diff options
author | Denis Bitouzé <dbitouze@wanadoo.fr> | 2021-02-25 18:23:07 +0000 |
---|---|---|
committer | Denis Bitouzé <dbitouze@wanadoo.fr> | 2021-02-25 18:23:07 +0000 |
commit | c6101f91d071883b48b1b4b51e5eba0f36d9a78d (patch) | |
tree | 1bf7f5a881d7a4f5c5bf59d0b2821943dd822372 /Build/source/texk/kpathsea/doc | |
parent | 07ee7222e389b0777456b427a55c22d0e6ffd267 (diff) |
French translation for tlmgr updated
git-svn-id: svn://tug.org/texlive/trunk@57912 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/kpathsea/doc')
-rw-r--r-- | Build/source/texk/kpathsea/doc/Makefile.am | 8 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/Makefile.in | 769 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/kpathsea.info | 4017 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/kpathsea.texi | 3931 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/unixtex.texi | 50 |
5 files changed, 0 insertions, 8775 deletions
diff --git a/Build/source/texk/kpathsea/doc/Makefile.am b/Build/source/texk/kpathsea/doc/Makefile.am deleted file mode 100644 index 92191e57c16..00000000000 --- a/Build/source/texk/kpathsea/doc/Makefile.am +++ /dev/null @@ -1,8 +0,0 @@ -## Makefile.am for the TeX Live subdirectory texk/kpathsea/doc/ -## -## Copyright (C) 2009-2014 Peter Breitenlohner <tex-live@tug.org> -## You may freely use, modify and/or distribute this file. -## -info_TEXINFOS = kpathsea.texi -kpathsea_TEXINFOS = unixtex.texi - diff --git a/Build/source/texk/kpathsea/doc/Makefile.in b/Build/source/texk/kpathsea/doc/Makefile.in deleted file mode 100644 index 3edd0ef5944..00000000000 --- a/Build/source/texk/kpathsea/doc/Makefile.in +++ /dev/null @@ -1,769 +0,0 @@ -# Makefile.in generated by automake 1.16.3 from Makefile.am. -# @configure_input@ - -# Copyright (C) 1994-2020 Free Software Foundation, Inc. - -# This Makefile.in is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY, to the extent permitted by law; without -# even the implied warranty of MERCHANTABILITY or FITNESS FOR A -# PARTICULAR PURPOSE. - -@SET_MAKE@ -VPATH = @srcdir@ -am__is_gnu_make = { \ - if test -z '$(MAKELEVEL)'; then \ - false; \ - elif test -n '$(MAKE_HOST)'; then \ - true; \ - elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ - true; \ - else \ - false; \ - fi; \ -} -am__make_running_with_option = \ - case $${target_option-} in \ - ?) ;; \ - *) echo "am__make_running_with_option: internal error: invalid" \ - "target option '$${target_option-}' specified" >&2; \ - exit 1;; \ - esac; \ - has_opt=no; \ - sane_makeflags=$$MAKEFLAGS; \ - if $(am__is_gnu_make); then \ - sane_makeflags=$$MFLAGS; \ - else \ - case $$MAKEFLAGS in \ - *\\[\ \ ]*) \ - bs=\\; \ - sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ - | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ - esac; \ - fi; \ - skip_next=no; \ - strip_trailopt () \ - { \ - flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ - }; \ - for flg in $$sane_makeflags; do \ - test $$skip_next = yes && { skip_next=no; continue; }; \ - case $$flg in \ - *=*|--*) continue;; \ - -*I) strip_trailopt 'I'; skip_next=yes;; \ - -*I?*) strip_trailopt 'I';; \ - -*O) strip_trailopt 'O'; skip_next=yes;; \ - -*O?*) strip_trailopt 'O';; \ - -*l) strip_trailopt 'l'; skip_next=yes;; \ - -*l?*) strip_trailopt 'l';; \ - -[dEDm]) skip_next=yes;; \ - -[JT]) skip_next=yes;; \ - esac; \ - case $$flg in \ - *$$target_option*) has_opt=yes; break;; \ - esac; \ - done; \ - test $$has_opt = yes -am__make_dryrun = (target_option=n; $(am__make_running_with_option)) -am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) -pkgdatadir = $(datadir)/@PACKAGE@ -pkgincludedir = $(includedir)/@PACKAGE@ -pkglibdir = $(libdir)/@PACKAGE@ -pkglibexecdir = $(libexecdir)/@PACKAGE@ -am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd -install_sh_DATA = $(install_sh) -c -m 644 -install_sh_PROGRAM = $(install_sh) -c -install_sh_SCRIPT = $(install_sh) -c -INSTALL_HEADER = $(INSTALL_DATA) -transform = $(program_transform_name) -NORMAL_INSTALL = : -PRE_INSTALL = : -POST_INSTALL = : -NORMAL_UNINSTALL = : -PRE_UNINSTALL = : -POST_UNINSTALL = : -build_triplet = @build@ -host_triplet = @host@ -subdir = doc -ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 -am__aclocal_m4_deps = $(top_srcdir)/../../m4/kpse-common.m4 \ - $(top_srcdir)/../../m4/kpse-lib-version.m4 \ - $(top_srcdir)/../../m4/kpse-mktex.m4 \ - $(top_srcdir)/../../m4/kpse-warnings.m4 \ - $(top_srcdir)/../../m4/kpse-win32.m4 \ - $(top_srcdir)/../../m4/libtool.m4 \ - $(top_srcdir)/../../m4/ltoptions.m4 \ - $(top_srcdir)/../../m4/ltsugar.m4 \ - $(top_srcdir)/../../m4/ltversion.m4 \ - $(top_srcdir)/../../m4/lt~obsolete.m4 $(top_srcdir)/version.ac \ - $(top_srcdir)/../../version.ac $(top_srcdir)/ac/mktex.ac \ - $(top_srcdir)/configure.ac -am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ - $(ACLOCAL_M4) -DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) -mkinstalldirs = $(install_sh) -d -CONFIG_HEADER = $(top_builddir)/c-auto.h -CONFIG_CLEAN_FILES = -CONFIG_CLEAN_VPATH_FILES = -AM_V_P = $(am__v_P_@AM_V@) -am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) -am__v_P_0 = false -am__v_P_1 = : -AM_V_GEN = $(am__v_GEN_@AM_V@) -am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) -am__v_GEN_0 = @echo " GEN " $@; -am__v_GEN_1 = -AM_V_at = $(am__v_at_@AM_V@) -am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) -am__v_at_0 = @ -am__v_at_1 = -SOURCES = -DIST_SOURCES = -AM_V_DVIPS = $(am__v_DVIPS_@AM_V@) -am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@) -am__v_DVIPS_0 = @echo " DVIPS " $@; -am__v_DVIPS_1 = -AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@) -am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@) -am__v_MAKEINFO_0 = @echo " MAKEINFO" $@; -am__v_MAKEINFO_1 = -AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@) -am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@) -am__v_INFOHTML_0 = @echo " INFOHTML" $@; -am__v_INFOHTML_1 = -AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@) -am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@) -am__v_TEXI2DVI_0 = @echo " TEXI2DVI" $@; -am__v_TEXI2DVI_1 = -AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@) -am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@) -am__v_TEXI2PDF_0 = @echo " TEXI2PDF" $@; -am__v_TEXI2PDF_1 = -AM_V_texinfo = $(am__v_texinfo_@AM_V@) -am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@) -am__v_texinfo_0 = -q -am__v_texinfo_1 = -AM_V_texidevnull = $(am__v_texidevnull_@AM_V@) -am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@) -am__v_texidevnull_0 = > /dev/null -am__v_texidevnull_1 = -INFO_DEPS = $(srcdir)/kpathsea.info -TEXINFO_TEX = $(top_srcdir)/../../build-aux/texinfo.tex -am__TEXINFO_TEX_DIR = $(top_srcdir)/../../build-aux -DVIS = kpathsea.dvi -PDFS = kpathsea.pdf -PSS = kpathsea.ps -HTMLS = kpathsea.html -TEXINFOS = kpathsea.texi -TEXI2DVI = texi2dvi -TEXI2PDF = $(TEXI2DVI) --pdf --batch -MAKEINFOHTML = $(MAKEINFO) --html -AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) -DVIPS = dvips -am__can_run_installinfo = \ - case $$AM_UPDATE_INFO_DIR in \ - n|no|NO) false;; \ - *) (install-info --version) >/dev/null 2>&1;; \ - esac -am__installdirs = "$(DESTDIR)$(infodir)" -am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; -am__vpath_adj = case $$p in \ - $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ - *) f=$$p;; \ - esac; -am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; -am__install_max = 40 -am__nobase_strip_setup = \ - srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` -am__nobase_strip = \ - for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" -am__nobase_list = $(am__nobase_strip_setup); \ - for p in $$list; do echo "$$p $$p"; done | \ - sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ - $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ - if (++n[$$2] == $(am__install_max)) \ - { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ - END { for (dir in files) print dir, files[dir] }' -am__base_list = \ - sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ - sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' -am__uninstall_files_from_dir = { \ - test -z "$$files" \ - || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ - || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ - $(am__cd) "$$dir" && rm -f $$files; }; \ - } -am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) -am__DIST_COMMON = $(kpathsea_TEXINFOS) $(srcdir)/Makefile.in \ - $(top_srcdir)/../../build-aux/texinfo.tex -DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) -ACLOCAL = @ACLOCAL@ -AMTAR = @AMTAR@ -AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ -AR = @AR@ -AS = @AS@ -AUTOCONF = @AUTOCONF@ -AUTOHEADER = @AUTOHEADER@ -AUTOMAKE = @AUTOMAKE@ -AWK = @AWK@ -CC = @CC@ -CCDEPMODE = @CCDEPMODE@ -CFLAGS = @CFLAGS@ -CPP = @CPP@ -CPPFLAGS = @CPPFLAGS@ -CYGPATH_W = @CYGPATH_W@ -DEFS = @DEFS@ -DEPDIR = @DEPDIR@ -DLLTOOL = @DLLTOOL@ -DSYMUTIL = @DSYMUTIL@ -DUMPBIN = @DUMPBIN@ -ECHO_C = @ECHO_C@ -ECHO_N = @ECHO_N@ -ECHO_T = @ECHO_T@ -EGREP = @EGREP@ -EXEEXT = @EXEEXT@ -FGREP = @FGREP@ -GREP = @GREP@ -INSTALL = @INSTALL@ -INSTALL_DATA = @INSTALL_DATA@ -INSTALL_PROGRAM = @INSTALL_PROGRAM@ -INSTALL_SCRIPT = @INSTALL_SCRIPT@ -INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ -KPSEVERSION = @KPSEVERSION@ -KPSE_LT_VERSINFO = @KPSE_LT_VERSINFO@ -LD = @LD@ -LDFLAGS = @LDFLAGS@ -LIBOBJS = @LIBOBJS@ -LIBS = @LIBS@ -LIBTOOL = @LIBTOOL@ -LIPO = @LIPO@ -LN_S = @LN_S@ -LTLIBOBJS = @LTLIBOBJS@ -LT_OBJDIR = @LT_OBJDIR@ -LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@ -MAINT = @MAINT@ -MAKEINFO = @MAKEINFO@ -MANIFEST_TOOL = @MANIFEST_TOOL@ -MKDIR_P = @MKDIR_P@ -NM = @NM@ -NMEDIT = @NMEDIT@ -OBJDUMP = @OBJDUMP@ -OBJEXT = @OBJEXT@ -OTOOL = @OTOOL@ -OTOOL64 = @OTOOL64@ -PACKAGE = @PACKAGE@ -PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ -PACKAGE_NAME = @PACKAGE_NAME@ -PACKAGE_STRING = @PACKAGE_STRING@ -PACKAGE_TARNAME = @PACKAGE_TARNAME@ -PACKAGE_URL = @PACKAGE_URL@ -PACKAGE_VERSION = @PACKAGE_VERSION@ -PATH_SEPARATOR = @PATH_SEPARATOR@ -RANLIB = @RANLIB@ -SED = @SED@ -SET_MAKE = @SET_MAKE@ -SHELL = @SHELL@ -STRIP = @STRIP@ -VERSION = @VERSION@ -WARNING_CFLAGS = @WARNING_CFLAGS@ -WEB2CVERSION = @WEB2CVERSION@ -abs_builddir = @abs_builddir@ -abs_srcdir = @abs_srcdir@ -abs_top_builddir = @abs_top_builddir@ -abs_top_srcdir = @abs_top_srcdir@ -ac_ct_AR = @ac_ct_AR@ -ac_ct_CC = @ac_ct_CC@ -ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ -am__include = @am__include@ -am__leading_dot = @am__leading_dot@ -am__quote = @am__quote@ -am__tar = @am__tar@ -am__untar = @am__untar@ -bindir = @bindir@ -build = @build@ -build_alias = @build_alias@ -build_cpu = @build_cpu@ -build_os = @build_os@ -build_vendor = @build_vendor@ -builddir = @builddir@ -datadir = @datadir@ -datarootdir = @datarootdir@ -docdir = @docdir@ -dvidir = @dvidir@ -exec_prefix = @exec_prefix@ -host = @host@ -host_alias = @host_alias@ -host_cpu = @host_cpu@ -host_os = @host_os@ -host_vendor = @host_vendor@ -htmldir = @htmldir@ -includedir = @includedir@ -infodir = @infodir@ -install_sh = @install_sh@ -libdir = @libdir@ -libexecdir = @libexecdir@ -localedir = @localedir@ -localstatedir = @localstatedir@ -mandir = @mandir@ -mkdir_p = @mkdir_p@ -oldincludedir = @oldincludedir@ -pdfdir = @pdfdir@ -prefix = @prefix@ -program_transform_name = @program_transform_name@ -psdir = @psdir@ -sbindir = @sbindir@ -sharedstatedir = @sharedstatedir@ -srcdir = @srcdir@ -sysconfdir = @sysconfdir@ -target_alias = @target_alias@ -top_build_prefix = @top_build_prefix@ -top_builddir = @top_builddir@ -top_srcdir = @top_srcdir@ -info_TEXINFOS = kpathsea.texi -kpathsea_TEXINFOS = unixtex.texi -all: all-am - -.SUFFIXES: -.SUFFIXES: .dvi .html .info .pdf .ps .texi -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) - @for dep in $?; do \ - case '$(am__configure_deps)' in \ - *$$dep*) \ - ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ - && { if test -f $@; then exit 0; else break; fi; }; \ - exit 1;; \ - esac; \ - done; \ - echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \ - $(am__cd) $(top_srcdir) && \ - $(AUTOMAKE) --foreign doc/Makefile -Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status - @case '$?' in \ - *config.status*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ - *) \ - echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \ - cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \ - esac; - -$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh - -$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh -$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh -$(am__aclocal_m4_deps): - -mostlyclean-libtool: - -rm -f *.lo - -clean-libtool: - -rm -rf .libs _libs - -.texi.info: - $(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \ - am__cwd=`pwd` && $(am__cd) $(srcdir) && \ - rm -rf $$backupdir && mkdir $$backupdir && \ - if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ - for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ - if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ - done; \ - else :; fi && \ - cd "$$am__cwd"; \ - if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $@ $<; \ - then \ - rc=0; \ - $(am__cd) $(srcdir); \ - else \ - rc=$$?; \ - $(am__cd) $(srcdir) && \ - $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ - fi; \ - rm -rf $$backupdir; exit $$rc - -.texi.dvi: - $(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \ - $< - -.texi.pdf: - $(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \ - $< - -.texi.html: - $(AM_V_MAKEINFO)rm -rf $(@:.html=.htp) - $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $(@:.html=.htp) $<; \ - then \ - rm -rf $@ && mv $(@:.html=.htp) $@; \ - else \ - rm -rf $(@:.html=.htp); exit 1; \ - fi -$(srcdir)/kpathsea.info: kpathsea.texi $(kpathsea_TEXINFOS) -kpathsea.dvi: kpathsea.texi $(kpathsea_TEXINFOS) -kpathsea.pdf: kpathsea.texi $(kpathsea_TEXINFOS) -kpathsea.html: kpathsea.texi $(kpathsea_TEXINFOS) -.dvi.ps: - $(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - $(DVIPS) $(AM_V_texinfo) -o $@ $< - -uninstall-dvi-am: - @$(NORMAL_UNINSTALL) - @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ - for p in $$list; do \ - $(am__strip_dir) \ - echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ - rm -f "$(DESTDIR)$(dvidir)/$$f"; \ - done - -uninstall-html-am: - @$(NORMAL_UNINSTALL) - @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ - for p in $$list; do \ - $(am__strip_dir) \ - echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ - rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ - done - -uninstall-info-am: - @$(PRE_UNINSTALL) - @if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ - if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ - then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ - done; \ - else :; fi - @$(NORMAL_UNINSTALL) - @list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ - (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ - echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ - rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ - else :; fi); \ - done - -uninstall-pdf-am: - @$(NORMAL_UNINSTALL) - @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ - for p in $$list; do \ - $(am__strip_dir) \ - echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ - rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ - done - -uninstall-ps-am: - @$(NORMAL_UNINSTALL) - @list='$(PSS)'; test -n "$(psdir)" || list=; \ - for p in $$list; do \ - $(am__strip_dir) \ - echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ - rm -f "$(DESTDIR)$(psdir)/$$f"; \ - done - -dist-info: $(INFO_DEPS) - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - list='$(INFO_DEPS)'; \ - for base in $$list; do \ - case $$base in \ - $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ - esac; \ - if test -f $$base; then d=.; else d=$(srcdir); fi; \ - base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ - for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ - if test -f $$file; then \ - relfile=`expr "$$file" : "$$d/\(.*\)"`; \ - test -f "$(distdir)/$$relfile" || \ - cp -p $$file "$(distdir)/$$relfile"; \ - else :; fi; \ - done; \ - done - -mostlyclean-aminfo: - -rm -rf kpathsea.t2d kpathsea.t2p - -clean-aminfo: - -test -z "kpathsea.dvi kpathsea.pdf kpathsea.ps kpathsea.html" \ - || rm -rf kpathsea.dvi kpathsea.pdf kpathsea.ps kpathsea.html - -maintainer-clean-aminfo: - @list='$(INFO_DEPS)'; for i in $$list; do \ - i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ - echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ - rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ - done -tags TAGS: - -ctags CTAGS: - -cscope cscopelist: - - -distdir: $(BUILT_SOURCES) - $(MAKE) $(AM_MAKEFLAGS) distdir-am - -distdir-am: $(DISTFILES) - @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ - topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ - list='$(DISTFILES)'; \ - dist_files=`for file in $$list; do echo $$file; done | \ - sed -e "s|^$$srcdirstrip/||;t" \ - -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ - case $$dist_files in \ - */*) $(MKDIR_P) `echo "$$dist_files" | \ - sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ - sort -u` ;; \ - esac; \ - for file in $$dist_files; do \ - if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ - if test -d $$d/$$file; then \ - dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ - if test -d "$(distdir)/$$file"; then \ - find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ - fi; \ - if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ - cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ - find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ - fi; \ - cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ - else \ - test -f "$(distdir)/$$file" \ - || cp -p $$d/$$file "$(distdir)/$$file" \ - || exit 1; \ - fi; \ - done - $(MAKE) $(AM_MAKEFLAGS) \ - top_distdir="$(top_distdir)" distdir="$(distdir)" \ - dist-info -check-am: all-am -check: check-am -all-am: Makefile $(INFO_DEPS) -installdirs: - for dir in "$(DESTDIR)$(infodir)"; do \ - test -z "$$dir" || $(MKDIR_P) "$$dir"; \ - done -install: install-am -install-exec: install-exec-am -install-data: install-data-am -uninstall: uninstall-am - -install-am: all-am - @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am - -installcheck: installcheck-am -install-strip: - if test -z '$(STRIP)'; then \ - $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ - install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ - install; \ - else \ - $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ - install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ - "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ - fi -mostlyclean-generic: - -clean-generic: - -distclean-generic: - -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) - -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) - -maintainer-clean-generic: - @echo "This command is intended for maintainers to use" - @echo "it deletes files that may require special tools to rebuild." -clean: clean-am - -clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am - -distclean: distclean-am - -rm -f Makefile -distclean-am: clean-am distclean-generic - -dvi: dvi-am - -dvi-am: $(DVIS) - -html: html-am - -html-am: $(HTMLS) - -info: info-am - -info-am: $(INFO_DEPS) - -install-data-am: install-info-am - -install-dvi: install-dvi-am - -install-dvi-am: $(DVIS) - @$(NORMAL_INSTALL) - @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ - if test -n "$$list"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \ - $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \ - fi; \ - for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - echo "$$d$$p"; \ - done | $(am__base_list) | \ - while read files; do \ - echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ - $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ - done -install-exec-am: - -install-html: install-html-am - -install-html-am: $(HTMLS) - @$(NORMAL_INSTALL) - @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ - if test -n "$$list"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \ - $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \ - fi; \ - for p in $$list; do \ - if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ - $(am__strip_dir) \ - d2=$$d$$p; \ - if test -d "$$d2"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ - $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ - echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \ - $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ - else \ - list2="$$list2 $$d2"; \ - fi; \ - done; \ - test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ - while read files; do \ - echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ - $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ - done; } -install-info: install-info-am - -install-info-am: $(INFO_DEPS) - @$(NORMAL_INSTALL) - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ - if test -n "$$list"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \ - $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \ - fi; \ - for file in $$list; do \ - case $$file in \ - $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ - esac; \ - if test -f $$file; then d=.; else d=$(srcdir); fi; \ - file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ - for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ - $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ - if test -f $$ifile; then \ - echo "$$ifile"; \ - else : ; fi; \ - done; \ - done | $(am__base_list) | \ - while read files; do \ - echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ - $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done - @$(POST_INSTALL) - @if $(am__can_run_installinfo); then \ - list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ - install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ - done; \ - else : ; fi -install-man: - -install-pdf: install-pdf-am - -install-pdf-am: $(PDFS) - @$(NORMAL_INSTALL) - @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ - if test -n "$$list"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \ - $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \ - fi; \ - for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - echo "$$d$$p"; \ - done | $(am__base_list) | \ - while read files; do \ - echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ - $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done -install-ps: install-ps-am - -install-ps-am: $(PSS) - @$(NORMAL_INSTALL) - @list='$(PSS)'; test -n "$(psdir)" || list=; \ - if test -n "$$list"; then \ - echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \ - $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \ - fi; \ - for p in $$list; do \ - if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - echo "$$d$$p"; \ - done | $(am__base_list) | \ - while read files; do \ - echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ - $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done -installcheck-am: - -maintainer-clean: maintainer-clean-am - -rm -f Makefile -maintainer-clean-am: distclean-am maintainer-clean-aminfo \ - maintainer-clean-generic - -mostlyclean: mostlyclean-am - -mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \ - mostlyclean-libtool - -pdf: pdf-am - -pdf-am: $(PDFS) - -ps: ps-am - -ps-am: $(PSS) - -uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ - uninstall-pdf-am uninstall-ps-am - -.MAKE: install-am install-strip - -.PHONY: all all-am check check-am clean clean-aminfo clean-generic \ - clean-libtool cscopelist-am ctags-am dist-info distclean \ - distclean-generic distclean-libtool distdir dvi dvi-am html \ - html-am info info-am install install-am install-data \ - install-data-am install-dvi install-dvi-am install-exec \ - install-exec-am install-html install-html-am install-info \ - install-info-am install-man install-pdf install-pdf-am \ - install-ps install-ps-am install-strip installcheck \ - installcheck-am installdirs maintainer-clean \ - maintainer-clean-aminfo maintainer-clean-generic mostlyclean \ - mostlyclean-aminfo mostlyclean-generic mostlyclean-libtool pdf \ - pdf-am ps ps-am tags-am uninstall uninstall-am \ - uninstall-dvi-am uninstall-html-am uninstall-info-am \ - uninstall-pdf-am uninstall-ps-am - -.PRECIOUS: Makefile - - -# Tell versions [3.59,3.63) of GNU make to not export all variables. -# Otherwise a system limit (for SysV at least) may be exceeded. -.NOEXPORT: diff --git a/Build/source/texk/kpathsea/doc/kpathsea.info b/Build/source/texk/kpathsea/doc/kpathsea.info deleted file mode 100644 index 66b0a4e2f90..00000000000 --- a/Build/source/texk/kpathsea/doc/kpathsea.info +++ /dev/null @@ -1,4017 +0,0 @@ -This is kpathsea.info, produced by makeinfo version 5.1 from -kpathsea.texi. - -This file documents the Kpathsea library for path searching. - - Copyright (C) 1996-2021 Karl Berry & Olaf Weber. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the TeX Users Group. -INFO-DIR-SECTION TeX -START-INFO-DIR-ENTRY -* Kpathsea: (kpathsea). File lookup along search paths. -* kpsewhich: (kpathsea)Invoking kpsewhich. TeX file searching. -* mktexfmt: (kpathsea)mktex scripts. Format (fmt/base/mem) generation. -* mktexlsr: (kpathsea)Filename database. Update ls-R. -* mktexmf: (kpathsea)mktex scripts. MF source generation. -* mktexpk: (kpathsea)mktex scripts. PK bitmap generation. -* mktextex: (kpathsea)mktex scripts. TeX source generation. -* mktextfm: (kpathsea)mktex scripts. TeX font metric generation. -END-INFO-DIR-ENTRY - - -File: kpathsea.info, Node: Top, Next: Introduction, Up: (dir) - -Kpathsea library -**************** - -This manual documents the Kpathsea library for path searching. It -corresponds to version 6.3.3, released in February 2021. - -* Menu: - -* Introduction:: Overview and history. - -* unixtex.ftp:: Obtaining TeX software. -* Security:: Who can write what files, etc. -* TeX directory structure:: Managing the horde of TeX input files. - -* Path searching:: How filename lookups work. -* TeX support:: Special support for TeX-related file lookups. - -* Programming:: How to use Kpathsea features in your program. - -* Reporting bugs:: Where and how to report bugs. -* Index:: General index. - - -File: kpathsea.info, Node: Introduction, Next: unixtex.ftp, Prev: Top, Up: Top - -1 Introduction -************** - -This manual corresponds to version 6.3.3 of the Kpathsea library, -released in February 2021. - - The library's fundamental purpose is to return a filename from a list -of directories specified by the user, similar to what shells do when -looking up program names to execute. - - The following software, all of which is maintained in parallel, uses -this library: - - * Dviljk (see the 'dvilj' man page) - * Dvipsk (*note (dvips)::) - * GNU font utilities (*note (fontu)::) - * Web2c (*note (web2c)::) - * Xdvik (see the 'xdvi' man page) - -Other software that we do not maintain also uses it. - - Kpathsea is now maintained as part of the TeX Live distribution -(<https://tug.org/texlive>), which includes several more Kpathsea-using -programs. For information on configuration, building, installing, and -more, *note (tlbuild)::. - - The library is still actively maintained. If you have comments or -suggestions, please send along (*note Reporting bugs::). - - The Kpathsea library is distributed under the GNU Library General -Public License (LGPL), version 2.1 or (at your option) any later -version. In short, this means if you write a program using the library, -you must (offer to) distribute the source to the library, along with any -changes you have made, and allow anyone to modify the library source and -distribute their modifications. It does not mean you have to distribute -the source to your program using the library, although we hope you will. -See accompanying files for the text of the GNU licenses, or -<https://gnu.org/licenses>. - - If you know enough about TeX to be reading this manual, then you (or -your institution) should consider joining the TeX Users Group (if you're -already a member, thanks!). TUG produces the periodical 'TUGboat', -sponsors an annual meeting and publishes the proceedings, and arranges -courses on TeX for all levels of users throughout the world. See -<https://tug.org> for information. - -* Menu: - -* History:: - - -File: kpathsea.info, Node: History, Up: Introduction - -1.1 History -=========== - -This section is for those people who are curious about how the library -came about. If you like to read historical accounts of software, we -urge you to seek out the GNU Autoconf manual and the "Errors of TeX" -paper by Don Knuth, published in his book 'Digital Typography', among -other places. - - [Karl writes.] My first ChangeLog entry for Web2c seems to be -February 1990, but I may have done some work before then. In any case, -Tim Morgan and I were jointly maintaining it for a time. (I should -mention here that Tim had made Web2c into a real distribution long -before I had ever used it or even heard of it, and Tom Rokicki did the -original implementation. When I started, I was using 'pxp' and 'pc' on -VAX 11/750's and the hot new Sun 2 machines.) - - It must have been later in 1990 and 1991 that I started working on -'TeX for the Impatient'. Dvips, Xdvi, Web2c, and the GNU fontutils -(which I was also writing at the time) all used different environment -variables, and, more importantly, had different bugs in their path -searching. This became extremely painful, as I was stressing everything -to the limit working on the book. I also desperately wanted to -implement subdirectory searching, since I couldn't stand putting -everything in one big directory, and also couldn't stand having to -explicitly specify 'cm', 'pandora', ... in a path. - - In the first incarnation, I just hacked separately on each -program--that was the original subdirectory searching code in both Xdvi -and Dvips. That is, I tried to go with the flow in each program, rather -than changing the program's calling sequences to conform to new -routines. - - Then, as bugs inevitably appeared, I found I was fixing the same -thing three times (Web2c and fontutils were already sharing code, since -I maintained both of those--there was no Dvipsk or Xdvik or Dviljk at -this point). After a while, I finally started sharing source files. -They weren't yet a library, though. I just kept things up to date with -shell scripts. (I was developing on a 386 running ISC 2.2 at the time, -and so didn't have symbolic links. An awful experience.) - - The ChangeLogs for Xdvik and Dvipsk record initial releases of those -distributions in May and June 1992. I think it was because I was tired -of the different configuration strategies of each program, not so much -because of the path searching. Autoconf was being developed by David -MacKenzie and others, and I was adapting it to TeX and friends. - - I started to make a separate library that other programs could link -with on my birthday in April 1993, according to the ChangeLog. I don't -remember exactly why I finally took the time to make it a separate -library; a conversation with david zuhn initiated it. Just seemed like -it was time. - - Dviljk got started in March 1994 after I bought a Laserjet 4. -(Kpathsea work got suspended while Norm Walsh and I, with Gustaf -Neumann's help, implemented a way for TeX to get at all those neat -builtin LJ4 fonts ... such a treat to have something to typeset in -besides Palatino!) - - By spring of 1995, I had implemented just about all the -path-searching features in Kpathsea that I plan to, driven beyond my -initial goals by Thomas Esser and others. I then started to integrate -Web2c with Kpathsea. After the release of a stable Web2c, I hope to be -able to stop development, and turn most of my attention back to making -fonts for GNU. (Always assuming Micros**t hasn't completely obliterated -Unix by then, or that software patents haven't stopped software -development by anybody smaller than a company with a -million-dollar-a-year legal budget. Which is actually what I think is -likely to happen, but that's another story...) - - [Olaf writes.] At the end of 1997, Unix is still alive and kicking, -individuals still develop software, and Web2c development still -continues. Karl had been looking for some time for someone to take up -part of the burden, and I volunteered. - - [Karl writes again.] Indeed, time goes on. As of 2006 or so, Olaf's -available time for Kpathsea was reduced, and I started taking overall -care of it again, although I did not do any significant new development. -In 2009, Taco Hoekwater implemented a major rearrangement to make the -library suitable for use within the MetaPost library (*note Programming -overview::). Also, for some years now, Peter Breitenlohner has made -many improvements to the infrastructure and kept it up-to-date with -respect to the overall TeX Live build, where Kpathsea is now maintained. - - -File: kpathsea.info, Node: unixtex.ftp, Next: Security, Prev: Introduction, Up: Top - -2 'unixtex.ftp': Obtaining TeX -****************************** - -This is <ftp://tug.org/tex/unixtex.ftp>, a.k.a. -<https://tug.org/unixtex.ftp>, last updated 29 February 2020. Email -<tex-k@tug.org> with comments or questions. - - The principal free TeX distribution for Unix-like systems is TeX -Live, on the web at <http://tug.org/texlive>. The pages there describe -many ways to acquire and/or build TeX, over the Internet or on physical -media, both the sources and precompiled binaries for many systems, -either standalone or as part of various operating system distributions. - - Web2c, Kpathsea, Dvips, and Dviljk, among others, are no longer -released as a separate packages. Their sources are now maintained as -part of TeX Live. - - The host ftp.cs.stanford.edu is the original source for the files for -which Donald Knuth is directly responsible: 'tex.web', 'plain.tex', etc. -However, unless you want to undertake the project of building your TeX -system from scratch, it is more reliable and less work to retrieve these -files as part of a larger package. - - In any case, the Stanford ftp site is not the canonical source for -anything except what was created as part of Knuth's original TeX, so do -not rely on any other files available there being up-to-date. The best -place to check for up-to-date files is CTAN (the Comprehensive TeX -Archive Network), <https://ctan.org>. - - -File: kpathsea.info, Node: Security, Next: TeX directory structure, Prev: unixtex.ftp, Up: Top - -3 Security -********** - -None of the programs in the TeX system require any special system -privileges, so there's no first-level security concern of people gaining -illegitimate root access. - - A TeX document, however, can write to arbitrary files, e.g., -'~/.rhosts', and thus an unwitting user who runs TeX on a random -document is vulnerable to a trojan horse attack. This loophole is -closed by default, but you can be permissive if you so desire in -'texmf.cnf'. *Note (web2c)tex invocation::. MetaPost has the same -issue. - - Dvips, Xdvi, and TeX can also execute shell commands under some -circumstances. To disable this, see the '-R' option in *note -(dvips)Option details::, the xdvi man page, and *note (web2c)tex -invocation::, respectively. - - Another security issue arises because it's very useful--almost -necessary--to make arbitrary fonts on user demand with 'mktexpk' and -friends. Where do these files get installed? By default, the 'mktexpk' -distributed with Kpathsea assumes a world-writable '/var/tmp' directory; -this is a simple and convenient approach, but it may not suit your -situation because it means that a local cache of fonts is created on -every machine. - - To avoid this duplication, many people consider a shared, globally -writable font tree desirable, in spite of the potential security -problems. To do this you should change the value of 'VARTEXFONTS' in -'texmf.cnf' to refer to some globally known directory. *Note mktex -configuration::. - - The first restriction you can apply is to make newly-created -directories under 'texmf' be append-only with an option in 'mktex.cnf'. -*Note mktex configuration::. - - Another approach is to establish a group (or user) for TeX files, -make the 'texmf' tree writable only to that group (or user), and make -'mktexpk' et al. setgid to that group (or setuid to that user). Then -users must invoke the scripts to install things. (If you're worried -about the inevitable security holes in scripts, then you could write a C -wrapper to exec the script.) - - The 'mktex...' scripts install files with the same read and write -permissions as the directory they are installed in. The executable, -sgid, suid, and sticky bits are always cleared. - - Any directories created by the 'mktex...' scripts have the same -permissions as their parent directory, unless the 'appendonlydir' -feature is used, in which case the sticky bit is always set. - - -File: kpathsea.info, Node: TeX directory structure, Next: Path searching, Prev: Security, Up: Top - -4 TeX directory structure -************************* - -This section describes the default installation hierarchy of the -distribution. It conforms to both the GNU coding standards and the TeX -directory structure (TDS) standard. For rationale and further -explanation, please see those documents. The GNU document is available -from <https://gnu.org/prep/standards>. The TDS document is available -from <http://mirror.ctan.org/tds> (*note unixtex.ftp::). - - In short, here is a skeleton of the default directory structure, -extracted from the TDS document: - - PREFIX/ installation root ('/usr/local' by default) - bin/ executables - man/ man pages - include/ C header files - info/ GNU info files - lib/ libraries ('libkpathsea.*') - share/ architecture-independent files - texmf/ TDS root - bibtex/ BibTeX input files - bib/ BibTeX databases - base/ base distribution (e.g., 'xampl.bib') - misc/ single-file databases - PKG/ name of a package - bst/ BibTeX style files - base/ base distribution (e.g., 'plain.bst', 'acm.bst') - misc/ single-file styles - PKG/ name of a package - doc/ additional documentation - dvips/ '.pro', '.ps', 'psfonts.map' - fonts/ font-related files - TYPE/ file type (e.g., 'tfm', 'pk') - MODE/ type of output device (types 'pk' and 'gf' only) - SUPPLIER/ name of a font supplier (e.g., 'public') - TYPEFACE/ name of a typeface (e.g., 'cm') - dpiNNN/ font resolution (types 'pk' and 'gf' only) - metafont/ Metafont (non-font) input files - base/ base distribution (e.g., 'plain.mf') - misc/ single-file packages (e.g., 'modes.mf') - PKG/ name of a package (e.g., 'mfpic') - metapost/ MetaPost input files - base/ base distribution (e.g., 'plain.mp') - misc/ single-file packages - PKG/ name of a package - support/ support files for MetaPost-related utilities (e.g., 'trfonts.map') - mft/ 'MFT' inputs (e.g., 'plain.mft') - tex/ TeX input files - FORMAT/ name of a format (e.g., 'plain') - base/ base distribution for FORMAT (e.g., 'plain.tex') - misc/ single-file packages (e.g., 'webmac.tex') - local/ local additions to or local configuration files for FORMAT - PKG/ name of a package (e.g., 'graphics', 'mfnfss') - generic/ format-independent packages - hyphen/ hyphenation patterns (e.g., 'hyphen.tex') - images/ image input files (e.g., Encapsulated PostScript) - misc/ single-file format-independent packages (e.g., 'null.tex'). - PKG/ name of a package (e.g., 'babel') - web2c/ implementation-dependent files ('.pool', '.fmt', 'texmf.cnf', etc.) - - Some concrete examples for most file types: - - /usr/local/bin/tex - /usr/local/man/man1/xdvi.1 - /usr/local/info/kpathsea.info - /usr/local/lib/libkpathsea.a - /usr/local/share/texmf/bibtex/bst/base/plain.bst - /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk - /usr/local/share/texmf/fonts/source/public/pandora/pnr10.mf - /usr/local/share/texmf/fonts/tfm/public/cm/cmr10.tfm - /usr/local/share/texmf/fonts/type1/adobe/utopia/putr.pfa - /usr/local/share/texmf/metafont/base/plain.mf - /usr/local/share/texmf/metapost/base/plain.mp - /usr/local/share/texmf/tex/plain/base/plain.tex - /usr/local/share/texmf/tex/generic/hyphen/hyphen.tex - /usr/local/share/texmf/web2c/tex.pool - /usr/local/share/texmf/web2c/tex.fmt - /usr/local/share/texmf/web2c/texmf.cnf - - -File: kpathsea.info, Node: Path searching, Next: TeX support, Prev: TeX directory structure, Up: Top - -5 Path searching -**************** - -This chapter describes the generic path searching mechanism Kpathsea -provides. For information about searching for particular file types -(e.g., TeX fonts), see the next chapter. - - This section, with minor differences, has been translated into -several other languages (Chinese, Spanish, Russian, Japanese, French, -German, ...) as part of the TeX Live guide; see -<https://tug.org/texlive/doc.html> for links. - -* Menu: - -* Searching overview:: Basic scheme for searching. -* Path sources:: Where search paths can be defined. -* Path expansion:: Special constructs in search paths. -* Casefolding search:: Fallback to case-insensitive search. -* Filename database:: Using an externally-built list to search. -* Invoking kpsewhich:: Standalone path lookup. - - -File: kpathsea.info, Node: Searching overview, Next: Path sources, Up: Path searching - -5.1 Searching overview -====================== - -A "search path" is a colon-separated list of "path elements", which are -directory names with a few extra frills. A search path can come from (a -combination of) many sources; see below. To look up a file 'foo' along -a path '.:/dir', Kpathsea checks each element of the path in turn: first -'./foo', then '/dir/foo', returning the first match (or possibly all -matches). - - The "colon" and "slash" mentioned here aren't necessarily ':' and '/' -on non-Unix systems. Kpathsea tries to adapt to other operating -systems' conventions. - - To check a particular path element E, Kpathsea first sees if a -prebuilt database (*note Filename database::) applies to E, i.e., if the -database is in a directory that is a prefix of E. If so, the path -specification is matched against the contents of the database. - - If the database does not exist, or does not apply to this path -element, or contains no matches, the filesystem is searched (if this was -not forbidden by the specification with '!!' and if the file being -searched for must exist). Kpathsea constructs the list of directories -that correspond to this path element, and then checks in each for the -file being searched for. (To help speed future lookups of files in the -same directory, the directory in which a file is found is floated to the -top of the directory list.) - - The "file must exist" condition comes into play with VF files and -input files read by the TeX '\openin' command. These files might very -well not exist (consider 'cmr10.vf'), and so it would be wrong to search -the disk for them. Therefore, if you fail to update 'ls-R' when you -install a new VF file, it will not be found. - - Each path element is checked in turn: first the database, then the -disk. If a match is found, the search stops and the result is returned -(unless the search explicitly requested all matches). This avoids -possibly-expensive processing of path specifications that are never -needed on a particular run. - - On Unix-like systems, if no match is found by any of the above, and -the path element allows checking the filesystem (per the above), a final -check is made for a case-insensitive match. Thus, looking for a name -like './FooBar.TeX' will match a file './foobar.tex', and vice versa. -This is not done on Windows. *Note Casefolding search::. - - Although the simplest and most common path element is a directory -name, Kpathsea supports additional features in search paths: layered -default values, environment variable names, config file values, users' -home directories, and recursive subdirectory searching. Thus, we say -that Kpathsea "expands" a path element, meaning transforming all the -magic specifications into the basic directory name or names. This -process is described in the sections below. It happens in the same -order as the sections. - - Exception to all of the above: If the filename being searched for is -absolute or explicitly relative, i.e., starts with '/' or './' or '../', -Kpathsea simply checks if that file exists, with a fallback to a -casefolding match if needed and enabled, as described above. - - Ordinarily, if Kpathsea tries to access a file or directory that -cannot be read, it gives a warning. This is so you will be alerted to -directories or files that accidentally lack any read permission (for -example, a 'lost+found' directory). If you prefer not to see these -warnings, include the value 'readable' in the 'TEX_HUSH' environment -variable or config file value. - - This generic path searching algorithm is implemented in -'kpathsea/pathsearch.c'. It is employed by a higher-level algorithm -when searching for a file of a particular type (*note File lookup::, and -*note Glyph lookup::). - - -File: kpathsea.info, Node: Path sources, Next: Path expansion, Prev: Searching overview, Up: Path searching - -5.2 Path sources -================ - -A search path or other configuration value can come from many sources. -In the order in which Kpathsea looks for them: - - 1. A command-line option such as '--cnf-line', available in - 'kpsewhich' and most TeX engines. *Note Path searching options::. - - A user-set environment variable, e.g., 'TEXINPUTS'. Environment - variables with an underscore and the program name appended - override; for example, 'TEXINPUTS_latex' overrides 'TEXINPUTS' if - the program being run is named 'latex'. - - 2. A program-specific configuration file, e.g., an 'S /a:/b' line in - Dvips' 'config.ps' (*note (dvips)Config files::). - - 3. A line in a Kpathsea configuration file 'texmf.cnf', e.g., - 'TEXINPUTS=/c:/d' (see below). - - 4. The compile-time default (specified in 'kpathsea/paths.h'). - - You can see each of these values for a given search path by using the -debugging options (*note Debugging::). - - These sources may be combined via default expansion (*note Default -expansion::). - -* Menu: - -* Config files:: Kpathsea's runtime config files (texmf.cnf). - - -File: kpathsea.info, Node: Config files, Up: Path sources - -5.2.1 Config files ------------------- - -As mentioned above, Kpathsea reads "runtime configuration files" named -'texmf.cnf' for search path and other definitions. The search path used -to look for these configuration files is named 'TEXMFCNF', and is -constructed in the usual way, as described above, except that -configuration files cannot be used to define the path, naturally; also, -an 'ls-R' database is not used to search for them. - - Kpathsea reads _all_ 'texmf.cnf' files in the search path, not just -the first one found; definitions in earlier files override those in -later files. Thus, if the search path is '.:$TEXMF', values from -'./texmf.cnf' override those from '$TEXMF/texmf.cnf'. - - If Kpathsea cannot find any 'texmf.cnf' file, it reports a warning -including all the directories it checked. If you don't want to see this -warning, set the environment variable 'KPATHSEA_WARNING' to the single -character '0' (zero, not oh). - - While (or instead of) reading this description, you may find it -helpful to look at the distributed 'texmf.cnf', which uses or at least -mentions most features. The format of 'texmf.cnf' files follows: - - * Comments start with '%', either at the beginning of a line or - preceded by whitespace, and continue to the end of the line. That - is, similar to most shells, a '%' in the "middle" of a value does - not start a comment. Examples: - - % this is a comment - var = a%b % but the value of var will be "a%b" - - * Blank lines are ignored. - - * A '\' at the end of a line acts as a continuation character, i.e., - the next line is appended. Whitespace at the beginning of - continuation lines is not ignored. - - * Each remaining line will look like: - - VARIABLE [. PROGNAME] [=] VALUE - - where the '=' and surrounding whitespace is optional. - - * The VARIABLE name may contain any character other than whitespace, - '=', or '.', but sticking to 'A-Za-z_' is safest. - - * If '.PROGNAME' is present (preceding spaces are ignored), the - definition only applies if the program that is running is named - (i.e., the last component of 'argv[0]' is) PROGNAME or - 'PROGNAME.{exe,bat,cmd,...}'. Most notably, this allows different - flavors of TeX to have different search paths. The PROGNAME value - is used literally, without variable or other expansions. - - * Considered as strings, VALUE may contain any character. However, - in practice most 'texmf.cnf' values are related to path expansion, - and since various special characters are used in expansion, such as - braces and commas, they cannot be used in directory names. - - The '$VAR.PROG' feature is not available on the right-hand side; - instead, you must use an additional variable (see below for - example). - - A ';' in VALUE is translated to ':' if running under Unix, in order - to have a single 'texmf.cnf' that can support both Unix and Windows - systems. This translation happens with any value, not just search - paths, but fortunately in practice ';' is not needed in other - values. - - * All definitions are read before anything is expanded, so you can - use variables before they are defined (like Make, unlike most other - programs). - -Here is a configuration file fragment illustrating most of these points: - - % TeX input files -- i.e., anything to be found by \input or \openin ... - latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex// - latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex// - TEXINPUTS = .:$TEXMF/tex// - TEXINPUTS.latex209 = $latex209_inputs - TEXINPUTS.latex2e = $latex2e_inputs - TEXINPUTS.latex = $latex2e_inputs - - This format has some similarity to Bourne shell scripts--change the -comment character to '#', disallow spaces around the '=', and get rid of -the '.NAME' convention, and it could be run through the shell. However, -there seemed little advantage in this, since all the information would -have to passed back to Kpathsea and parsed there anyway, since the 'sh' -process couldn't affect its parent's environment. - - The combination of spaces being ignored before the '.' of a program -name qualifer and the optional '=' for the assignment has an unexpected -consequence: if the value begins with a literal '.' and the '=' is -omitted, the intended value is interpreted as a program name. For -example, a line 'var .;/some/path' is taken as an empty value for 'var' -running under the program named ';/some/path'. To diagnose this, -Kpathsea warns if the program name contains a path separator or other -special character. The simplest way to avoid the problem is to use the -'='. - - Exactly when a character will be considered special or act as itself -depends on the context in which it is used. The rules are inherent in -the multiple levels of interpretation of the configuration (parsing, -expansion, search, ...) and so cannot be concisely stated, -unfortunately. There is no general escape mechanism; in particular, '\' -is not an "escape character" in 'texmf.cnf' files. When it comes -choosing directory names for installation, it is safest to avoid them -all. - - The implementation of all this is in 'kpathsea/cnf.c'. - - -File: kpathsea.info, Node: Path expansion, Next: Casefolding search, Prev: Path sources, Up: Path searching - -5.3 Path expansion -================== - -Kpathsea recognizes certain special characters and constructions in -search paths, similar to that in shells. As a general example: -'~$USER/{foo,bar}//baz' expands to all subdirectories under directories -'foo' and 'bar' in $USER's home directory that contain a directory or -file 'baz'. - - These expansions are explained in the sections below. - -* Menu: - -* Default expansion:: a: or :a or a::b expands to a default. -* Variable expansion:: $foo and ${foo} expand to environment values. -* Tilde expansion:: ~ and ~user expand to home directories. -* Brace expansion:: a{foo,bar}b expands to afoob abarb. -* KPSE_DOT expansion:: . is replaced with $KPSE_DOT if it is defined. -* Subdirectory expansion:: a// and a//b recursively expand to subdirs. - - -File: kpathsea.info, Node: Default expansion, Next: Variable expansion, Up: Path expansion - -5.3.1 Default expansion ------------------------ - -If the highest-priority search path (*note Path sources::) contains an -"extra colon" (i.e., leading, trailing, or doubled), Kpathsea inserts at -that point the next-highest-priority search path that is defined. If -that inserted path has an extra colon, the same happens with the -next-highest. (An extra colon in the compile-time default value has -unpredictable results, so installers beware.) - - For example, given an environment variable setting - - setenv TEXINPUTS /home/karl: - -and a 'TEXINPUTS' value from 'texmf.cnf' of - - .:$TEXMF//tex - -then the final value used for searching will be: - - /home/karl:.:$TEXMF//tex - - Put another way, default expansion works on "formats" (search paths), -and not directly on environment variables. Example, showing the -trailing ':' ignored in the first case and expanded in the second: - - $ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS' - /tmp - $ env TTFONTS=/tmp: kpsewhich --show-path=.ttf - /tmp:.:/home/olaf/texmf/fonts/truetype//:... - - Since Kpathsea looks for multiple configuration files, it would be -natural to expect that (for example) an extra colon in './texmf.cnf' -would expand to the path in '$TEXMF/texmf.cnf'. Or, with Dvips' -configuration files, that an extra colon in 'config.$PRINTER' would -expand to the path in 'config.ps'. This doesn't happen. It's not clear -this would be desirable in all cases, and trying to devise a way to -specify the path to which the extra colon should expand seemed truly -baroque. - - Technicality: Since it would be useless to insert the default value -in more than one place, Kpathsea changes only one extra ':' and leaves -any others in place (they will eventually be ignored). Kpathsea checks -first for a leading ':', then a trailing ':', then a doubled ':'. - - You can trace this by debugging "paths" (*note Debugging::). Default -expansion is implemented in the source file 'kpathsea/kdefault.c'. - - -File: kpathsea.info, Node: Variable expansion, Next: Tilde expansion, Prev: Default expansion, Up: Path expansion - -5.3.2 Variable expansion ------------------------- - -'$foo' or '${foo}' in a path element is replaced by (1) the value of an -environment variable 'foo' (if defined); (2) the value of 'foo' from -'texmf.cnf' (if defined); (3) the empty string. - - If the character after the '$' is alphanumeric or '_', the variable -name consists of all consecutive such characters. If the character -after the '$' is a '{', the variable name consists of everything up to -the next '}' (braces may not be nested around variable names). -Otherwise, Kpathsea gives a warning and ignores the '$' and its -following character. - - You must quote the $'s and braces as necessary for your shell. -_Shell_ variable values cannot be seen by Kpathsea, i.e., ones defined -by 'set' in C shells and without 'export' in Bourne shells. - - For example, given - setenv tex /home/texmf - setenv TEXINPUTS .:$tex:${tex}prev -the final 'TEXINPUTS' path is the three directories: - .:/home/texmf:/home/texmfprev - - The '.PROGNAME' suffix on variables and '_PROGNAME' on environment -variable names are not implemented for general variable expansions. -These are only recognized when search paths are initialized (*note Path -sources::). - - Variable expansion is implemented in the source file -'kpathsea/variable.c'. - - -File: kpathsea.info, Node: Tilde expansion, Next: Brace expansion, Prev: Variable expansion, Up: Path expansion - -5.3.3 Tilde expansion ---------------------- - -A leading '~' in a path element is replaced by the value of the -environment variable 'HOME', or '.' if 'HOME' is not set. On Windows, -the environment variable 'USERPROFILE' is checked instead of 'HOME'. - - A leading '~USER' in a path element is replaced by USER's home -directory from the system 'passwd' database. - - For example, - setenv TEXINPUTS ~/mymacros: - -will prepend a directory 'mymacros' in your home directory to the -default path. - - As a special case, if a home directory ends in '/', the trailing -slash is dropped, to avoid inadvertently creating a '//' construct in -the path. For example, if the home directory of the user 'root' is '/', -the path element '~root/mymacros' expands to just '/mymacros', not -'//mymacros'. - - Tilde expansion is implemented in the source file 'kpathsea/tilde.c'. - - -File: kpathsea.info, Node: Brace expansion, Next: KPSE_DOT expansion, Prev: Tilde expansion, Up: Path expansion - -5.3.4 Brace expansion ---------------------- - -'x{A,B}y' expands to 'xAy:xBy'. For example: - - foo/{1,2}/baz - -expands to 'foo/1/baz:foo/2/baz'. ':' is the path separator on the -current system; e.g., on a Windows system, it's ';'. - - Braces can be nested; for example, 'x{A,B{1,2}}y' expands to -'xAy:xB1y:xB2y'. - - Multiple non-nested braces are expanded from right to left; for -example, 'x{A,B}{1,2}y' expands to 'x{A,B}1y:x{A,B}2y', which expands to -'xA1y:xB1y:xA2y:xB2y'. - - This feature can be used to implement multiple TeX hierarchies, by -assigning a brace list to '$TEXMF', as mentioned in 'texmf.in'. - - You can also use the path separator instead of the comma. The last -example could have been written 'x{A:B}{1:2}y' (on Unix). - - Brace expansion is implemented in the source file -'kpathsea/expand.c'. - - -File: kpathsea.info, Node: KPSE_DOT expansion, Next: Subdirectory expansion, Prev: Brace expansion, Up: Path expansion - -5.3.5 'KPSE_DOT' expansion --------------------------- - -When 'KPSE_DOT' is defined in the environment, it names a directory that -should be considered the current directory for the purpose of looking up -files in the search paths. This feature is needed by the 'mktex...' -scripts *note mktex scripts::, because these change the working -directory. You should not ever define it yourself. - - -File: kpathsea.info, Node: Subdirectory expansion, Prev: KPSE_DOT expansion, Up: Path expansion - -5.3.6 Subdirectory expansion ----------------------------- - -Two or more consecutive slashes in a path element following a directory -D is replaced by all subdirectories of D: first those subdirectories -directly under D, then the subsubdirectories under those, and so on. At -each level, the order in which the directories are searched is -unspecified. (It's "directory order", and definitely not alphabetical.) - - If you specify any filename components after the '//', only -subdirectories which match those components are included. For example, -'/a//b' would expand into directories '/a/1/b', '/a/2/b', '/a/1/1/b', -and so on, but not '/a/b/c' or '/a/1'. - - You can include multiple '//' constructs in the path. - - '//' at the beginning of a path is ignored; you didn't really want to -search every directory on the system, did you? - - I should mention one related implementation trick, which I took from -GNU find. Matthew Farwell suggested it, and David MacKenzie implemented -it. - - The trick is that in every real Unix implementation (as opposed to -the POSIX specification), a directory which contains no subdirectories -will have exactly two links (namely, one for '.' and one for '..'). -That is to say, the 'st_nlink' field in the 'stat' structure will be -two. Thus, we don't have to stat everything in the bottom-level (leaf) -directories--we can just check 'st_nlink', notice it's two, and do no -more work. - - But if you have a directory that contains a single subdirectory and -500 regular files, 'st_nlink' will be 3, and Kpathsea has to stat every -one of those 501 entries. Therein lies slowness. - - You can disable the trick by undefining 'ST_NLINK_TRICK' in -'kpathsea/config.h'. (It is undefined by default except under Unix.) - - Unfortunately, in some cases files in leaf directories are 'stat''d: -if the path specification is, say, '$TEXMF/fonts//pk//', then files in a -subdirectory '.../pk', even if it is a leaf, are checked. The reason -cannot be explained without reference to the implementation, so read -'kpathsea/elt-dirs.c' (search for 'may descend') if you are curious. -And if you find a way to solve the problem, please let me know. - - Subdirectory expansion is implemented in the source file -'kpathsea/elt-dirs.c'. - - -File: kpathsea.info, Node: Casefolding search, Next: Filename database, Prev: Path expansion, Up: Path searching - -5.4 Casefolding search -====================== - -In Kpathsea version 6.3.0 (released with TeX Live 2018), a new fallback -search was implemented on Unix-like systems, including Macs: for each -path element in turn, if no match is found by the normal search, and the -path element allows for checking the filesystem, a second check is made -for a case-insensitive match. - - This is enabled at compile-time on Unix systems, and enabled at -runtime by setting the configuration variable 'texmf_casefold_search', -to a true value, e.g., '1'; this is done by default in TeX Live. - -* Menu: - -* Rationale: Casefolding rationale. -* Examples: Casefolding examples. - - -File: kpathsea.info, Node: Casefolding rationale, Next: Casefolding examples, Up: Casefolding search - -5.4.1 Casefolding rationale ---------------------------- - -The purpose of the fallback casefolding search is to ease moving complex -documents between case-insensitive (file)systems and case-sensitive -ones. In particular, Apple decided to make the default filesystem on -Macs be case-insensitive some years ago, and this has exacerbated a -problem of people creating documents that use, say, an image under the -name 'foo.jpg', while the actual file is named 'foo.JPG' or 'Foo.jpg'. -It works on the Mac but if the document is transferred and run on a -standard case-sensitive Unix (file)system, the file can't be found, due -only to differences in case. - - This same problematic scenario has always existed on Windows, but for -whatever reason, it has become much more common since Apple also went to -a case-insensitive filesystem. Hence the relatively late change to the -Kpathsea behavior. - - The fallback case-insensitive search is omitted at compile-time on -Windows, where (for practical purposes) all file names are -case-insensitive at the kernel level, and so the normal search will -already have definitively matched or not. Therefore, search results in -unusual cases can be different on Windows and Unix--but this has always -been true. - - -File: kpathsea.info, Node: Casefolding examples, Prev: Casefolding rationale, Up: Casefolding search - -5.4.2 Casefolding examples --------------------------- - -The casefolding implementation prefers exact matches to casefolded -matches within a given path element, so as to retain most compatibility. -Backward compatibility is not perfect, however, as a casefolded match -may be found in an earlier path element than an exact match was -previously found (see example #4 below). Still, preferring the match in -the earlier element seemed potentially less confusing than otherwise, -and is in fact consistent with past behavior on Windows. Since case -mismatches are rare to begin with, and name collisions with respect only -to case thus even more rare, the hope is that it will not cause -difficulties in practice. - - If it's desirable in a given situation to have the exact same search -behavior as previously, that can be accomplished by setting the -configuration variable 'texmf_casefold_search' to '0' (*note Path -sources::). - - Some examples to illustrate the new behavior follow. - - Example #1: suppose the file './foobar.tex' exists. Now, searching -for './FooBar.TeX' (or any other case variation) will succeed, returning -'./foobar.tex'--the name as stored on disk. In previous releases, or if -'texmf_casefold_search' is false, the search would fail. - - Example #2: suppose we are using a case-sensitive (file)system, and -the search path is '.:/somedir', and the files './foobar.tex' and -'/somedir/FooBar.TeX' both exist. Both now and previously, searching -for 'foobar.tex' returns './foobar.tex'. However, searching for -'FooBar.TeX' now returns './foobar.tex' instead of -'/somedir/FooBar.TeX'; this is the incompatibility mentioned above. -Also (as expected), searching for 'FOOBAR.TEX' (or whatever variation) -will now return './foobar.tex', whereas before it would fail. Searching -for all ('kpsewhich --all') 'foobar.tex' will return both matches. - - Example #3: same as example #2, but on a case-insensitive -(file)system: both now and previously, searching for 'FooBar.TeX' -returns './foobar.tex', since the system considers that a match. The -Kpathsea casefolding never comes into play. - - Example #4: if we have (on a case-sensitive system) both -'./foobar.tex' and './FOOBAR.TEX', searching with the exact case returns -that exact match, now and previously. Searching for 'FooBar.tex' will -now return one or the other (chosen arbitrarily), rather than failing. -Perhaps unexpectedly, searching for all 'foobar.tex' or 'FooBar.tex' -will also return only one or the other, not both (see more below). - - Example #5: the font file 'STIX-Regular.otf' is included in TeX Live -in the system directory 'texmf-dist/fonts/opentype/public/stix'. -Because Kpathsea never searches the disk in the big system directory, -the casefolding is not done, and a search for 'stix-regular.otf' will -fail (on case-sensitive systems), as it always has. - - The caveat about not searching the disk amounts to saying that -casefolding does not happen in the trees specified with '!!' (*note -ls-R::), that is, where only database ('ls-R') searching is done. In -TeX Live, that is the 'texmf-local' and 'texmf-dist' trees (also -'$TEXMFSYSCONFIG' and '$TEXMFSYSVAR', but those are rarely noticed). -The rationale for this is that in practice, case mangling happens with -user-created files, not with packages distributed as part of the TeX -system. - - One more caveat: the purpose of 'kpsewhich' is to exercise the path -searching in Kpathsea as it is actually done. Therefore, as shown -above, 'kpsewhich --all' will not return all matches regardless of case -within a given path element. If you want to find all matches in all -directories, 'find' is the best tool, although the setup takes a couple -steps: - - kpsewhich -show-path=tex >/tmp/texpath # search path specification - kpsewhich -expand-path="`cat /tmp/texpath`" >/tmp/texdirs # all dirs - tr ':' '\n' </tmp/texdirs >/tmp/texdirlist # colons to newlines - find `cat /tmp/texdirlist` -iname somefile.tex -print </tmp/texdirlist - - Sorry that it's annoyingly lengthy, but implementing this inside -Kpathsea would be a lot of error-prone trouble for something that is -only useful for debugging. If your 'find' does not support '-iname', -you can get GNU Find from <https://gnu.org/software/findutils>. - - The casefolding search is implemented in the source file -'kpathsea/pathsearch.c'. Two implementation points: - - * Kpathsea never tries to check if a given directory resides on a - case-insensitive filesystem, because there is no efficient and - portable way to do so. All it does is try to see if a potential - file name is a readable normal file (with, usually, the 'access' - system call). - - * Kpathsea does not do any case-insensitive matching of the - directories along the path. It's not going to find - '/Some/Random/file.tex' when looking for '/some/random/file.tex'. - The casefolding only happens with the elements of the leaf - directory. - - -File: kpathsea.info, Node: Filename database, Next: Invoking kpsewhich, Prev: Casefolding search, Up: Path searching - -5.5 Filename database ('ls-R') -============================== - -Kpathsea goes to some lengths to minimize disk accesses for searches -(*note Subdirectory expansion::). Nevertheless, in practice searching -every possible directory in typical TeX installations takes an -excessively long time. - - Therefore, Kpathsea can use an externally-built "filename database" -file named 'ls-R' that maps files to directories, thus avoiding the need -to exhaustively search the disk. - - A second database file 'aliases' allows you to give additional names -to the files listed in 'ls-R'. - - The 'ls-R' and 'aliases' features are implemented in the source file -'kpathsea/db.c'. - -* Menu: - -* ls-R:: The main filename database. -* Filename aliases:: Aliases for those names. -* Database format:: Syntax details of the database file. - - -File: kpathsea.info, Node: ls-R, Next: Filename aliases, Up: Filename database - -5.5.1 'ls-R' ------------- - -As mentioned above, you must name the main filename database 'ls-R'. -You can put one at the root of each TeX installation hierarchy you wish -to search ('$TEXMF' by default, which expands to a braced list of -several hierarchies in TeX Live). - - Kpathsea looks for 'ls-R' files along the 'TEXMFDBS' path. It is -best for this to contain all and only those hierarchies from '$TEXMF' -which are specified with '!!'--and also to specify them with '!!' in -'TEXMFDBS'. (See the end of this section for more on '!!'.) - - The recommended way to create and maintain 'ls-R' is to run the -'mktexlsr' script, which is installed in '$(bindir)' ('/usr/local/bin' -by default). That script goes to some trouble to follow symbolic links -as necessary, etc. It's also invoked by the distributed 'mktex...' -scripts. - - At its simplest, though, you can build 'ls-R' with the command - cd /YOUR/TEXMF/ROOT && ls -LAR ./ >ls-R - -presuming your 'ls' produces the right output format (see the section -below). GNU 'ls', for example, outputs in this format. Also presuming -your 'ls' hasn't been aliased in a system file (e.g., '/etc/profile') to -something problematic, e.g., 'ls --color=tty'. In that case, you will -have to disable the alias before generating 'ls-R'. For the precise -definition of the file format, see *note Database format::. - - Regardless of whether you use the supplied script or your own, you -will almost certainly want to invoke it via 'cron', so when you make -changes in the installed files (say if you install a new LaTeX package), -'ls-R' will be automatically updated. However, for those using TeX Live -or system distributions, the package managers should run 'mktexlsr' as -needed. - - The '-A' option to 'ls' includes files beginning with '.' (except for -'.' and '..'), such as the file '.tex' included with the LaTeX tools -package. (On the other hand, _directories_ whose names begin with '.' -are always ignored.) - - If your system does not support symbolic links, omit the '-L'. - - 'ls -LAR /YOUR/TEXMF/ROOT' will also work. But using './' avoids -embedding absolute pathnames, so the hierarchy can be easily -transported. It also avoids possible trouble with automounters or other -network filesystem conventions. - - Kpathsea warns you if it finds an 'ls-R' file, but the file does not -contain any usable entries. The usual culprit is running plain 'ls -R' -instead of 'ls -LR ./' or 'ls -R /YOUR/TEXMF/ROOT'. Another possibility -is some system directory name starting with a '.' (perhaps if you are -using AFS); Kpathsea ignores everything under such directories. - - If a particular path element begins with '!!', _only_ the database -will be searched for that element, never the disk; and if the database -does not exist, nothing at all will be searched. In TeX Live, most of -the trees are specified with '!!'. - - For path elements that do not begin with '!!', if the database -exists, it will be used, and the disk will not be searched. However, in -this case, if the database does not exist, the disk will be searched. -In TeX Live, the most notable case of this is the 'TEXMFHOME' tree, to -allow users to add and remove files from their own tree without having -to worry about 'ls-R'. - - (Aside: there are uncommon cases where a '!!' tree will be searched -on disk even if the 'ls-R' file exists; they are too obscure to try to -explain here. See 'pathsearch.c' in the source if you need to know.) - - To sum up: do not create an 'ls-R' file unless you also take care to -keep it up to date. Otherwise newly-installed files will not be found. - - -File: kpathsea.info, Node: Filename aliases, Next: Database format, Prev: ls-R, Up: Filename database - -5.5.2 Filename aliases ----------------------- - -In some circumstances, you may wish to find a file under several names. -For example, suppose a TeX document was created using a DOS system and -tries to read 'longtabl.sty'. But now it's being run on a Unix system, -and the file has its original name, 'longtable.sty'. The file won't be -found. You need to give the actual file 'longtable.sty' an alias -'longtabl.sty'. - - You can handle this by creating a file 'aliases' as a companion to -the 'ls-R' for the hierarchy containing the file in question. (You must -have an 'ls-R' for the alias feature to work.) - - The format of 'aliases' is simple: two whitespace-separated words per -line; the first is the real name 'longtable.sty', and second is the -alias ('longtabl.sty'). These must be base filenames, with no directory -components. 'longtable.sty' must be in the sibling 'ls-R'. - - Also, blank lines and lines starting with '%' or '#' are ignored in -'aliases', to allow for comments. - - If a real file 'longtabl.sty' exists, it is used regardless of any -aliases. - - -File: kpathsea.info, Node: Database format, Prev: Filename aliases, Up: Filename database - -5.5.3 Database format ---------------------- - -The "database" read by Kpathsea is a line-oriented file of plain text. -The format is that generated by GNU (and most other) 'ls' programs given -the '-R' option, as follows. - - * Blank lines are ignored. - - * If a line begins with '/' or './' or '../' and ends with a colon, - it's the name of a directory. ('../' lines aren't useful, however, - and should not be generated.) - - * All other lines define entries in the most recently seen directory. - /'s in such lines will produce possibly-strange results. - - * Files with no preceding directory line are ignored. - - For example, here's the first few lines of 'ls-R' (which totals about -30K bytes) on my system: - - bibtex - dvips - fonts - ls-R - metafont - metapost - tex - web2c - - ./bibtex: - bib - bst - doc - - ./bibtex/bib: - asi.bib - btxdoc.bib - ... - - -File: kpathsea.info, Node: Invoking kpsewhich, Prev: Filename database, Up: Path searching - -5.6 'kpsewhich': Standalone path searching -========================================== - -The Kpsewhich program exercises the path searching functionality -independent of any particular application. This can also be useful as a -sort of 'find' program to locate files in your TeX hierarchies, perhaps -in administrative scripts. It is used heavily in the distributed -'mktex...' scripts. - - Synopsis: - - kpsewhich OPTION... FILENAME... - - The options and filename(s) to look up can be intermixed. Options -can start with either '-' or '--', and any unambiguous abbreviation is -accepted. - -* Menu: - -* Path searching options:: Changing the mode, resolution, etc. -* Specially-recognized files:: Default formats for texmf.cnf, etc. -* Auxiliary tasks:: Path and variable expansion, etc. -* Standard options:: '--help' and '--version'. - - -File: kpathsea.info, Node: Path searching options, Next: Specially-recognized files, Up: Invoking kpsewhich - -5.6.1 Path searching options ----------------------------- - -Kpsewhich looks up each non-option argument on the command line as a -filename, and returns the first file found. - - Various options alter the path searching behavior: - -'--all' - Report all matches found, one per line. By default, if there is - more than one match, just one will be reported (chosen effectively - at random). Exception: with the glyph formats ('pk', 'gf'), this - option has no effect and only the first match is returned. - -'--casefold-search' -'--no-casefold-search' - Explicitly enable or disable the fallback to a case-insensitive - search on Unix platforms (*note Casefolding search::); no effect on - Windows. The default is enabled, set in 'texmf.cnf'. Disabling - ('--no-casefold-search') does not mean that searches magically - become case-sensitive when the underlying (file)system is - case-insensitive, it merely means that Kpathsea does not do any - casefolding itself. - -'--cnf-line=STR' - Parse STR as if it were a line in the 'texmf.cnf' configuration - file (*note Config files::), overriding settings in the actual - configuration files, and also in the environment (*note Path - sources::). This is implemented by making any settings from STR in - the environment, overwriting any value already there. Thus, an - extra colon in a '--cnf-line' value will refer to the value from a - configuration file, not a user-set environment variable. - - Furthermore, any variable set from STR will also be set with the - program name suffix. For example, 'pdftex - --cnf-line=TEXINPUTS=/foo:' will set both 'TEXINPUTS' and - 'TEXINPUTS_pdftex' in the environment (and the value will be '/foo' - followed by the setting from 'texmf.cnf', ignoring any user-set - 'TEXINPUTS'). - - This behavior is desirable because, in practice, many variables in - the distributed 'texmf.cnf' are program-specific, and the intuitive - behavior is for values set on the command line with '--cnf-line' to - override them. - -'--dpi=NUM' - Set the resolution to NUM; this only affects 'gf' and 'pk' lookups. - '-D' is a synonym, for compatibility with Dvips. Default is 600. - -'--engine=NAME' - Set the engine name to NAME. By default it is not set. The engine - name is used in some search paths to allow files with the same name - but used by different engines to coexist. - - In particular, since the memory dump files ('.fmt'/'.base'/'.mem') - are now stored in subdirectories named for the engine ('tex', - 'pdftex', 'xetex', etc.), you must specify an engine name in order - to find them. For example, 'cont-en.fmt' typically exists for both - 'pdftex' and 'xetex'. With the default path settings, you can use - '--engine=/' to look for any dump file, regardless of engine; if a - dump file exists for more than one engine, it's indeterminate which - one is returned. (The '/' ends up specifying a normal recursive - search along the path where the dumps are stored, namely - '$TEXMF/web2c{/$engine,}'.) - -'--format=NAME' - Set the format for lookup to NAME. By default, the format is - guessed from the filename, with 'tex' being used if nothing else - fits. The recognized filename extensions (including any leading - '.') are also allowable NAMEs. - - All formats also have a name, which is the only way to specify - formats with no associated suffix. For example, for Dvips - configuration files you can use '--format="dvips config"'. (The - quotes are for the sake of the shell.) - - Here's the current list of recognized names and the associated - suffixes. *Note Supported file formats::, for more information on - each of these. - - The strings in parentheses are abbreviations recognized only by - 'kpsewhich' (not the underlying library calls). They are provided - when it would otherwise require an argument containing a space to - specify the format, to simplify quoting of calls from shells. - - gf: gf - pk: pk - bitmap font (bitmapfont): - tfm: .tfm - afm: .afm - base: .base - bib: .bib - bst: .bst - cnf: .cnf - ls-R: ls-R ls-r - fmt: .fmt - map: .map - mem: .mem - mf: .mf - mfpool: .pool - mft: .mft - mp: .mp - mppool: .pool - MetaPost support (mpsupport): - ocp: .ocp - ofm: .ofm .tfm - opl: .opl .pl - otp: .otp - ovf: .ovf .vf - ovp: .ovp .vpl - graphic/figure: .eps .epsi - tex: .tex .sty .cls .fd .aux .bbl .def .clo .ldf - TeX system documentation (doc): - texpool: .pool - TeX system sources (source): .dtx .ins - PostScript header: .pro - Troff fonts (trofffont): - type1 fonts: .pfa .pfb - vf: .vf - dvips config (dvipsconfig): - ist: .ist - truetype fonts: .ttf .ttc .TTF .TTC .dfont - type42 fonts: .t42 .T42 - web2c files (web2c): - other text files (othertext): - other binary files (otherbin): - misc fonts (miscfont): - web: .web .ch - cweb: .w .web .ch - enc files: .enc - cmap files (cmap): - subfont definition files: .sfd - opentype fonts: .otf - pdftex config (pdftexconfig): - lig files: .lig - texmfscripts: - lua: .lua .luatex .luc .luctex .texlua .texluc .tlu - font feature files: .fea - cid maps: .cid .cidmap - mlbib: .mlbib .bib - mlbst: .mlbst .bst - clua: .dll .so - ris: .ris - bltxml: .bltxml - - This option and '--path' are mutually exclusive. - -'--interactive' - After processing the command line, read additional filenames to - look up from standard input. - -'--mktex=FILETYPE' -'--no-mktex=FILETYPE' - Turn on or off the 'mktex' script associated with FILETYPE. Usual - values for FILETYPE are 'pk', 'mf', 'tex', and 'tfm'. By default, - all are off in Kpsewhich, even if they are enabled for TeX. This - option implies setting '--must-exist'. *Note mktex scripts::. - -'--mode=STRING' - Set the mode name to STRING; this also only affects 'gf' and 'pk' - lookups. No default: any mode will be found. *Note mktex script - arguments::. - -'--must-exist' - Do everything possible to find the files, notably including - searching the disk and running the 'mktex' scripts. By default, - only the 'ls-R' database is checked, in the interest of efficiency. - -'--path=STRING' - Search along the path STRING (colon-separated as usual), instead of - guessing the search path from the filename. '//' and all the usual - expansions are supported (*note Path expansion::). This option and - '--format' are mutually exclusive. To output the complete - directory expansion of a path, instead of doing a one-shot lookup, - see '--expand-path' and '--show-path' in the following section. - -'--progname=NAME' - Set the program name to NAME; default is 'kpsewhich'. This can - affect the search paths via the '.PROGNAM' feature in configuration - files (*note Config files::). - -'--subdir=STRING' - Report only those matches whose directory part _ends_ with STRING - (compared literally, except case is ignored on a case-insensitive - operating system). For example, suppose there are two matches for - a given name: - - kpsewhich foo.sty - => /some/where/foo.sty - /another/place/foo.sty - - Then we can narrow the result to what we are interested in with - '--subdir': - - kpsewhich --subdir=where foo.sty - => /some/where/foo.sty - - kpsewhich --subdir=place foo.sty - => /another/place/foo.sty - - The string to match must be at the end of the directory part of the - match, and it is taken literally, with no pattern matching: - - kpsewhich --subdir=another foo.sty - => - - The string to match may cross directory components: - - kpsewhich --subdir=some/where foo.sty - => /some/where/foo.sty - - '--subdir' implies '--all'; if there is more than one match, they - will all be reported (in our example, both 'where' and 'place' end - in 'e'): - - kpsewhich --subdir=e - => /some/where/foo.sty - /another/place/foo.sty - - Because of the above rules, the presence of a leading '/' is - important, since it "anchors" the match to a full component name: - - kpsewhich --subdir=/lace foo.sty - => - - However, a trailing '/' is immaterial (and ignored), since the - match always takes place at the end of the directory part: - - kpsewhich --subdir=lace/ foo.sty - => /another/place/foo.sty - - The purpose of these rules is to make it convenient to find results - only within a particular area of the tree. For instance, a given - script named 'foo.lua' might exist within both - 'texmf-dist/scripts/pkg1/' and 'texmf-dist/scripts/pkg2/'. By - specifying, say, '--subdir=/pkg1', you can be sure of getting the - one you are interested in. - - We only match at the end because a site might happen to install TeX - in '/some/coincidental/pkg1/path/', and we wouldn't want to match - 'texmf-dist/scripts/pkg2/' that when searching for '/pkg1'. - - -File: kpathsea.info, Node: Specially-recognized files, Next: Auxiliary tasks, Prev: Path searching options, Up: Invoking kpsewhich - -5.6.2 Specially-recognized files for 'kpsewhich' ------------------------------------------------- - -'kpsewhich' recognizes a few special filenames on the command line and -defaults to using the 'known' file formats for them, merely to save the -time and trouble of specifying the format. This is only a feature of -'kpsewhich'; when using the Kpathsea library itself, none of these -special filenames are recognized, and it's still up to the caller to -specify the desired format. - - Here is the list of special filenames to 'kpsewhich', along with -their corresponding format: - -'config.ps' - 'dvips config' - -'dvipdfmx.cfg' - 'other text files' - -'fmtutil.cnf' - 'web2c files' - -'glyphlist.txt' - 'map' - -'mktex.cnf' - 'web2c files' - -'pdfglyphlist.txt' - 'map' - -'pdftex.cfg' - 'pdftex config' (although 'pdftex.cfg' is not used any more; look - for the file 'pdftexconfig.tex' instead.) - -'texmf.cnf' - 'cnf' - -'XDvi' - 'other text files' - - A user-specified format will override the above defaults. - - Another useful configuration file in this regard is 'tcfmgr.map', -found in 'texmf/texconfig/tcfmgr.map', which records various information -about the above configuration files (among others). - - -File: kpathsea.info, Node: Auxiliary tasks, Next: Standard options, Prev: Specially-recognized files, Up: Invoking kpsewhich - -5.6.3 Auxiliary tasks ---------------------- - -Kpsewhich provides some features in addition to path lookup as such: - -'--debug=NUM' - Set debugging options to NUM. *Note Debugging::. - -'--expand-braces=STRING' - Output variable, tilde, and brace expansion of STRING, which is - assumed to be a single path element. *Note Path expansion::. - -'--expand-path=STRING' - Output the complete expansion of STRING, with each element - separated by the usual path separator on the current system (';' on - Windows, ':' otherwise). This may be useful to construct a custom - search path for a format not otherwise supported. To retrieve the - search path for a format that is already supported, see - '--show-path'. - - Nonexistent directories are culled from the output: - - $ kpsewhich --expand-path '/tmp' - => /tmp - $ kpsewhich --expand-path '/nonesuch' - => - - For one-shot uses of an arbitrary (not built in to Kpathsea) path, - see '--path' (*note Path searching options::). - -'--expand-var=STRING' - Output the variable and tilde expansion of STRING. For example, - with the usual 'texmf.cnf', 'kpsewhich --expand-var='$TEXMF'' - returns the TeX system hierarchy root(s). *Note Path expansion::. - The specified STRING can contain anything, though, not just - variable references. This calls 'kpse_var_expand' (*note - Programming with config files::). - -'--help-formats' - Output information about each supported format (*note Supported - file formats::), including the names and abbreviations, variables - looked for, and the original path. - -'--safe-in-name=NAME' -'--safe-out-name=NAME' - Exit successfully if NAME is safe to open for reading or writing, - respectively, else unsuccessfully. No output is written. These - tests take account of the related Kpathsea configuration settings - (*note Calling sequence::). - -'--show-path=NAME' - Show the path that would be used for file lookups of file type - NAME. Either a filename extension ('pk', '.vf', etc.) or an - integer can be used, just as with '--format', described in the - previous section. - -'--var-brace-value=VARIABLE' - Like '--var-value' (next), but also expands '{...}' constructs. - (*note Brace expansion::). Thus, the value is assumed to possibly - be several path elements, and '~' is expanded at the beginning of - each. The path separator is changed to that of the current system - in the expansion. - - Example: 'FOO='.;~' kpsewhich --var-brace-value=FOO' outputs (on a - Unix-ish system) '.:/home/karl', supposing the latter is the - current user's home directory. Note that the ';' in the source - value, as commonly used in 'texmf.cnf', has changed to a ':', as - the normal path separator on the current system. On a Windows-ish - system, the ';' would remain. - -'--var-value=VARIABLE' - Outputs the value of VARIABLE (a simple identifier like - 'TEXMFDIST', with no '$' or other constructs), expanding '$' (*note - Variable expansion::) and '~' (*note Tilde expansion::) constructs - in the value. '~' expansion happens at the beginning of the - overall value and at the beginning of a variable expansion, but not - arbitrarily within the string. Braces are not expanded. - - Example: '--var-value=texmf_casefold_search' outputs (if the - default is not changed) '1'. - - Example to contrast with '--var-brace-value': 'FOO='.;~' kpsewhich - --var-value=FOO' outputs '.;~', i.e., the same as the input value, - on all systems. - - -File: kpathsea.info, Node: Standard options, Prev: Auxiliary tasks, Up: Invoking kpsewhich - -5.6.4 Standard options ----------------------- - -Kpsewhich accepts the standard GNU options: - - * '--help' prints a help message on standard output and exits - successfully. - - * '--version' prints the Kpathsea version number and exits - successfully. - - -File: kpathsea.info, Node: TeX support, Next: Programming, Prev: Path searching, Up: Top - -6 TeX support -************* - -Although the basic features in Kpathsea can be used for any type of path -searching, it came about, as usual, with a specific application in mind: -I wrote Kpathsea specifically for TeX system programs. I had been -struggling with the programs I was using (Dvips, Xdvi, and TeX itself) -having slightly different notions of how to specify paths; and debugging -was painful, since no code was shared. - - Therefore, Kpathsea provides some TeX-specific formats and features. -Indeed, many of the purportedly generic path searching features were -provided because they seemed useful in that conTeXt (font lookup, -particularly). - - Kpathsea provides a standard way to search for files of any of the -supported file types; glyph fonts are a bit different than all the rest. -Searches are based solely on names of files, not their contents--if a GF -file is (mis)named 'cmr10.600pk', it will be found as a PK file. - -* Menu: - -* Supported file formats:: File types Kpathsea knows about. -* File lookup:: Searching for most kinds of files. -* Glyph lookup:: Searching for bitmap fonts. -* Suppressing warnings:: Avoiding warnings via TEX_HUSH. -* mktex scripts:: Generating files at runtime. - - -File: kpathsea.info, Node: Supported file formats, Next: File lookup, Up: TeX support - -6.1 Supported file formats -========================== - -Kpathsea has support for a number of file types. Each file type has a -list of environment and config file variables that are checked to define -the search path, and most have a default suffix that plays a role in -finding files (see the next section). Some also define additional -suffixes, and/or a program to be run to create missing files on the fly. - - Since environment variables containing periods, such as -'TEXINPUTS.latex', are not allowed on some systems, Kpathsea looks for -environment variables with an underscore, e.g., 'TEXINPUTS_latex' (*note -Config files::). - - The following table lists the above information. You can also get -the list by giving the '--help-formats' option to 'kpsewhich' (*note -Auxiliary tasks::). - -'afm' - (Adobe font metrics, *note (dvips)Metric files::) 'AFMFONTS'; - suffix '.afm'. - -'base' - (Metafont memory dump, *note (web2c)Memory dumps::) 'MFBASES', - 'TEXMFINI'; suffix '.base'. - -'bib' - (BibTeX bibliography source, *note (web2c)bibtex invocation::) - 'BIBINPUTS', 'TEXBIB'; suffix '.bib'. - -'bltxml' - (BibLaTeXML bibliography files for Biber, - <https://ctan.org/pkg/biber>) 'BLTXMLINPUTS' suffix '.bltxml'. - -'bst' - (BibTeX style, *note Basic BibTeX style files: (web2c)Basic BibTeX - style files.) 'BSTINPUTS'; suffix '.bst'. - -'clua' - (dynamic libraries for Lua, <https://ctan.org/pkg/luatex>) - 'CLUAINPUTS' suffixes '.dll' and '.so'. - -'cmap' - (character map files) 'CMAPFONTS'; suffix '.cmap'. - -'cnf' - (Runtime configuration files, *note Config files::) 'TEXMFCNF'; - suffix '.cnf'. - -'cweb' - (CWEB input files) 'CWEBINPUTS'; suffixes '.w', '.web'; additional - suffix '.ch'. - -'dvips config' - (Dvips 'config.*' files, such as 'config.ps', *note (dvips)Config - files::) 'TEXCONFIG'. - -'enc files' - (encoding vectors) 'ENCFONTS'; suffix '.enc'. - -'fmt' - (TeX memory dump, *note (web2c)Memory dumps::) 'TEXFORMATS', - 'TEXMFINI'; suffix '.fmt'. - -'font cid map' - (CJK mapping) 'FONTCIDMAPS' suffix '.cid'. - -'font feature files' - (primarily for OpenType font features) 'FONTFEATURES' suffix - '.fea'. - -'gf' - (generic font bitmap, *note (dvips)Glyph files::) 'PROGRAMFONTS', - 'GFFONTS', 'GLYPHFONTS', 'TEXFONTS'; suffix 'gf'. - -'graphic/figure' - (Encapsulated PostScript figures, *note (dvips)PostScript - figures::) 'TEXPICTS', 'TEXINPUTS'; additional suffixes: '.eps', - '.epsi'. - -'ist' - (makeindex style files) 'TEXINDEXSTYLE', 'INDEXSTYLE'; suffix - '.ist'. - -'lig files' - (ligature definition files) 'LIGFONTS'; suffix '.lig'. - -'ls-R' - (Filename databases, *note Filename database::) 'TEXMFDBS'. - -'map' - (Fontmaps, *note Fontmap::) 'TEXFONTMAPS'; suffix '.map'. - -'mem' - (MetaPost memory dump, *note (web2c)Memory dumps::) 'MPMEMS', - 'TEXMFINI'; suffix '.mem'. - -'MetaPost support' - (MetaPost support files, used by DMP; *note (web2c)dmp - invocation::) 'MPSUPPORT'. - -'mf' - (Metafont source, *note (web2c)mf invocation::) 'MFINPUTS'; suffix - '.mf'; dynamic creation program: 'mktexmf'. - -'mfpool' - (Metafont program strings, *note (web2c)pooltype invocation::) - 'MFPOOL', 'TEXMFINI'; suffix '.pool'. - -'mft' - ('MFT' style file, *note (web2c)mft invocation::) 'MFTINPUTS'; - suffix '.mft'. - -'misc fonts' - (font-related files that don't fit the other categories) - 'MISCFONTS' - -'mlbib' - (MlBibTeX bibliography source) 'MLBIBINPUTS', 'BIBINPUTS', - 'TEXBIB'; suffixes '.mlbib', '.mlbib'. - -'mlbst' - (MlBibTeX style) 'MLBSTINPUTS', 'BSTINPUTS'; suffixes '.mlbst', - '.bst'. - -'mp' - (MetaPost source, *note (web2c)mpost invocation::) 'MPINPUTS'; - suffix '.mp'. - -'mppool' - (MetaPost program strings, *note (web2c)pooltype invocation::) - 'MPPOOL', 'TEXMFINI'; suffix '.pool'. - -'ocp' - (Omega compiled process files) 'OCPINPUTS'; - suffix '.ocp'; dynamic creation program: 'MakeOmegaOCP'. - -'ofm' - (Omega font metrics) 'OFMFONTS', 'TEXFONTS'; - suffixes '.ofm', '.tfm'; dynamic creation program: 'MakeOmegaOFM'. - -'opentype fonts' - (OpenType fonts) 'OPENTYPEFONTS'. - -'opl' - (Omega property lists) 'OPLFONTS', 'TEXFONTS'; suffix '.opl'. - -'otp' - (Omega translation process files) 'OTPINPUTS'; suffix '.otp'. - -'ovf' - (Omega virtual fonts) 'OVFFONTS', 'TEXFONTS'; suffix '.ovf'. - -'ovp' - (Omega virtual property lists) 'OVPFONTS', 'TEXFONTS'; suffix - '.ovp'. - -'pdftex config' - (PDFTeX-specific configuration files) 'PDFTEXCONFIG'. - -'pk' - (packed bitmap fonts, *note (dvips)Glyph files::) 'PROGRAMFONTS' - (PROGRAM being 'XDVI', etc.), 'PKFONTS', 'TEXPKS', 'GLYPHFONTS', - 'TEXFONTS'; suffix 'pk'; dynamic creation program: 'mktexpk'. - -'PostScript header' - (downloadable PostScript, *note (dvips)Header files::) - 'TEXPSHEADERS', 'PSHEADERS'; additional suffix '.pro'. - -'ris' - (RIS bibliography files, primarily for Biber, - <https://ctan.org/pkg/biber>) 'RISINPUTS' suffix '.ris'. - -'subfont definition files' - (subfont definition files) 'SFDFONTS' suffix '.sfd'. - -'tex' - (TeX source, *note (web2c)tex invocation::) 'TEXINPUTS'; suffix - '.tex'; additional suffixes: none, because such a list cannot be - complete; dynamic creation program: 'mktextex'. - -'TeX system documentation' - (Documentation files for the TeX system) 'TEXDOCS'. - -'TeX system sources' - (Source files for the TeX system) 'TEXSOURCES'. - -'texmfscripts' - (Architecture-independent executables distributed in the texmf - trees) 'TEXMFSCRIPTS'. - -'texpool' - (TeX program strings, *note (web2c)pooltype invocation::) - 'TEXPOOL', 'TEXMFINI'; suffix '.pool'. - -'tfm' - (TeX font metrics, *note (dvips)Metric files::) 'TFMFONTS', - 'TEXFONTS'; suffix '.tfm'; dynamic creation program: 'mktextfm'. - -'Troff fonts' - (Troff fonts, used by DMP; *note (web2c)DMP invocation::) - 'TRFONTS'. - -'truetype fonts' - (TrueType outline fonts) 'TTFONTS'; suffixes '.ttf' and '.TTF', - '.ttc' and '.TTC', '.dfont'. - -'type1 fonts' - (Type 1 PostScript outline fonts, *note (dvips)Glyph files::) - 'T1FONTS', 'T1INPUTS', 'TEXPSHEADERS', 'DVIPSHEADERS'; suffixes - '.pfa', '.pfb'. - -'type42 fonts' - (Type 42 PostScript outline fonts) 'T42FONTS'. - -'vf' - (virtual fonts, *note (dvips)Virtual fonts::) 'VFFONTS', - 'TEXFONTS'; suffix '.vf'. - -'web' - (WEB input files) 'WEBINPUTS'; suffix '.web'; additional suffix - '.ch'. - -'web2c files' - (files specific to the web2c implementation) 'WEB2C'. - - There are two special cases, because the paths and environment -variables always depend on the name of the program: the variable name is -constructed by converting the program name to upper case, and then -appending 'INPUTS'. Assuming the program is called 'foo', this gives us -the following table. - -'other text files' - (text files used by 'foo') 'FOOINPUTS'. - -'other binary files' - (binary files used by 'foo') 'FOOINPUTS'. - - If an environment variable by these names are set, the corresponding -'texmf.cnf' definition won't be looked at (unless, as usual, the -environment variable value has an extra ':'). *Note Default -expansion::. - - For the font variables, the intent is that: - * 'TEXFONTS' is the default for everything. - - * 'GLYPHFONTS' is the default for bitmap (or, more precisely, - non-metric) files. - - * Each font format has a variable of its own. - - * Each program has its own font override path as well; e.g., - 'DVIPSFONTS' for Dvipsk. Again, this is for bitmaps, not metrics. - - -File: kpathsea.info, Node: File lookup, Next: Glyph lookup, Prev: Supported file formats, Up: TeX support - -6.2 File lookup -=============== - -This section describes how Kpathsea searches for most files (bitmap font -searches are the exception, as described in the next section). - - Here is the search strategy for a file NAME: - - 1. If the file format defines default suffixes, and the suffix of NAME - name is not already a known suffix for that format, try the name - with each default appended, and use alternative names found in the - fontmaps if necessary. Example: given 'foo.bar', look for - 'foo.bar.tex'. - - 2. Search for NAME, and if necessary for alternative names found in - the fontmaps. Example: given 'foo.bar', we also look for - 'foo.bar'. - - 3. If the file format defines a program to invoke to create missing - files, run it (*note mktex scripts::). - - The order in which we search for "suffixed" name (item 1) or the -"as-is" name (item 2) is controlled by the 'try_std_extension_first' -configuration value. The default set in 'texmf.cnf' is true, since -common suffixes are already recognized: 'babel.sty' will only look for -'babel.sty', not 'babel.sty.tex', regardless of this setting. - - When the suffix is unknown (e.g., 'foo.bar'), both names are always -tried; the difference is the order in which they are tried. - - 'try_std_extension_first' only affects names being looked up which -*already* have an extension. A name without an extension (e.g., 'tex -story') will always have an extension added first. - - This algorithm is implemented in the function 'kpathsea_find_file' in -the source file 'kpathsea/tex-file.c'. You can watch it in action with -the debugging options (*note Debugging::). - - -File: kpathsea.info, Node: Glyph lookup, Next: Suppressing warnings, Prev: File lookup, Up: TeX support - -6.3 Glyph lookup -================ - -This section describes how Kpathsea searches for a bitmap font in GF or -PK format (or either) given a font name (e.g., 'cmr10') and a resolution -(e.g., 600). - - Here is an outline of the search strategy (details in the sections -below) for a file NAME at resolution DPI. The search stops at the first -successful lookup. - - 1. Look for an existing file NAME.DPIFORMAT in the specified - format(s). - - 2. If NAME is an alias for a file F in the fontmap file - 'texfonts.map', look for F.DPI. - - 3. Run an external program (typically named 'mktexpk') to generate the - font (*note mktex scripts::) - - 4. Look for FALLBACK.DPI, where FALLBACK is some last-resort font - (typically 'cmr10'). - - This is implemented in 'kpathsea_find_glyph' in -'kpathsea/tex-glyph.c'. - -* Menu: - -* Basic glyph lookup:: Features common to all glyph lookups. -* Fontmap:: Aliases for fonts. -* Fallback font:: Resolutions and fonts of last resort. - - -File: kpathsea.info, Node: Basic glyph lookup, Next: Fontmap, Up: Glyph lookup - -6.3.1 Basic glyph lookup ------------------------- - -When Kpathsea looks for a bitmap font NAME at resolution DPI in a format -FORMAT, it first checks each directory in the search path for a file -'NAME.DPIFORMAT'; for example, 'cmr10.600pk'. Kpathsea looks for a PK -file first, then a GF file. - - If that fails, Kpathsea looks for 'dpiDPI/NAME.FORMAT'; for example, -'dpi600/cmr10.pk'. This is how fonts are typically stored on -filesystems (such as DOS) that permit only three-character extensions. - - If that fails, Kpathsea looks for a font with a close-enough DPI. -"Close enough" is defined by the macro 'KPSE_BITMAP_TOLERANCE' in -'kpathsea/tex-glyph.h' to be 'DPI / 500 + 1'. This is slightly more -than the 0.2% minimum allowed by the DVI standard -(<CTAN:/dviware/driv-standard/level-0>). - - -File: kpathsea.info, Node: Fontmap, Next: Fallback font, Prev: Basic glyph lookup, Up: Glyph lookup - -6.3.2 Fontmap -------------- - -If a bitmap font or metric file is not found with the original name (see -the previous section), Kpathsea looks through any "fontmap" files for an -"alias" for the original font name. These files are named -'texfonts.map' and searched for along the 'TEXFONTMAPS' -environment/config file variable. All 'texfonts.map' files that are -found are read; earlier definitions override later ones. - - This feature is intended to help in two respects: - - 1. An alias name is limited in length only by available memory, not by - your filesystem. Therefore, if you want to ask for 'Times-Roman' - instead of 'ptmr', you can (you get 'ptmr8r'). - - 2. A few fonts have historically had multiple names: specifically, - LaTeX's "circle font" has variously been known as 'circle10', - 'lcircle10', and 'lcirc10'. Aliases can make all the names - equivalent, so that it no longer matters what the name of the - installed file is; TeX documents will find their favorite name. - - The format of fontmap files is straightforward: - - * Comments start with the last '%' on a line and continue to the end - of the line. (This provides for names that include a %, - ill-advised as that may be.) - - * Blank lines are ignored. - - * Each nonblank line is broken up into a series of "words": a - sequence of non-whitespace characters. - - * If the first word is 'include', the second word is used as a - filename, and it is searched for and read. - - * Otherwise, the first word on each line is the true filename; - - * the second word is the alias; - - * subsequent words are ignored. - - If an alias has an extension, it matches only those files with that -extension; otherwise, it matches anything with the same root, regardless -of extension. For example, an alias 'foo.tfm' matches only when -'foo.tfm' is being searched for; but an alias 'foo' matches 'foo.vf', -'foo.600pk', etc. - - As an example, here is an excerpt from the 'texfonts.map' in the -Web2c distribution. It makes the old and new names of the LaTeX circle -fonts equivalent. - - circle10 lcircle10 - circle10 lcirc10 - lcircle10 circle10 - lcircle10 lcirc10 - lcirc10 circle10 - lcirc10 lcircle10 - ... - - Fontmaps are implemented in the file 'kpathsea/fontmap.c'. The -Fontname distribution has much more information on font naming (*note -(fontname)::). - - -File: kpathsea.info, Node: Fallback font, Prev: Fontmap, Up: Glyph lookup - -6.3.3 Fallback font -------------------- - -If a bitmap font cannot be found or created at the requested size, -Kpathsea looks for the font at a set of "fallback resolutions". You -specify these resolutions as a colon-separated list (like search paths). -Kpathsea looks first for a program-specific environment variable (e.g., -'DVIPSSIZES' for Dvipsk), then the environment variable 'TEXSIZES', then -a default specified at compilation time (the Make variable -'default_texsizes'). You can set this list to be empty if you prefer to -find fonts at their stated size or not at all. - - Finally, if the font cannot be found even at the fallback -resolutions, Kpathsea looks for a fallback font, typically 'cmr10'. -Programs must enable this feature by calling 'kpathsea_init_prog' (*note -Calling sequence::); the default is no fallback font. - - -File: kpathsea.info, Node: Suppressing warnings, Next: mktex scripts, Prev: Glyph lookup, Up: TeX support - -6.4 Suppressing warnings -======================== - -Kpathsea provides a way to suppress selected usually-harmless warnings; -this is useful at large sites where most users are not administrators, -and thus the warnings are merely a source of confusion, not a help. To -do this, you set the environment variable or configuration file value -'TEX_HUSH' to a colon-separated list of values. Here are the -possibilities: - -'all' - Suppress everything possible. - -'checksum' - Suppress mismatched font checksum warnings. - -'lostchar' - Suppress warnings when a character is missing from a font that a - DVI or VF file tries to typeset. - -'none' - Don't suppress any warnings. - -'readable' - Suppress warnings about attempts to access a file whose permissions - render it unreadable. - -'special' - Suppresses warnings about an unimplemented or unparsable '\special' - command. - -'tex-hush.c' defines the function that checks the variable value. Each -driver implements its own checks where appropriate. - - -File: kpathsea.info, Node: mktex scripts, Prev: Suppressing warnings, Up: TeX support - -6.5 'mktex' scripts -=================== - -If Kpathsea cannot otherwise find a file, for some file types it is -configured by default to invoke an external program to create it -dynamically (*note mktex configuration::). These are collectively known -as "'mktex' scripts", since most of them are named 'mktex...'. - - For example, this is useful for fonts (bitmaps, TFM's, and -arbitrarily-sizable Metafont sources such as the Sauter and EC fonts), -since any given document can use fonts never before referenced. -Building all fonts in advance is therefore impractical, if not -impossible. - - It is also useful for the TeX '.fmt' (and Metafont '.base' and -Metapost '.mem' files, *note (Web2c)Memory dumps::), where -pre-generating every format consumes a lot of both time and space. - - The script is passed the name of the file to create and possibly -other arguments, as explained below. It must echo the full pathname of -the file it created (and nothing else) to standard output; it can write -diagnostics to standard error. - -* Menu: - -* config: mktex configuration. -* names: mktex script names. -* args: mktex script arguments. - - -File: kpathsea.info, Node: mktex configuration, Next: mktex script names, Up: mktex scripts - -6.5.1 'mktex' configuration ---------------------------- - -The list of file types and program names that can run an external -program to create missing files is listed in the next section. In the -absence of 'configure' options specifying otherwise, everything but -'mktextex' will be enabled by default. The 'configure' options to -change the defaults are: - - --without-mktexfmt-default - --without-mktexmf-default - --without-mktexocp-default - --without-mktexofm-default - --without-mktexpk-default - --without-mktextfm-default - --with-mktextex-default - - The 'configure' setting is overridden if the environment variable or -configuration file value named for the script is set; e.g., 'MKTEXPK' -(*note mktex script arguments::). - - 'mktexfmt' reads a file 'fmtutil.cnf', typically located in -'texmf/web2c/' to glean its configuration information. The rest of the -files and features in this section are primarily intended for the font -generation scripts. - - As distributed, all the scripts source a file 'texmf/web2c/mktex.cnf' -if it exists, so you can override various defaults. See 'mktex.opt', -for instance, which defines the default mode, resolution, some special -directory names, etc. If you prefer not to change the distributed -scripts, you can simply create 'mktex.cnf' with the appropriate -definitions (you do not need to create it if you have nothing to put in -it). 'mktex.cnf' has no special syntax; it's an arbitrary Bourne shell -script. The distribution contains a sample 'mktex.cnf' for you to copy -and modify as you please (it is not installed anywhere). - - In addition, you can configure a number of features with the -'MT_FEATURES' variable, which you can define: - - * in 'mktex.opt', as just mentioned; - - * by editing the file 'mktex.opt', either before 'make install' (in - the source hierarchy) or after (in the installed hierarchy); - - * or in the environment. - - If none of the options below are enabled, 'mktexpk', 'mktextfm', and -'mktexmf' follow the following procedure to decide where fonts should be -installed. Find the tree where the font's sources are, and test the -permissions of the 'fonts' directory of that tree to determine whether -it is writable. If it is, put the files in the tree in appropriate -locations. If it isn't writable, see whether the tree is a system tree -(named in 'SYSTEXMF'). If so, the 'VARTEXFONTS' tree is used. In all -other cases the working directory is used. - - The 'appendonlydir' option is enabled by default. - -'appendonlydir' - Tell 'mktexdir' to create directories append-only, i.e., set their - sticky bit (*note (coreutils)Mode Structure::). This feature is - silently ignored on non-Unix platforms (e.g. Windows/NT and - MS-DOS) which don't support similar functionality. This feature is - enabled by default. - -'dosnames' - Use 8.3 names; e.g., 'dpi600/cmr10.pk' instead of 'cmr10.600pk'. - Note that this feature only affects filenames that would otherwise - clash with other TeX-related filenames; 'mktex' scripts do nothing - about filenames which exceed the 8+3 MS-DOS limits but remain - unique when truncated (by the OS) to these limits, and nether do - the scripts care about possible clashes with files which aren't - related with TeX. For example, 'cmr10.600pk' would clash with - 'cmr10.600gf' and is therefore changed when 'dosnames' is in - effect, but 'mf.pool' and 'mp.base' don't clash with any - TeX-related files and are therefore unchanged. - - This feature is turned on by default on MS-DOS. If you do not wish - 'dosnames' to be set on an MS-DOS platform, you need to set the - 'MT_FEATURES' environment variable to a value that doesn't include - 'dosnames'. You can also change the default setting by editing - 'mktex.opt', but only if you use the 'mktex' shell scripts; the - emulation programs don't consult 'mktex.opt'. - -'fontmaps' - Instead of deriving the location of a font in the destination tree - from the location of the sources, the aliases and directory names - from the Fontname distribution are used. (*note Introduction: - (fontname)Top.). - -'nomfdrivers' - Let mktexpk and mktextfm create metafont driver files in a - temporary directory. These will be used for just one metafont run - and not installed permanently. - -'nomode' - Omit the directory level for the mode name; this is fine as long as - you generate fonts for only one mode. - -'stripsupplier' - Omit the font supplier name directory level. - -'striptypeface' - Omit the font typeface name directory level. - -'strip' - Omit the font supplier and typeface name directory levels. This - feature is deprecated in favour of 'stripsupplier' and - 'striptypeface'. - -'varfonts' - When this option is enabled, fonts that would otherwise be written - in system texmf tree go to the 'VARTEXFONTS' tree instead. The - default value in 'kpathsea/Makefile.in' is '/var/tmp/texfonts'. - The 'Linux File System Standard' recommends '/var/tex/fonts'. - - The 'varfonts' setting in 'MT_FEATURES' is overridden by the - 'USE_VARTEXFONTS' environment variable: if set to '1', the feature - is enabled, and if set to '0', the feature is disabled. - -'texmfvar' - Force generated files that would go into a system tree (as defined - by 'SYSTEXMF') into 'TEXMFVAR'. Starting with teTeX-3.0, the - variable 'TEXMFVAR' is always set. The 'varfonts' feature takes - precedence if also set. - - The 'texmfvar' setting in 'MT_FEATURES' is overridden by the - 'USE_TEXMFVAR' environment variable: if set to '1', the feature is - enabled, and if set to '0', the feature is disabled. - - -File: kpathsea.info, Node: mktex script names, Next: mktex script arguments, Prev: mktex configuration, Up: mktex scripts - -6.5.2 'mktex' script names --------------------------- - -The following table shows the default name of the script for each of the -file types which support runtime generation. - -'mktexfmt' - ('.fmt', '.base', '.mem') TeX/Metafont/MetaPost formats. This - script is also named 'fmtutil', and reads 'fmtutil.cnf' for - configuration information. - -'mktexmf' - ('.mf') Metafont input files. - -'mkocp' - ('.ocp') Omega compiled process files. - -'mkofm' - ('.ofm') Omega font metric files. - -'mktexpk' - ('pk') Glyph fonts. - -'mktextex' - ('.tex') TeX input files (disabled by default). - -'mktextfm' - ('.tfm') TFM files. - -These names can be overridden by an environment variable specific to the -program--for example, 'DVIPSMAKEPK' for Dvipsk. - - If a 'mktex...' script fails, the invocation is appended to a file -'missfont.log' (by default) in the current directory. You can then -execute the log file to create the missing files after fixing the -problem. - - If the current directory is not writable and the environment variable -or configuration file value 'TEXMFOUTPUT' is set, its value is used. -Otherwise, nothing is written. The name 'missfont.log' is overridden by -the 'MISSFONT_LOG' environment variable or configuration file value. - - -File: kpathsea.info, Node: mktex script arguments, Prev: mktex script names, Up: mktex scripts - -6.5.3 'mktex' script arguments ------------------------------- - -The first argument to a 'mktex' script is always the name of the file to -be created. - - In the default 'mktexpk' implementation, additional arguments may -also be passed: - -'--dpi NUM' - Sets the resolution of the generated font to NUM. -'--mfmode NAME' - Sets the Metafont mode to NAME. -'--bdpi NUM' - Sets the "base dpi" for the font. This must match the mode being - used. -'--mag STRING' - A "magstep" string suitable for the Metafont 'mag' variable. This - must match the combination of BDPI and DPI being used. -'--destdir STRING' - A directory name. If the directory is absolute, it is used as-is. - Otherwise, it is appended to the root destination directory set in - the script. - - -File: kpathsea.info, Node: Programming, Next: Reporting bugs, Prev: TeX support, Up: Top - -7 Programming -************* - -This chapter is for programmers who wish to use Kpathsea. *Note -Introduction::, for the conditions under which you may do so (in short, -it is released under LGPLv2.1 or later). - -* Menu: - -* Overview: Programming overview. Introduction. -* Calling sequence:: Specifics of what to call. -* Program-specific files:: How to handle these. -* Config: Programming with config files. Getting info from texmf.cnf. - - -File: kpathsea.info, Node: Programming overview, Next: Calling sequence, Up: Programming - -7.1 Programming overview -======================== - -Aside from this manual, your best source of information is the source to -the programs that use Kpathsea (*note Introduction::). First, Kpsewhich -is a small utility program whose sole purpose is to exercise the main -path-searching functionality. Of the drivers, Dviljk is probably the -simplest full application program. 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. - - When looking at these program sources, you should know that previous -versions of the library had a different programming interface; the -current interface supports re-entrancy. Historically, 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. The old functions will never disappear, and can -reliably continue to be used when they suffice, as they do for the -programs above. The main application using the re-entrant API is the -MetaPost library used by MetaPost and LuaTeX. - - 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. - - -File: kpathsea.info, Node: Calling sequence, Next: Program-specific files, Prev: Programming overview, Up: Programming - -7.2 Calling sequence -==================== - -The typical way to use Kpathsea in your program goes something like -this: - - 1. Call 'kpathsea_new' to create a new library instance. This - variable must be passed as the first argument to all the following - library functions. The rest of this manual will be using 'kpse' as - a placeholder for the name of this variable. - - 2. Call 'kpathsea_set_program_name' with 'argv[0]' as the second - argument; the third argument is a string or 'NULL'. The third - argument is used by Kpathsea as the program name for the '.PROGRAM' - feature of config files (*note Config files::). If the third - argument is 'NULL', the value of the second argument is used. This - function must be called before any other use of the Kpathsea - library. - - 'kpathsea_set_program_name' always sets the variables - 'kpse->invocation_name' and 'kpse->invocation_short_name'. These - variables are used in the error message macros defined in - 'kpathsea/lib.h'. It sets the variable 'kpse->program_name' to the - program name it uses. - - It also initializes debugging options based on the environment - variable 'KPATHSEA_DEBUG' (if that is set). - - Finally, it sets the environment variables 'SELFAUTOLOC', - 'SELFAUTODIR' and 'SELFAUTOPARENT' to the location, parent and - grandparent directory of the executable, removing '.' and '..' path - elements and resolving symbolic links. These are used in the - default configuration file to allow people to invoke TeX from - anywhere. You can use 'kpsewhich --expand-var=\$SELFAUTOLOC', - etc., to see the values. - - 3. Set debugging options. *Note Debugging::. If your program doesn't - have a debugging option already, you can define one and set - 'kpse->debug' to the number that the user supplies (as in Dviljk - and Web2c), or you can just omit this altogether (people can always - set 'KPATHSEA_DEBUG'). If you do have runtime debugging already, - you need to merge Kpathsea's options with yours (as in Dvipsk and - Xdvik). - - 4. If your program has its own configuration files that can define - search paths, you should assign those paths to the 'client_path' - member in the appropriate element of the 'kpse->format_info' array. - (This array is indexed by file type; see 'tex-file.h'.) See - 'resident.c' in Dvipsk for an example. - - 5. Call 'kpathsea_init_prog' (see 'proginit.c'). It's useful for the - DVI drivers, at least, but for other programs it may be simpler to - extract the parts of it that actually apply. This does not - initialize any paths, it just looks for (and sets) certain - environment variables and other random information. (A search path - is always initialized at the first call to find a file of that - type; this eliminates much useless work, e.g., initializing the - BibTeX search paths in a DVI driver.) - - 6. The routine to actually find a file of type FORMAT is - 'kpathsea_find_file'. You can call 'kpathsea_find_file' after - doing only the first and second of the initialization steps - above--Kpathsea automatically reads the 'texmf.cnf' generic config - files, looks for environment variables, and does expansions at the - first lookup. - - 7. To find PK and/or GF bitmap fonts, the routine is - 'kpathsea_find_glyph', defined in 'tex-glyph.h'. This returns a - structure in addition to the resultant filename, because fonts can - be found in so many ways. See the documentation in the source. - - 8. To actually open a file, not just return a filename, call - 'kpathsea_open_file'. This function takes the name to look up and - a Kpathsea file format as arguments, and returns the usual 'FILE - *'. It always assumes the file must exist, and thus will search - the disk if necessary (unless the search path specified '!!', - etc.). In other words, if you are looking up a VF or some other - file that need not exist, don't use this. - - 9. TeX can write output files, via the '\openout' primitive; this - opens a security hole vulnerable to Trojan horse attack: an - unwitting user could run a TeX program that overwrites, say, - '~/.rhosts'. Analogous security holes exist for many other - programs. To alleviate this, there is a configuration variable - 'openout_any', which selects one of three levels of security. When - it is set to 'a' (for "any"), no restrictions are imposed. When it - is set to 'r' (for "restricted"), filenames beginning with '.' are - disallowed (except '.tex' because LaTeX needs it). When it is set - to 'p' (for "paranoid") additional restrictions are imposed: an - absolute filename must refer to a file in (a subdirectory) of - 'TEXMFOUTPUT', and any attempt to go up a directory level is - forbidden (that is, paths may not contain a '..' component). The - paranoid setting is the default. (For backwards compatibility, 'y' - and '1' are synonyms of 'a', while 'n' and '0' are synonyms for - 'r'.) The function 'kpathsea_out_name_ok', with a filename as - second argument, returns 'true' if that filename is acceptable to - be opend for output or 'false' otherwise. - - 10. Similarly, the function 'kpathsea_in_name_ok', with a filename as - second argument, returns 'true' if that filename is acceptable to - be opend for input or 'false' otherwise, depending on the value of - the configuration variable 'openin_any' (with 'a' as default). - - 11. To close the kpathsea library instance you are using, call - 'kpathsea_finish'. This function closes any open log files and - frees the memory used by the instance. - - Kpathsea also provides many utility routines. Some are generic: hash -tables, memory allocation, string concatenation and copying, string -lists, reading input lines of arbitrary length, etc. Others are -filename-related: default path, tilde, and variable expansion, 'stat' -calls, etc. (Perhaps someday I'll move the former to a separate -library.) - - The 'c-*.h' header files can also help your program adapt to many -different systems. You will almost certainly want to use Autoconf and -probably Automake for configuring and building your software if you use -Kpathsea; I strongly recommend using Autoconf and Automake regardless. -They are available from <https://gnu.org/software>. - - -File: kpathsea.info, Node: Program-specific files, Next: Programming with config files, Prev: Calling sequence, Up: Programming - -7.3 Program-specific files -========================== - -Many programs will need to find some configuration files. Kpathsea -contains some support to make it easy to place them in their own -directories. The Standard TeX directory structure (*note Introduction: -(tds)Top.), specifies that such files should go into a subdirectory -named after the program, like 'texmf/ttf2pk'. - - Two formats, 'kpse_program_text_format' and -'kpse_program_binary_format', use '.:$TEXMF/PROGRAM//' as their -compiled-in search path. To override this default, you can use the -variable 'PROGRAMINPUTS' in the environment and/or 'texmf.cnf'. That is -to say, the name of the variable is constructed by converting the name -of the program to upper case, and appending 'INPUTS'. - - The only difference between these two formats is whether -'kpathsea_open_file' will open the files it finds in text or binary -mode. - - -File: kpathsea.info, Node: Programming with config files, Prev: Program-specific files, Up: Programming - -7.4 Programming with config files -================================= - -You can (and probably should) use the same 'texmf.cnf' configuration -file that Kpathsea uses for your program. This helps installers by -keeping all configuration in one place. - - To retrieve a value for a configuration variable VAR, the best way is -to call 'kpathsea_var_value' on the string 'VAR'. This will look first -for an environment variable VAR, then a config file value. The result -will be the value found or 'NULL'. This function is declared in -'kpathsea/variable.h'. For an example, see the 'shell_escape' code in -'web2c/lib/texmfmp.c'. - - The routine to do full variable and tilde expansion of an arbitrary -string in the context of a search path (as opposed to simply retrieving -a value) is 'kpathsea_var_expand', also declared in -'kpathsea/variable.h'. However, it's generally only necessary to set -the search path structure components as explained in the previous -section instead of using this directly. Because of its usage with any -input string, undefined '$FOO' constructs in the argument to -'kpathsea_var_expand' are returned literally ('"$FOO"'), while undefined -'${FOO}' constructs are expanded to the empty string. - - If for some reason you want to retrieve a value _only_ from a config -file, not automatically looking for a corresponding environment -variable, call 'kpathsea_cnf_get' (declared in 'kpathsea/cnf.h') with -the string VAR. - - No initialization calls are needed. - - -File: kpathsea.info, Node: Reporting bugs, Next: Index, Prev: Programming, Up: Top - -8 Reporting bugs -**************** - -If you have problems or suggestions, please report them to -<tex-k@tug.org> using the bug checklist below. - - Please report bugs in the documentation; not only factual errors or -inconsistent behavior, but unclear or incomplete explanations, typos, -wrong fonts, ... - -* Menu: - -* Bug checklist:: What to include in a good bug report. -* Mailing lists:: Joining the bugs or announcements mailing lists. -* Debugging:: Analyzing runtime problems. -* Logging:: Recording searches. -* Common problems:: When things go wrong. - - -File: kpathsea.info, Node: Bug checklist, Next: Mailing lists, Up: Reporting bugs - -8.1 Bug checklist -================= - -Before reporting a bug, please check below to be sure it isn't already -known (*note Common problems::). - - Bug reports should be sent via electronic mail to <tex-k@tug.org>. - - The general principle is that a good bug report includes all the -information necessary for reproduction. Therefore, to enable -investigation, your report should include the following: - - * The version number(s) of the program(s) involved, and of Kpathsea - itself. You can get the former by giving a sole option '--version' - to the program, and the latter by running 'kpsewhich --version'. - The 'NEWS' and 'ChangeLog' files also contain the version number. - - * The hardware, operating system (including version), compiler, and - 'make' program you are using (the output of 'uname -a' is a start - on the first two, though incomplete). - - * Any options you gave to 'configure'. This is recorded in the - 'config.status' files. - - If you are reporting a bug in 'configure' itself, it's probably - system-dependent, and it will be unlikely the maintainers can do - anything useful if you merely report that thus-and-such is broken. - Therefore, you need to do some additional work: for some bugs, you - can look in the file 'config.log' where the test that failed should - appear, along with the compiler invocation and source program in - question. You can then compile it yourself by hand, and discover - why the test failed. Other 'configure' bugs do not involve the - compiler; in that case, the only recourse is to inspect the - 'configure' shell script itself, or the Autoconf macros that - generated 'configure'. - - * The log of all debugging output, if the bug is in path searching. - You can get this by setting the environment variable - 'KPATHSEA_DEBUG' to '-1' before running the program. Please look - at the log yourself to make sure the behavior is really a bug - before reporting it; perhaps "old" environment variable settings - are causing files not to be found, for example. - - * The contents of any input files necessary to reproduce the bug. - For bugs in DVI-reading programs, for example, this generally means - a DVI file (and any EPS or other files it uses)--TeX source files - are helpful, but the DVI file is required, because that's the - actual program input. - - * If you are sending a patch (do so if you can!), please do so in the - form of a context diff ('diff -c') against the original - distribution source. Any other form of diff is either not as - complete or harder for me to understand. Please also include a - 'ChangeLog' entry. - - * If the bug involved is an actual crash (i.e., core dump), it is - easy and useful to include a stack trace from a debugger (I - recommend the GNU debugger GDB (<https://gnu.org/software/gdb>). - If the cause is apparent (a 'NULL' value being dereferenced, for - example), please send the details along. If the program involved - is TeX or Metafont, and the crash is happening at apparently-sound - code, however, the bug may well be in the compiler, rather than in - the program or the library (*note TeX or Metafont failing: TeX or - Metafont failing.). - - * Any additional information that will be helpful in reproducing, - diagnosing, or fixing the bug. - - -File: kpathsea.info, Node: Mailing lists, Next: Debugging, Prev: Bug checklist, Up: Reporting bugs - -8.2 Mailing lists -================= - -Web2c and Kpathsea in general are discussed on the mailing list -<tex-k@tug.org>. You can subscribe and peruse the archives on the web -<https://lists.tug.org/tex-k>. - - You do not need to join to submit a report, nor will it affect -whether you get a response. Be aware that large data files are -sometimes included in bug reports. If this is a problem for you, do not -join the list. - - If you are looking for general TeX help, such as how to install a -full TeX system or how to use LaTeX, please see -<https://tug.org/begin.html>. - - -File: kpathsea.info, Node: Debugging, Next: Logging, Prev: Mailing lists, Up: Reporting bugs - -8.3 Debugging -============= - -Kpathsea provides a number of runtime debugging options, detailed below -by their names and corresponding numeric values. When the files you -expect aren't being found, the thing to do is enable these options and -examine the output. - - You can set these with some runtime argument (e.g., '-d') to the -program; in that case, you should use the numeric values described in -the program's documentation (which, for Dvipsk and Xdvik, are different -than those below). It's best to give the '-d' (or whatever) option -first, for maximal output. Dvipsk and Xdvik have additional -program-specific debugging options as well. - - You can also set the environment variable 'KPATHSEA_DEBUG'; in this -case, you should use the numbers below. If you run the program under a -debugger and set the instance variable 'kpse->debug', also use the -numbers below. - - In any case, by far the simplest value to use is '-1', which will -turn on all debugging output. This is usually better than guessing -which particular values will yield the output you need. - - Debugging output always goes to standard error, so you can redirect -it easily. For example, in Bourne-compatible shells: - dvips -d -1 ... 2>/tmp/debug - - It is sometimes helpful to run the standalone Kpsewhich utility -(*note Invoking kpsewhich::), instead of the original program. - - In any case, you cannot use the names below; you must always use -somebody's numbers. (Sorry.) To set more than one option, just sum the -corresponding numbers. - -'KPSE_DEBUG_STAT (1)' - Report 'stat'(2) calls. This is useful for verifying that your - directory structure is not forcing Kpathsea to do many additional - file tests (*note Slow path searching::, and *note Subdirectory - expansion::). If you are using an up-to-date 'ls-R' database - (*note Filename database::), this should produce no output unless a - nonexistent file that must exist is searched for. - -'KPSE_DEBUG_HASH (2)' - Report lookups in all hash tables: 'ls-R' and 'aliases' (*note - Filename database::); font aliases (*note Fontmap::); and config - file values (*note Config files::). Useful when expected values - are not being found, e.g.., file searches are looking at the disk - instead of using 'ls-R'. - -'KPSE_DEBUG_FOPEN (4)' - Report file openings and closings. Especially useful when your - system's file table is full, for seeing which files have been - opened but never closed. In case you want to set breakpoints in a - debugger: this works by redefining 'fopen' ('fclose') to be - 'kpse_fopen_trace' ('kpse_fclose_trace'). - -'KPSE_DEBUG_PATHS (8)' - Report general path information for each file type Kpathsea is - asked to search. This is useful when you are trying to track down - how a particular path got defined--from 'texmf.cnf', 'config.ps', - an environment variable, the compile-time default, etc. This is - the contents of the 'kpse_format_info_type' structure defined in - 'tex-file.h'. - -'KPSE_DEBUG_EXPAND (16)' - Report the directory list corresponding to each path element - Kpathsea searches. This is only relevant when Kpathsea searches - the disk, since 'ls-R' searches don't look through directory lists - in this way. - -'KPSE_DEBUG_SEARCH (32)' - Report on each file search: the name of the file searched for, the - path searched in, whether or not the file must exist (when drivers - search for 'cmr10.vf', it need not exist), and whether or not we - are collecting all occurrences of the file in the path (as with, - e.g., 'texmf.cnf' and 'texfonts.map'), or just the first (as with - most lookups). This can help you correlate what Kpathsea is doing - with what is in your input file. - -'KPSE_DEBUG_VARS (64)' - Report the value of each variable Kpathsea looks up. This is - useful for verifying that variables do indeed obtain their correct - values. - -'GSFTOPK_DEBUG (128)' - Activates debugging printout specific to 'gsftopk' program. - -'MAKETEX_DEBUG (512)' - If you use the optional 'mktex' programs instead of the traditional - shell scripts, this will report the name of the site file - ('mktex.cnf' by default) which is read, directories created by - 'mktexdir', the full path of the 'ls-R' database built by - 'mktexlsr', font map searches, 'MT_FEATURES' in effect, parameters - from 'mktexnam', filenames added by 'mktexupd', and some subsidiary - commands run by the programs. - -'MAKETEX_FINE_DEBUG (1024)' - When the optional 'mktex' programs are used, this will print - additional debugging info from functions internal to these - programs. - - Debugging output from Kpathsea is always written to standard error, -and begins with the string 'kdebug:'. (Except for hash table buckets, -which just start with the number, but you can only get that output -running under a debugger. See comments at the 'hash_summary_only' -variable in 'kpathsea/db.c'.) - - -File: kpathsea.info, Node: Logging, Next: Common problems, Prev: Debugging, Up: Reporting bugs - -8.4 Logging -=========== - -Kpathsea can record the time and filename found for each successful -search. This may be useful in finding good candidates for deletion when -your filesystem is full, or in discovering usage patterns at your site. - - To do this, define the environment or config file variable -'TEXMFLOG'. The value is the name of the file to append the information -to. The file is created if it doesn't exist, and appended to if it -does. - - Each successful search turns into one line in the log file: two words -separated by a space. The first word is the time of the search, as the -integer number of seconds since "the epoch", i.e., UTC midnight 1 -January 1970 (more precisely, the result of the 'time' system call). -The second word is the filename. - - For example, after 'setenv TEXMFLOG /tmp/log', running Dvips on -'story.dvi' appends the following lines: - - 774455887 /usr/local/share/texmf/dvips/config.ps - 774455887 /usr/local/share/texmf/dvips/psfonts.map - 774455888 /usr/local/share/texmf/dvips/texc.pro - 774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk - 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk - 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk - 774455889 /usr/local/share/texmf/dvips/texc.pro - -Only filenames that are absolute are recorded, to preserve some -semblance of privacy. - - In addition to this Kpathsea-specific logging, 'pdftex' provides an -option '-recorder' to write the names of all files accessed during a run -to the file 'BASEFILE.fls'. - - Finally, most systems provide a general tool to output each system -call, thus including opening and closing files. It might be named -'strace', 'truss', 'struss', or something else. - - -File: kpathsea.info, Node: Common problems, Prev: Logging, Up: Reporting bugs - -8.5 Common problems -=================== - -Here are some common problems with configuration, compilation, linking, -execution, ... - -* Menu: - -* Unable to find files:: If your program can't find fonts (or whatever). -* Slow path searching:: If it takes forever to find anything. -* Unable to generate fonts:: If mktexpk fails. -* TeX or Metafont failing:: Likely compiler bugs. - - -File: kpathsea.info, Node: Unable to find files, Next: Slow path searching, Up: Common problems - -8.5.1 Unable to find files --------------------------- - -If a program complains it cannot find fonts (or other input files), any -of several things might be wrong. In any case, you may find the -debugging options helpful. *Note Debugging::. - - * Perhaps you simply haven't installed all the necessary files; the - basic fonts and input files are distributed separately from the - programs. *Note unixtex.ftp::. - - * You have (perhaps unknowingly) told Kpathsea to use search paths - that don't reflect where the files actually are. One common cause - is having environment variables set from a previous installation, - thus overriding what you carefully set in 'texmf.cnf' (*note - Supported file formats::). System '/etc/profile' or other files - such may be the culprit. - - * Your files reside in a directory that is only pointed to via a - symbolic link, in a leaf directory and is not listed in 'ls-R'. - - Unfortunately, Kpathsea's subdirectory searching has an - irremediable deficiency: If a directory D being searched for - subdirectories contains plain files and symbolic links to other - directories, but no true subdirectories, D will be considered a - leaf directory, i.e., the symbolic links will not be followed. - *Note Subdirectory expansion::. - - You can work around this problem by creating an empty dummy - subdirectory in D. Then D will no longer be a leaf, and the - symlinks will be followed. - - The directory immediately followed by the '//' in the path - specification, however, is always searched for subdirectories, even - if it is a leaf. Presumably you would not have asked for the - directory to be searched for subdirectories if you didn't want it - to be. - - * If the fonts (or whatever) don't already exist, 'mktexpk' (or - 'mktexmf' or 'mktextfm') will try to create them. If these rather - complicated shell scripts fail, you'll eventually get an error - message saying something like 'Can't find font FONTNAME'. The best - solution is to fix (or at least report) the bug in 'mktexpk'; the - workaround is to generate the necessary fonts by hand with - Metafont, or to grab them from a CTAN site (*note unixtex.ftp::). - - * There is a bug in the library. *Note Reporting bugs::. - - -File: kpathsea.info, Node: Slow path searching, Next: Unable to generate fonts, Prev: Unable to find files, Up: Common problems - -8.5.2 Slow path searching -------------------------- - -If your program takes an excessively long time to find fonts or other -input files, but does eventually succeed, here are some possible -culprits: - - * Most likely, you just have a lot of directories to search, and that - takes a noticeable time. The solution is to create and maintain a - separate 'ls-R' file that lists all the files in your main TeX - hierarchy. *Note Filename database::. Kpathsea always uses 'ls-R' - if it's present; there's no need to recompile or reconfigure any of - the programs. - - * Your recursively-searched directories (e.g., - '/usr/local/share/texmf/fonts//'), contain a mixture of files and - directories. This prevents Kpathsea from using a useful - optimization (*note Subdirectory expansion::). - - It is best to have only directories (and perhaps a 'README') in the - upper levels of the directory structure, and it's very important to - have _only_ files, and no subdirectories, in the leaf directories - where the dozens of TFM, PK, or whatever files reside. - - In any case, you may find the debugging options helpful in -determining precisely when the disk or network is being pounded. *Note -Debugging::. - - -File: kpathsea.info, Node: Unable to generate fonts, Next: TeX or Metafont failing, Prev: Slow path searching, Up: Common problems - -8.5.3 Unable to generate fonts ------------------------------- - -Metafont outputs fonts in bitmap format, tuned for a particular device -at a particular resolution, in order to allow for the highest-possible -quality of output. Some DVI-to-whatever programs, such as Dvips, try to -generate these on the fly when they are needed, but this generation may -fail in several cases. - - If 'mktexpk' runs, but fails with this error: - mktexpk: Can't guess mode for NNN dpi devices. - mktexpk: Use a config file to specify the mode, or update me. - you need to ensure the resolution and mode match; just specifying the -resolution, as in '-D 360', is not enough. - - You can specify the mode name with the '-mode' option on the Dvips -command line, or in a Dvips configuration file (*note (dvips)Config -files::), such as 'config.ps' in your document directory, '~/.dvipsrc' -in your home directory, or in a system directory (again named -'config.ps'). (Other drivers use other files, naturally.) - - For example, if you need 360dpi fonts, you could include this in a -configuration file: - D 360 - M lqmed - - If Metafont runs, but generates fonts at the wrong resolution or for -the wrong device, most likely 'mktexpk''s built-in guess for the mode is -wrong, and you should override it as above. - - See <https://ctan.org/pkg/modes> for a list of resolutions and mode -names for most devices (additional submissions are welcome). - - If Metafont runs but generates fonts at a resolution of 2602dpi (and -prints out the name of each character as well as just a character -number, and maybe tries to display the characters), then your Metafont -base file probably hasn't been made properly. (It's using the default -'proof' mode, instead of an actual device mode.) To make a proper -'plain.base', assuming the local mode definitions are contained in a -file 'modes.mf', run the following command (assuming Unix): - - inimf "plain; input modes; dump" - -Then copy the 'plain.base' file from the current directory to where the -base files are stored on your system ('/usr/local/share/texmf/web2c' by -default), and make a link (either hard or soft) from 'plain.base' to -'mf.base' in that directory. *Note (web2c)inimf invocation::. - - If 'mf' is a command not found at all by 'mktexpk', then you need to -install Metafont (*note unixtex.ftp::). - - -File: kpathsea.info, Node: TeX or Metafont failing, Prev: Unable to generate fonts, Up: Common problems - -8.5.4 TeX or Metafont failing ------------------------------ - -If TeX or Metafont get a segmentation fault or otherwise fail while -running a normal input file, the problem is usually a compiler bug -(unlikely as that may sound). Even if the trip and trap tests are -passed, problems may lurk. Optimization occasionally causes trouble in -programs other than TeX and Metafont themselves, too. - - For a workaround, if you enabled any optimization flags, it's best to -omit optimization entirely. In any case, the way to find the facts is -to run the program under the debugger and see where it's failing. - - Also, if you have trouble with a system C compiler, I advise trying -the GNU C compiler. And vice versa, unfortunately; but in that case I -also recommend reporting a bug to the GCC mailing list; see *note -(gcc)Bugs::. - - To report compiler bugs effectively requires perseverance and -perspicacity: you must find the miscompiled line, and that usually -involves delving backwards in time from the point of error, checking -through TeX's (or whatever program's) data structures. Good luck. - - -File: kpathsea.info, Node: Index, Prev: Reporting bugs, Up: Top - -Index -***** - - -* Menu: - -* !! and casefolding: Casefolding examples. - (line 57) -* !! in path specifications: ls-R. (line 57) -* !! in 'TEXMFDBS': ls-R. (line 11) -* $ expansion: Variable expansion. (line 6) -* --all: Path searching options. - (line 12) -* --casefold-search: Path searching options. - (line 19) -* --cnf-line: Path searching options. - (line 28) -* '--cnf-line', source for path: Path sources. (line 9) -* --color=tty: ls-R. (line 25) -* --debug=NUM: Auxiliary tasks. (line 9) -* --dpi=NUM: Path searching options. - (line 49) -* --engine=NAME: Path searching options. - (line 53) -* --expand-braces=STRING: Auxiliary tasks. (line 12) -* --expand-path=STRING: Auxiliary tasks. (line 16) -* --expand-var=STRING: Auxiliary tasks. (line 34) -* --format=NAME: Path searching options. - (line 69) -* --help: Standard options. (line 8) -* --help-formats: Auxiliary tasks. (line 42) -* --interactive: Path searching options. - (line 151) -* --mktex=FILETYPE: Path searching options. - (line 156) -* --mode=STRING: Path searching options. - (line 162) -* --must-exist: Path searching options. - (line 167) -* --no-casefold-search: Path searching options. - (line 19) -* --no-mktex=FILETYPE: Path searching options. - (line 156) -* --path=STRING: Path searching options. - (line 172) -* --progname=NAME: Path searching options. - (line 180) -* --safe-in-name=NAME: Auxiliary tasks. (line 48) -* --safe-out-name=NAME: Auxiliary tasks. (line 48) -* --show-path=NAME: Auxiliary tasks. (line 54) -* --subdir=STRING: Path searching options. - (line 185) -* --var-brace-value=VARIABLE: Auxiliary tasks. (line 60) -* --var-value=VARIABLE: Auxiliary tasks. (line 74) -* --version: Standard options. (line 11) -* --with-mktextex-default: mktex configuration. (line 12) -* --without-mktexfmt-default: mktex configuration. (line 12) -* --without-mktexmf-default: mktex configuration. (line 12) -* --without-mktexocp-default: mktex configuration. (line 12) -* --without-mktexofm-default: mktex configuration. (line 12) -* --without-mktexpk-default: mktex configuration. (line 12) -* --without-mktextfm-default: mktex configuration. (line 12) -* -1 debugging value: Debugging. (line 23) -* -A option to 'ls': ls-R. (line 39) -* -D NUM: Path searching options. - (line 49) -* -iname, find predicate: Casefolding examples. - (line 78) -* -L option to 'ls': ls-R. (line 44) -* . directories, ignored: ls-R. (line 39) -* . files: ls-R. (line 39) -* .2602gf: Unable to generate fonts. - (line 36) -* .afm: Supported file formats. - (line 22) -* .base: Supported file formats. - (line 26) -* .bib: Supported file formats. - (line 30) -* .bltxml: Supported file formats. - (line 34) -* .bst: Supported file formats. - (line 38) -* .cid: Supported file formats. - (line 68) -* .cmap: Supported file formats. - (line 46) -* .cnf: Supported file formats. - (line 49) -* .dll: Supported file formats. - (line 42) -* .enc: Supported file formats. - (line 61) -* .eps: Supported file formats. - (line 79) -* .epsi: Supported file formats. - (line 79) -* .fea: Supported file formats. - (line 71) -* .fmt: Supported file formats. - (line 64) -* .ist: Supported file formats. - (line 84) -* .lig: Supported file formats. - (line 88) -* .map: Supported file formats. - (line 94) -* .mem: Supported file formats. - (line 97) -* .mf: Supported file formats. - (line 105) -* .mft: Supported file formats. - (line 113) -* .mlbib: Supported file formats. - (line 121) -* .mlbst: Supported file formats. - (line 125) -* .mp: Supported file formats. - (line 129) -* .ocp: Supported file formats. - (line 137) -* .ofm: Supported file formats. - (line 141) -* .opl: Supported file formats. - (line 148) -* .otp: Supported file formats. - (line 151) -* .ovf: Supported file formats. - (line 154) -* .ovp: Supported file formats. - (line 157) -* .pfa: Supported file formats. - (line 211) -* .pfb: Supported file formats. - (line 211) -* .pk: Supported file formats. - (line 164) -* .pool: Supported file formats. - (line 109) -* .pool <1>: Supported file formats. - (line 133) -* .pool <2>: Supported file formats. - (line 195) -* .pro: Supported file formats. - (line 169) -* .PROGNAME qualifier in 'texmf.cnf': Config files. (line 50) -* .rhosts, writable by TeX: Security. (line 10) -* .ris: Supported file formats. - (line 173) -* .sfd: Supported file formats. - (line 177) -* .so: Supported file formats. - (line 42) -* .tex: Supported file formats. - (line 180) -* .tex file, included in 'ls-R': ls-R. (line 39) -* .tfm: Supported file formats. - (line 199) -* .ttc: Supported file formats. - (line 207) -* .ttf: Supported file formats. - (line 207) -* .vf: Supported file formats. - (line 219) -* .w: Supported file formats. - (line 53) -* .web: Supported file formats. - (line 53) -* .web <1>: Supported file formats. - (line 223) -* / may not be /: Searching overview. (line 13) -* /, trailing in home directory: Tilde expansion. (line 19) -* //: Subdirectory expansion. - (line 6) -* /etc/profile: Unable to find files. - (line 14) -* /etc/profile and aliases: ls-R. (line 25) -* /var/tmp/texfonts: mktex configuration. (line 113) -* 2602gf: Unable to generate fonts. - (line 36) -* 8.3 filenames, using: mktex configuration. (line 68) -* : may not be :: Searching overview. (line 13) -* :: expansion: Default expansion. (line 6) -* ; translated to ':' in 'texmf.cnf': Config files. (line 66) -* = omitted in 'texmf.cnf' and misparsing: Config files. (line 93) -* \, line continuation in 'texmf.cnf': Config files. (line 37) -* \openin: Searching overview. (line 31) -* \special, suppressing warnings about: Suppressing warnings. - (line 31) -* { expansion: Brace expansion. (line 6) -* ~ expansion: Tilde expansion. (line 6) -* absolute filenames: Searching overview. (line 58) -* access system call: Casefolding examples. - (line 86) -* access warnings: Searching overview. (line 63) -* AFMFONTS: Supported file formats. - (line 22) -* aliases for fonts: Fontmap. (line 6) -* aliases, for filenames: Filename aliases. (line 6) -* all: Suppressing warnings. - (line 13) -* all matches, finding: Path searching options. - (line 12) -* alphabetical order, not: Subdirectory expansion. - (line 6) -* announcement mailing list: Mailing lists. (line 6) -* API, re-entrant: Programming overview. - (line 16) -* append-only directories and 'mktexpk': Security. (line 36) -* appendonlydir: mktex configuration. (line 60) -* Apple filesystem, case-insensitive: Casefolding rationale. - (line 6) -* arguments to 'mktex': mktex script arguments. - (line 6) -* argv[0]: Calling sequence. (line 14) -* autoconf, recommended: Calling sequence. (line 117) -* automounter, and 'ls-R': ls-R. (line 46) -* auxiliary tasks: Auxiliary tasks. (line 6) -* Bach, Johann Sebastian: Default expansion. (line 41) -* backslash-newline: Config files. (line 37) -* basic glyph lookup: Basic glyph lookup. (line 6) -* Berry, Karl: History. (line 12) -* BIBINPUTS: Supported file formats. - (line 30) -* BIBINPUTS <1>: Supported file formats. - (line 121) -* blank lines, in 'texmf.cnf': Config files. (line 35) -* BLTXMLINPUTS: Supported file formats. - (line 34) -* brace expansion: Brace expansion. (line 6) -* Breitenlohner, Peter: History. (line 78) -* BSTINPUTS: Supported file formats. - (line 38) -* BSTINPUTS <1>: Supported file formats. - (line 125) -* bug address: Reporting bugs. (line 6) -* bug checklist: Bug checklist. (line 6) -* bug mailing list: Mailing lists. (line 6) -* bugs, reporting: Reporting bugs. (line 6) -* c-*.h: Calling sequence. (line 117) -* c-auto.h: Programming overview. - (line 35) -* cache of fonts, local: Security. (line 22) -* calling sequence: Calling sequence. (line 6) -* casefolding examples: Casefolding examples. - (line 6) -* casefolding fallback rationale: Casefolding rationale. - (line 6) -* casefolding search: Casefolding search. (line 6) -* ChangeLog entry: Bug checklist. (line 52) -* checklist for bug reports: Bug checklist. (line 6) -* checksum: Suppressing warnings. - (line 16) -* circle fonts: Fontmap. (line 19) -* client_path in 'kpse->format_info': Calling sequence. (line 47) -* CLUAINPUTS: Supported file formats. - (line 42) -* CMAPFONTS: Supported file formats. - (line 46) -* cmr10, as fallback font: Fallback font. (line 15) -* cmr10.vf: Searching overview. (line 31) -* cnf.c: Config files. (line 112) -* cnf.h: Programming with config files. - (line 27) -* comments, in fontmap files: Fontmap. (line 27) -* comments, in 'texmf.cnf': Config files. (line 27) -* comments, making: Introduction. (line 29) -* common features in glyph lookup: Basic glyph lookup. (line 6) -* common problems: Common problems. (line 6) -* compilation value, source for path: Path sources. (line 23) -* compiler bugs: TeX or Metafont failing. - (line 6) -* compiler bugs, finding: TeX or Metafont failing. - (line 21) -* conditions for use: Introduction. (line 32) -* config files: Config files. (line 6) -* config files, for Kpathsea-using programs: Calling sequence. - (line 47) -* config files, programming with: Programming with config files. - (line 6) -* config.h: Programming overview. - (line 35) -* config.log: Bug checklist. (line 24) -* config.ps: Specially-recognized files. - (line 16) -* config.ps, search path for: Supported file formats. - (line 57) -* config.status: Bug checklist. (line 27) -* configuration bugs: Bug checklist. (line 27) -* configuration file, source for path: Path sources. (line 20) -* configuration files as shell scripts.: Config files. (line 86) -* configuration of 'mktex' scripts: mktex configuration. (line 6) -* 'configure' options for 'mktex' scripts: mktex configuration. - (line 12) -* context diff: Bug checklist. (line 52) -* continuation character: Config files. (line 37) -* core dumps, reporting: Bug checklist. (line 58) -* crashes, reporting: Bug checklist. (line 58) -* CWEBINPUTS: Supported file formats. - (line 53) -* database search: Searching overview. (line 17) -* database, for filenames: Filename database. (line 6) -* database, format of: Database format. (line 6) -* debug.h: Debugging. (line 6) -* debugger: Bug checklist. (line 58) -* debugging: Debugging. (line 6) -* debugging options, in Kpathsea-using program: Calling sequence. - (line 39) -* debugging output: Debugging. (line 27) -* default expansion: Default expansion. (line 6) -* default_texsizes: Fallback font. (line 6) -* device, wrong: Unable to generate fonts. - (line 29) -* directories, making append-only: mktex configuration. (line 61) -* directory permissions: Security. (line 51) -* directory structure, for TeX files: TeX directory structure. - (line 6) -* disabling 'mktex' scripts: mktex configuration. (line 6) -* disk search: Searching overview. (line 22) -* disk searching, avoiding: ls-R. (line 57) -* disk usage, reducing: Logging. (line 6) -* doc files: Supported file formats. - (line 185) -* DOS compatible names: mktex configuration. (line 68) -* dosnames: mktex configuration. (line 67) -* dot files: ls-R. (line 39) -* doubled colons: Default expansion. (line 6) -* dpiNNN directories: mktex configuration. (line 68) -* DVILJMAKEPK: mktex script names. (line 32) -* DVILJSIZES: Fallback font. (line 6) -* dvipdfmx.cfg: Specially-recognized files. - (line 19) -* DVIPSFONTS: Supported file formats. - (line 254) -* DVIPSHEADERS: Supported file formats. - (line 211) -* DVIPSMAKEPK: mktex script names. (line 32) -* DVIPSSIZES: Fallback font. (line 6) -* dynamic creation of files: mktex scripts. (line 6) -* EC fonts, and dynamic source creation: mktex scripts. (line 6) -* elt-dirs.c: Subdirectory expansion. - (line 41) -* elt-dirs.c <1>: Subdirectory expansion. - (line 48) -* enabling 'mktex' scripts: mktex configuration. (line 6) -* ENCFONTS: Supported file formats. - (line 61) -* engine name: Path searching options. - (line 53) -* environment variable, source for path: Path sources. (line 12) -* environment variables for TeX: Supported file formats. - (line 6) -* environment variables in paths: Variable expansion. (line 6) -* environment variables, old: Unable to find files. - (line 14) -* epoch, seconds since: Logging. (line 15) -* error message macros: Calling sequence. (line 22) -* examples, of casefolding searches: Casefolding examples. - (line 6) -* excessive startup time: Slow path searching. (line 6) -* expand.c: Brace expansion. (line 26) -* expanding symlinks: Calling sequence. (line 31) -* expansion, default: Default expansion. (line 6) -* expansion, path element: Searching overview. (line 49) -* expansion, search path: Path expansion. (line 6) -* expansion, subdirectory: Subdirectory expansion. - (line 6) -* expansion, tilde: Tilde expansion. (line 6) -* expansion, variable: Variable expansion. (line 6) -* explicitly relative filenames: Searching overview. (line 58) -* extensions, filename: File lookup. (line 24) -* externally-built filename database: Filename database. (line 6) -* extra colons: Default expansion. (line 6) -* failed 'mktex...' script invocation: mktex script names. (line 35) -* fallback font: Fallback font. (line 6) -* fallback resolutions: Fallback font. (line 6) -* FAQ, Kpathsea: Common problems. (line 6) -* Farwell, Matthew: Subdirectory expansion. - (line 22) -* file formats, supported: Supported file formats. - (line 6) -* file lookup: File lookup. (line 6) -* file permissions: Security. (line 47) -* file types, registering new: Programming overview. - (line 41) -* filename aliases: Filename aliases. (line 6) -* filename database: Filename database. (line 6) -* filenames, absolute or explicitly relative: Searching overview. - (line 58) -* files, unable to find: Unable to find files. - (line 6) -* filesystem search: Searching overview. (line 22) -* filesystem, case-(in)sensitive: Casefolding rationale. - (line 6) -* Findutils, GNU package: Casefolding examples. - (line 78) -* floating directories: Searching overview. (line 22) -* fmtutil: mktex script names. (line 10) -* fmtutil.cnf: Specially-recognized files. - (line 22) -* fmtutils.cnf: mktex configuration. (line 24) -* font alias files: Fontmap. (line 6) -* font generation failures: Unable to generate fonts. - (line 6) -* font of last resort: Fallback font. (line 6) -* font set, infinite: mktex scripts. (line 6) -* FONTCIDMAPS: Supported file formats. - (line 68) -* FONTFEATURES: Supported file formats. - (line 71) -* fontmap files: Fontmap. (line 6) -* fontmaps: mktex configuration. (line 86) -* fontmaps <1>: mktex configuration. (line 87) -* fontname: mktex configuration. (line 87) -* fontnames, arbitrary length: Fontmap. (line 15) -* FOOINPUTS: Supported file formats. - (line 236) -* FOOINPUTS <1>: Supported file formats. - (line 239) -* fopen, redefined: Debugging. (line 54) -* format of external database: Database format. (line 6) -* ftp.cs.stanford.edu: unixtex.ftp. (line 20) -* ftp.tug.org: unixtex.ftp. (line 6) -* fundamental purpose of Kpathsea: Introduction. (line 6) -* gdb, recommended: Bug checklist. (line 58) -* gf: Supported file formats. - (line 75) -* GFFONTS: Supported file formats. - (line 75) -* globally writable directories: Security. (line 30) -* glyph lookup: Glyph lookup. (line 6) -* glyph lookup bitmap tolerance: Basic glyph lookup. (line 15) -* GLYPHFONTS: Supported file formats. - (line 75) -* GLYPHFONTS <1>: Supported file formats. - (line 164) -* glyphlist.txt: Specially-recognized files. - (line 25) -* GNU C compiler bugs: TeX or Metafont failing. - (line 16) -* GNU General Public License: Introduction. (line 32) -* group-writable directories: Security. (line 40) -* GSFTOPK_DEBUG (128): Debugging. (line 88) -* hash table buckets, printing: Debugging. (line 105) -* hash table routines: Calling sequence. (line 110) -* hash_summary_only variable for debugging: Debugging. (line 105) -* history of Kpathsea: History. (line 6) -* Hoekwater, Taco: History. (line 78) -* home directories in paths: Tilde expansion. (line 6) -* HOME, as ~ expansion: Tilde expansion. (line 6) -* identifiers, characters valid in: Config files. (line 47) -* include fontmap directive: Fontmap. (line 36) -* INDEXSTYLE: Supported file formats. - (line 84) -* input lines, reading: Calling sequence. (line 110) -* interactive query: Path searching options. - (line 151) -* interface, not frozen: Introduction. (line 29) -* introduction: Introduction. (line 6) -* 'kdebug:': Debugging. (line 105) -* kdefault.c: Default expansion. (line 48) -* Knuth, Donald E.: History. (line 6) -* Knuth, Donald E., archive of programs by: unixtex.ftp. (line 20) -* Kpathsea config file, source for path: Path sources. (line 20) -* kpathsea.h: Programming overview. - (line 26) -* kpathsea_cnf_get: Programming with config files. - (line 27) -* KPATHSEA_DEBUG: Calling sequence. (line 28) -* KPATHSEA_DEBUG <1>: Debugging. (line 18) -* kpathsea_find_file: File lookup. (line 38) -* kpathsea_find_file <1>: Calling sequence. (line 62) -* kpathsea_find_glyph: Glyph lookup. (line 26) -* kpathsea_finish: Calling sequence. (line 106) -* kpathsea_init_prog: Fallback font. (line 15) -* kpathsea_init_prog <1>: Calling sequence. (line 53) -* kpathsea_in_name_ok: Calling sequence. (line 101) -* kpathsea_new: Calling sequence. (line 9) -* kpathsea_open_file: Calling sequence. (line 74) -* kpathsea_out_name_ok: Calling sequence. (line 82) -* kpathsea_set_program_name: Calling sequence. (line 14) -* kpathsea_var_value: Programming with config files. - (line 10) -* KPATHSEA_WARNING: Config files. (line 18) -* kpse->debug: Debugging. (line 6) -* kpse->debug <1>: Debugging. (line 18) -* kpse->debug variable: Calling sequence. (line 39) -* kpse->format_info: Calling sequence. (line 47) -* kpse->invocation_name: Calling sequence. (line 22) -* kpse->invocation_short_name: Calling sequence. (line 22) -* kpse->program_name: Calling sequence. (line 22) -* kpsewhich: Invoking kpsewhich. (line 6) -* Kpsewhich, and debugging: Debugging. (line 31) -* KPSE_BITMAP_TOLERANCE: Basic glyph lookup. (line 15) -* KPSE_DEBUG_EXPAND (16): Debugging. (line 68) -* KPSE_DEBUG_FOPEN (4): Debugging. (line 53) -* KPSE_DEBUG_HASH (2): Debugging. (line 46) -* KPSE_DEBUG_PATHS (8): Debugging. (line 60) -* KPSE_DEBUG_SEARCH (32): Debugging. (line 74) -* KPSE_DEBUG_STAT (1): Debugging. (line 38) -* KPSE_DEBUG_VARS (64): Debugging. (line 83) -* KPSE_DOT expansion: KPSE_DOT expansion. (line 6) -* kpse_format_info_type: Debugging. (line 61) -* last-resort font: Fallback font. (line 6) -* lcircle10: Fontmap. (line 19) -* leading colons: Default expansion. (line 6) -* leaf directories wrongly guessed: Unable to find files. - (line 21) -* leaf directory trick: Subdirectory expansion. - (line 22) -* license for using the library: Introduction. (line 32) -* LIGFONTS: Supported file formats. - (line 88) -* lines, reading arbitrary-length: Calling sequence. (line 110) -* Linux File System Standard: mktex configuration. (line 113) -* local cache of fonts: Security. (line 22) -* log file: Logging. (line 6) -* logging successful searches: Logging. (line 6) -* lost+found directory: Searching overview. (line 63) -* lostchar: Suppressing warnings. - (line 19) -* ls-R: Supported file formats. - (line 91) -* ls-R database file: ls-R. (line 6) -* ls-R, simplest build: ls-R. (line 22) -* Mac filesystem, case-insensitive: Casefolding rationale. - (line 6) -* MacKenzie, David: History. (line 44) -* MacKenzie, David <1>: Subdirectory expansion. - (line 22) -* magic characters: Searching overview. (line 13) -* mailing lists: Mailing lists. (line 6) -* MAKETEX_DEBUG (512): Debugging. (line 91) -* MAKETEX_FINE_DEBUG (1024): Debugging. (line 100) -* memory allocation routines: Calling sequence. (line 110) -* metafont driver files: mktex configuration. (line 93) -* Metafont failures: TeX or Metafont failing. - (line 6) -* Metafont installation: Unable to generate fonts. - (line 51) -* Metafont making too-large fonts: Unable to generate fonts. - (line 36) -* Metafont using the wrong device: Unable to generate fonts. - (line 29) -* MFBASES: Supported file formats. - (line 26) -* MFINPUTS: Supported file formats. - (line 105) -* MFPOOL: Supported file formats. - (line 109) -* MFTINPUTS: Supported file formats. - (line 113) -* MISCFONTS: Supported file formats. - (line 117) -* mismatched checksum warnings: Suppressing warnings. - (line 17) -* missfont.log: mktex script names. (line 35) -* MISSFONT_LOG: mktex script names. (line 40) -* missing character warnings: Suppressing warnings. - (line 20) -* mkocp: mktex script names. (line 18) -* mkofm: mktex script names. (line 21) -* 'mktex' script configuration: mktex configuration. (line 6) -* 'mktex' script names: mktex script names. (line 6) -* 'mktex' scripts: mktex scripts. (line 6) -* mktex.cnf: Specially-recognized files. - (line 28) -* mktex.cnf <1>: mktex configuration. (line 29) -* mktex.opt: mktex configuration. (line 29) -* mktex.opt <1>: mktex configuration. (line 39) -* mktexdir: mktex configuration. (line 61) -* mktexfmt: mktex script names. (line 10) -* mktexmf: mktex script names. (line 15) -* mktexpk: mktex script names. (line 24) -* 'mktexpk' can't guess mode: Unable to generate fonts. - (line 12) -* mktextex: mktex script names. (line 27) -* mktextfm: mktex script names. (line 30) -* MLBIBINPUTS: Supported file formats. - (line 121) -* MLBSTINPUTS: Supported file formats. - (line 125) -* mode directory, omitting: mktex configuration. (line 98) -* Morgan, Tim: History. (line 12) -* MPINPUTS: Supported file formats. - (line 129) -* MPMEMS: Supported file formats. - (line 97) -* MPPOOL: Supported file formats. - (line 133) -* MPSUPPORT: Supported file formats. - (line 101) -* MT_FEATURES: mktex configuration. (line 39) -* multiple TeX hierarchies: Brace expansion. (line 20) -* must exist: Searching overview. (line 31) -* names for 'mktex' scripts: mktex script names. (line 6) -* Neumann, Gustaf: History. (line 56) -* NFS and 'ls-R': ls-R. (line 46) -* nomfdrivers: mktex configuration. (line 92) -* nomode: mktex configuration. (line 97) -* none: Suppressing warnings. - (line 23) -* null pointers, dereferencing: Bug checklist. (line 58) -* numeric debugging values: Debugging. (line 34) -* obtaining TeX: unixtex.ftp. (line 6) -* OCPINPUTS: Supported file formats. - (line 137) -* OFMFONTS: Supported file formats. - (line 141) -* online Metafont display, spurious: Unable to generate fonts. - (line 36) -* OPENTYPEFONTS: Supported file formats. - (line 145) -* optimization caveat: TeX or Metafont failing. - (line 12) -* options for debugging: Debugging. (line 6) -* OTPINPUTS: Supported file formats. - (line 151) -* overview of path searching: Searching overview. (line 6) -* overview of programming with Kpathsea: Programming overview. - (line 6) -* OVFFONTS: Supported file formats. - (line 154) -* OVPFONTS: Supported file formats. - (line 157) -* path expansion: Path expansion. (line 6) -* path searching: Path searching. (line 6) -* path searching options: Path searching options. - (line 6) -* path searching, overview: Searching overview. (line 6) -* path searching, standalone: Invoking kpsewhich. (line 6) -* path sources: Path sources. (line 6) -* pathsearch.h: Programming overview. - (line 26) -* pc Pascal compiler: History. (line 12) -* pdfglyphlist.txt: Specially-recognized files. - (line 31) -* pdftex.cfg: Specially-recognized files. - (line 34) -* PDFTEXCONFIG: Supported file formats. - (line 161) -* pdftexconfig.tex: Specially-recognized files. - (line 34) -* permission denied: Searching overview. (line 63) -* permissions, directory: Security. (line 51) -* permissions, file: Security. (line 47) -* PKFONTS: Supported file formats. - (line 164) -* plain.base: Unable to generate fonts. - (line 46) -* privacy, semblance of: Logging. (line 32) -* problems, common: Common problems. (line 6) -* proginit.h: Calling sequence. (line 53) -* program-varying paths: Supported file formats. - (line 12) -* programming overview: Programming overview. - (line 6) -* programming with config files: Programming with config files. - (line 6) -* programming with Kpathsea: Calling sequence. (line 6) -* programs using the library: Introduction. (line 13) -* proof mode: Unable to generate fonts. - (line 36) -* PSHEADERS: Supported file formats. - (line 169) -* pxp Pascal preprocessor: History. (line 12) -* quoting variable values: Variable expansion. (line 17) -* rationale for casefolding fallback: Casefolding rationale. - (line 6) -* re-entrant API: Programming overview. - (line 16) -* readable: Suppressing warnings. - (line 26) -* reading arbitrary-length lines: Calling sequence. (line 110) -* recording successful searches: Logging. (line 6) -* relative filenames: Searching overview. (line 58) -* reporting bugs: Reporting bugs. (line 6) -* resident.c: Calling sequence. (line 47) -* resolution, setting: Path searching options. - (line 49) -* resolutions, last-resort: Fallback font. (line 6) -* retrieving TeX: unixtex.ftp. (line 6) -* right-hand side of variable assignments: Config files. (line 57) -* RISINPUTS: Supported file formats. - (line 173) -* Rokicki, Tom: History. (line 12) -* root user: Tilde expansion. (line 19) -* runtime configuration files: Config files. (line 6) -* runtime debugging: Debugging. (line 6) -* Sauter fonts, and dynamic source creation: mktex scripts. (line 6) -* scripts for file creation: mktex scripts. (line 6) -* search path, defined: Searching overview. (line 6) -* search, case-insensitive: Casefolding search. (line 6) -* searching for files: File lookup. (line 6) -* searching for glyphs: Glyph lookup. (line 6) -* searching overview: Searching overview. (line 6) -* searching the database: Searching overview. (line 17) -* searching the disk: Searching overview. (line 22) -* security considerations: Security. (line 6) -* SELFAUTODIR: Calling sequence. (line 31) -* SELFAUTOLOC: Calling sequence. (line 31) -* SELFAUTOPARENT: Calling sequence. (line 31) -* sending patches: Bug checklist. (line 52) -* setgid scripts: Security. (line 40) -* SFDFONTS: Supported file formats. - (line 177) -* shell scripts as configuration files: Config files. (line 86) -* shell variables: Variable expansion. (line 17) -* shell_escape, example for code: Programming with config files. - (line 10) -* site overrides for 'mktex...': mktex configuration. (line 29) -* skeleton TeX directory: TeX directory structure. - (line 6) -* slow startup time: Slow path searching. (line 6) -* source files: Supported file formats. - (line 188) -* sources for search paths: Path sources. (line 6) -* special: Suppressing warnings. - (line 30) -* stack trace: Bug checklist. (line 58) -* standalone path searching: Invoking kpsewhich. (line 6) -* standard error and debugging output: Debugging. (line 27) -* standard options: Standard options. (line 6) -* startup time, excessive: Slow path searching. (line 6) -* string routines: Calling sequence. (line 110) -* strip: mktex configuration. (line 107) -* stripsupplier: mktex configuration. (line 101) -* striptypeface: mktex configuration. (line 104) -* st_nlink: Subdirectory expansion. - (line 26) -* ST_NLINK_TRICK: Subdirectory expansion. - (line 38) -* subdirectory searching: Subdirectory expansion. - (line 6) -* suffixes, filename: File lookup. (line 24) -* suggestions, making: Introduction. (line 29) -* Sun 2: History. (line 12) -* supplier directory, omitting: mktex configuration. (line 102) -* supplier directory, omitting <1>: mktex configuration. (line 108) -* supported file formats: Supported file formats. - (line 6) -* suppressing warnings: Suppressing warnings. - (line 6) -* symbolic links not found: Unable to find files. - (line 21) -* symbolic links, and 'ls-R': ls-R. (line 44) -* symlinks, resolving: Calling sequence. (line 31) -* system C compiler bugs: TeX or Metafont failing. - (line 16) -* system-dependent casefolding behavior: Casefolding rationale. - (line 6) -* T1FONTS: Supported file formats. - (line 211) -* T1INPUTS: Supported file formats. - (line 211) -* T42FONTS: Supported file formats. - (line 216) -* tcfmgr.map: Specially-recognized files. - (line 46) -* TDS: TeX directory structure. - (line 6) -* TeX directory structure: TeX directory structure. - (line 6) -* TeX environment variables: Supported file formats. - (line 6) -* TeX failures: TeX or Metafont failing. - (line 6) -* TeX file lookup: File lookup. (line 6) -* TeX glyph lookup: Glyph lookup. (line 6) -* TeX support: TeX support. (line 6) -* TeX Users Group: Introduction. (line 43) -* tex-file.c: File lookup. (line 38) -* tex-file.h: Programming overview. - (line 26) -* tex-glyph.c: Glyph lookup. (line 26) -* tex-glyph.h: Programming overview. - (line 26) -* tex-k@tug.org: Mailing lists. (line 6) -* tex-k@tug.org (bug address): Reporting bugs. (line 6) -* tex.web: unixtex.ftp. (line 20) -* TEXBIB: Supported file formats. - (line 30) -* TEXBIB <1>: Supported file formats. - (line 121) -* TEXCONFIG: Supported file formats. - (line 57) -* TEXDOCS: Supported file formats. - (line 185) -* TEXFONTMAPS: Supported file formats. - (line 94) -* TEXFONTS: Supported file formats. - (line 75) -* TEXFONTS <1>: Supported file formats. - (line 164) -* TEXFONTS <2>: Supported file formats. - (line 199) -* TEXFONTS <3>: Supported file formats. - (line 219) -* texfonts.map: Fontmap. (line 6) -* TEXFORMATS: Supported file formats. - (line 64) -* TEXINDEXSTYLE: Supported file formats. - (line 84) -* TEXINPUTS: Supported file formats. - (line 79) -* TEXINPUTS <1>: Supported file formats. - (line 180) -* TEXMF: TeX directory structure. - (line 6) -* texmf.cnf: Specially-recognized files. - (line 38) -* 'texmf.cnf' missing, warning about: Config files. (line 18) -* texmf.cnf, and variable expansion: Variable expansion. (line 6) -* texmf.cnf, definition for: Config files. (line 6) -* texmf.cnf, source for path: Path sources. (line 20) -* TEXMFCNF: Config files. (line 6) -* TEXMFCNF <1>: Supported file formats. - (line 49) -* TEXMFDBS: ls-R. (line 11) -* TEXMFDBS <1>: Supported file formats. - (line 91) -* TEXMFINI: Supported file formats. - (line 26) -* TEXMFINI <1>: Supported file formats. - (line 64) -* TEXMFINI <2>: Supported file formats. - (line 97) -* TEXMFLOG: Logging. (line 10) -* TEXMFOUTPUT: mktex script names. (line 40) -* TEXMFSCRIPTS: Supported file formats. - (line 191) -* texmfvar: mktex configuration. (line 122) -* TEXMFVAR: mktex configuration. (line 123) -* texmf_casefold_search: Casefolding search. (line 12) -* TEXPICTS: Supported file formats. - (line 79) -* TEXPKS: Supported file formats. - (line 164) -* TEXPOOL: Supported file formats. - (line 195) -* TEXPSHEADERS: Supported file formats. - (line 169) -* TEXPSHEADERS <1>: Supported file formats. - (line 211) -* TEXSIZES: Fallback font. (line 6) -* TEXSOURCES: Supported file formats. - (line 188) -* TEX_HUSH: Searching overview. (line 63) -* TEX_HUSH <1>: Suppressing warnings. - (line 6) -* TFMFONTS: Supported file formats. - (line 199) -* tilde expansion: Tilde expansion. (line 6) -* tilde.c: Tilde expansion. (line 25) -* time system call: Logging. (line 15) -* tolerance for glyph lookup: Basic glyph lookup. (line 15) -* trailing '/' in home directory: Tilde expansion. (line 19) -* trailing colons: Default expansion. (line 6) -* translations, of path searching description: Path searching. - (line 10) -* TRFONTS: Supported file formats. - (line 203) -* trick for detecting leaf directories: Subdirectory expansion. - (line 22) -* trojan horse attack: Security. (line 10) -* try_std_extension_first: File lookup. (line 24) -* TTFONTS: Supported file formats. - (line 207) -* tug.org: unixtex.ftp. (line 6) -* typeface directory, omitting: mktex configuration. (line 105) -* typeface directory, omitting <1>: mktex configuration. (line 108) -* unable to find files: Unable to find files. - (line 6) -* unable to generate fonts: Unable to generate fonts. - (line 6) -* uname: Bug checklist. (line 20) -* unixtex.ftp: unixtex.ftp. (line 6) -* unknown special warnings: Suppressing warnings. - (line 31) -* unreadable file warnings: Suppressing warnings. - (line 27) -* unreadable files: Searching overview. (line 63) -* unusable 'ls-R' warning: ls-R. (line 51) -* usage patterns, finding: Logging. (line 6) -* USERPROFILE, as ~ expansion: Tilde expansion. (line 6) -* USE_TEXMFVAR: mktex configuration. (line 128) -* USE_VARTEXFONTS: mktex configuration. (line 118) -* varfonts: mktex configuration. (line 112) -* variable expansion: Variable expansion. (line 6) -* variable.c: Variable expansion. (line 32) -* variable.h: Programming with config files. - (line 10) -* VARTEXFONTS: mktex configuration. (line 113) -* VAX 11/750: History. (line 12) -* version numbers, determining: Bug checklist. (line 15) -* VF files, not found: Searching overview. (line 31) -* VFFONTS: Supported file formats. - (line 219) -* Vojta, Paul: History. (line 30) -* Walsh, Norman: History. (line 56) -* warning about unusable 'ls-R': ls-R. (line 51) -* warning, about missing 'texmf.cnf': Config files. (line 18) -* warnings, file access: Searching overview. (line 63) -* warnings, suppressing: Suppressing warnings. - (line 6) -* WEB2C: Supported file formats. - (line 227) -* Weber, Olaf: History. (line 73) -* WEBINPUTS: Supported file formats. - (line 223) -* whitespace, in fontmap files: Fontmap. (line 31) -* whitespace, not ignored on continuation lines: Config files. - (line 37) -* Windows and casefolding: Casefolding rationale. - (line 21) -* www.tug.org: unixtex.ftp. (line 6) -* XDvi: Specially-recognized files. - (line 41) -* XDVIFONTS: Supported file formats. - (line 254) -* XDVIMAKEPK: mktex script names. (line 32) -* XDVISIZES: Fallback font. (line 6) -* zuhn, david: History. (line 50) - - - -Tag Table: -Node: Top1480 -Node: Introduction2263 -Node: History4333 -Node: unixtex.ftp8929 -Node: Security10399 -Node: TeX directory structure12903 -Node: Path searching16944 -Node: Searching overview17902 -Node: Path sources21721 -Node: Config files22947 -Node: Path expansion28210 -Node: Default expansion29163 -Node: Variable expansion31233 -Node: Tilde expansion32634 -Node: Brace expansion33614 -Node: KPSE_DOT expansion34553 -Node: Subdirectory expansion35066 -Node: Casefolding search37414 -Node: Casefolding rationale38183 -Node: Casefolding examples39529 -Node: Filename database44575 -Node: ls-R45557 -Node: Filename aliases49233 -Node: Database format50411 -Node: Invoking kpsewhich51424 -Node: Path searching options52379 -Node: Specially-recognized files61977 -Node: Auxiliary tasks63332 -Node: Standard options67057 -Node: TeX support67413 -Node: Supported file formats68767 -Node: File lookup76435 -Node: Glyph lookup78184 -Node: Basic glyph lookup79308 -Node: Fontmap80188 -Node: Fallback font82717 -Node: Suppressing warnings83629 -Node: mktex scripts84756 -Node: mktex configuration85971 -Node: mktex script names91774 -Node: mktex script arguments93160 -Node: Programming94039 -Node: Programming overview94612 -Node: Calling sequence97473 -Node: Program-specific files104002 -Node: Programming with config files105025 -Node: Reporting bugs106612 -Node: Bug checklist107290 -Node: Mailing lists110759 -Node: Debugging111436 -Node: Logging116513 -Node: Common problems118380 -Node: Unable to find files118857 -Node: Slow path searching121267 -Node: Unable to generate fonts122642 -Node: TeX or Metafont failing125114 -Node: Index126316 - -End Tag Table diff --git a/Build/source/texk/kpathsea/doc/kpathsea.texi b/Build/source/texk/kpathsea/doc/kpathsea.texi deleted file mode 100644 index 00ff64eefbe..00000000000 --- a/Build/source/texk/kpathsea/doc/kpathsea.texi +++ /dev/null @@ -1,3931 +0,0 @@ -\input texinfo -@setfilename kpathsea.info -@settitle Kpathsea: A library for path searching - -@set version 6.3.3 -@set month-year February 2021 - -@copying -This file documents the Kpathsea library for path searching. - -Copyright @copyright{} 1996--2021 Karl Berry & Olaf Weber. - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries a copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). -@end ignore - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -approved by the @TeX{} Users Group. -@end copying - -@c Define new indices for commands, filenames, and options. -@defcodeindex cm -@defcodeindex fl -@defcodeindex op - -@c Put everything in one index (arbitrarily chosen to be the concept index). -@syncodeindex cm cp -@syncodeindex fl cp -@syncodeindex fn cp -@syncodeindex ky cp -@syncodeindex op cp -@syncodeindex pg cp -@syncodeindex tp cp -@syncodeindex vr cp - -@dircategory TeX -@direntry -* Kpathsea: (kpathsea). File lookup along search paths. -* kpsewhich: (kpathsea)Invoking kpsewhich. TeX file searching. -* mktexfmt: (kpathsea)mktex scripts. Format (fmt/base/mem) generation. -* mktexlsr: (kpathsea)Filename database. Update ls-R. -* mktexmf: (kpathsea)mktex scripts. MF source generation. -* mktexpk: (kpathsea)mktex scripts. PK bitmap generation. -* mktextex: (kpathsea)mktex scripts. TeX source generation. -* mktextfm: (kpathsea)mktex scripts. TeX font metric generation. -@end direntry - - -@titlepage -@title Kpathsea library -@subtitle for version @value{version} -@subtitle @value{month-year} -@author Karl Berry -@author Olaf Weber -@author Taco Hoekwater -@author @url{https://tug.org/kpathsea} - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - - -@contents - - -@ifnottex -@node Top -@top Kpathsea library - -This manual documents the Kpathsea library for path searching. It -corresponds to version @value{version}, released in -@value{month-year}. - -@menu -* Introduction:: Overview and history. - -* unixtex.ftp:: Obtaining @TeX{} software. -* Security:: Who can write what files, etc. -* TeX directory structure:: Managing the horde of @TeX{} input files. - -* Path searching:: How filename lookups work. -* TeX support:: Special support for TeX-related file lookups. - -* Programming:: How to use Kpathsea features in your program. - -* Reporting bugs:: Where and how to report bugs. -* Index:: General index. -@end menu -@end ifnottex - - -@node Introduction -@chapter Introduction - -@cindex introduction -@cindex fundamental purpose of Kpathsea - -This manual corresponds to version @value{version} of the Kpathsea -library, released in @value{month-year}. - -The library's fundamental purpose is to return a filename from a list of -directories specified by the user, similar to what shells do when -looking up program names to execute. - -@cindex programs using the library -The following software, all of which is maintained in parallel, uses -this library: - -@itemize @bullet -@item Dviljk (see the @samp{dvilj} man page) -@item Dvipsk (@pxref{,,,dvips, Dvips: A DVI driver}) -@item GNU font utilities (@pxref{,,,fontu, GNU font utilities}) -@item Web2c (@pxref{,,,web2c, Web2c: A @TeX{} implementation}) -@item Xdvik (see the @samp{xdvi} man page) -@end itemize - -@noindent Other software that we do not maintain also uses it. - -Kpathsea is now maintained as part of the @TeX{} Live distribution -(@url{https://tug.org/texlive}), which includes several more -Kpathsea-using programs. For information on configuration, building, -installing, and more, @pxref{,,,tlbuild, Building @TeX{} Live}. - -@cindex interface, not frozen -@cindex comments, making -@cindex suggestions, making -The library is still actively maintained. If you have comments or -suggestions, please send along (@pxref{Reporting bugs}). - -@cindex conditions for use -@cindex license for using the library -@cindex GNU General Public License -The Kpathsea library is distributed under the GNU Library General -Public License (LGPL), version@tie{}2.1 or (at your option) any later -version. In short, this means if you write a program using the -library, you must (offer to) distribute the source to the library, -along with any changes you have made, and allow anyone to modify the -library source and distribute their modifications. It does not mean -you have to distribute the source to your program using the library, -although we hope you will. See accompanying files for the text of the -GNU licenses, or @url{https://gnu.org/licenses}. - -@cindex @TeX{} Users Group -If you know enough about @TeX{} to be reading this manual, then you (or -your institution) should consider joining the @TeX{} Users Group (if -you're already a member, thanks!). TUG produces the periodical -@cite{TUGboat}, sponsors an annual meeting and publishes the -proceedings, and arranges courses on @TeX{} for all levels of users -throughout the world. See @url{https://tug.org} for information. - -@menu -* History:: -@end menu - - -@node History -@section History - -@cindex history of Kpathsea - -@cindex Knuth, Donald E. -This section is for those people who are curious about how the library -came about. If you like to read historical accounts of software, we -urge you to seek out the GNU Autoconf manual and the ``Errors of -@TeX{}'' paper by Don Knuth, published in his book @cite{Digital -Typography}, among other places. - -@cindex Morgan, Tim -@cindex Rokicki, Tom -@cindex Berry, Karl -@cindex VAX 11/750 -@cindex Sun 2 -@pindex pxp @r{Pascal preprocessor} -@pindex pc @r{Pascal compiler} -[Karl writes.] My first ChangeLog entry for Web2c seems to be -February 1990, but I may have done some work before then. In any -case, Tim Morgan and I were jointly maintaining it for a time. (I -should mention here that Tim had made Web2c into a real distribution -long before I had ever used it or even heard of it, and Tom Rokicki -did the original implementation. When I started, I was using -@code{pxp} and @code{pc} on VAX 11/750's and the hot new Sun 2 -machines.) - -It must have been later in 1990 and 1991 that I started working on -@cite{@TeX{} for the Impatient}. Dvips, Xdvi, Web2c, and the GNU -fontutils (which I was also writing at the time) all used different -environment variables, and, more importantly, had different bugs in -their path searching. This became extremely painful, as I was stressing -everything to the limit working on the book. I also desperately wanted -to implement subdirectory searching, since I couldn't stand putting -everything in one big directory, and also couldn't stand having to -explicitly specify @file{cm}, @file{pandora}, @dots{} in a path. - -@cindex Vojta, Paul -In the first incarnation, I just hacked separately on each -program---that was the original subdirectory searching code in both -Xdvi and Dvips. That is, I tried to go with the flow in each program, -rather than changing the program's calling sequences to conform to new -routines. - -Then, as bugs inevitably appeared, I found I was fixing the same thing -three times (Web2c and fontutils were already sharing code, since I -maintained both of those---there was no Dvipsk or Xdvik or Dviljk at -this point). After a while, I finally started sharing source files. -They weren't yet a library, though. I just kept things up to date -with shell scripts. (I was developing on a 386 running ISC 2.2 at the -time, and so didn't have symbolic links. An awful experience.) - -@cindex MacKenzie, David -The ChangeLogs for Xdvik and Dvipsk record initial releases of those -distributions in May and June 1992. I think it was because I was tired -of the different configuration strategies of each program, not so much -because of the path searching. Autoconf was being developed by David -MacKenzie and others, and I was adapting it to @TeX{} and friends. - -@cindex zuhn, david -I started to make a separate library that other programs could link with -on my birthday in April 1993, according to the ChangeLog. I don't -remember exactly why I finally took the time to make it a separate -library; a conversation with david zuhn initiated it. Just seemed -like it was time. - -@cindex Walsh, Norman -@cindex Neumann, Gustaf -Dviljk got started in March 1994 after I bought a Laserjet 4. (Kpathsea -work got suspended while Norm Walsh and I, with Gustaf Neumann's help, -implemented a way for @TeX{} to get at all those neat builtin LJ4 fonts -@dots{} such a treat to have something to typeset in besides Palatino!) - -By spring of 1995, I had implemented just about all the path-searching -features in Kpathsea that I plan to, driven beyond my initial goals by -Thomas Esser and others. I then started to integrate Web2c with -Kpathsea. After the release of a stable Web2c, I hope to be able to stop -development, and turn most of my attention back to making fonts for GNU. -(Always assuming Micros**t hasn't completely obliterated Unix by then, -or that software patents haven't stopped software development by anybody -smaller than a company with a million-dollar-a-year legal budget. Which -is actually what I think is likely to happen, but that's another -story@dots{}) - -@cindex Weber, Olaf -[Olaf writes.] At the end of 1997, Unix is still alive and kicking, -individuals still develop software, and Web2c development still -continues. Karl had been looking for some time for someone to take up -part of the burden, and I volunteered. - -@cindex Hoekwater, Taco -@cindex Breitenlohner, Peter -[Karl writes again.] Indeed, time goes on. As of 2006 or so, Olaf's -available time for Kpathsea was reduced, and I started taking overall -care of it again, although I did not do any significant new -development. In 2009, Taco Hoekwater implemented a major -rearrangement to make the library suitable for use within the MetaPost -library (@pxref{Programming overview}). Also, for some years now, -Peter Breitenlohner has made many improvements to the infrastructure -and kept it up-to-date with respect to the overall @TeX{} Live build, -where Kpathsea is now maintained. - - -@c emacs-page separate file so we can easily generate unixtex.ftp. -@include unixtex.texi - - -@node Security -@chapter Security - -@cindex security considerations - -None of the programs in the @TeX{} system require any special system -privileges, so there's no first-level security concern of people gaining -illegitimate root access. - -@cindex trojan horse attack -@flindex .rhosts@r{, writable by @TeX{}} -A @TeX{} document, however, can write to arbitrary files, e.g., -@file{~/.rhosts}, and thus an unwitting user who runs @TeX{} on a random -document is vulnerable to a trojan horse attack. This loophole is -closed by default, but you can be permissive if you so desire in -@file{texmf.cnf}. @xref{tex invocation,,, web2c, Web2c}. MetaPost has -the same issue. - -Dvips, Xdvi, and @TeX{} can also execute shell commands under some -circumstances. To disable this, see the @samp{-R} option in @ref{Option -details,,, dvips, Dvips}, the xdvi man page, and @ref{tex -invocation,,, web2c, Web2c}, respectively. - -@cindex local cache of fonts -@cindex cache of fonts, local -Another security issue arises because it's very useful---almost -necessary---to make arbitrary fonts on user demand with @code{mktexpk} -and friends. Where do these files get installed? By default, the -@code{mktexpk} distributed with Kpathsea assumes a world-writable -@file{/var/tmp} directory; this is a simple and convenient approach, but -it may not suit your situation because it means that a local cache of -fonts is created on every machine. - -@cindex globally writable directories -To avoid this duplication, many people consider a shared, globally -writable font tree desirable, in spite of the potential security -problems. To do this you should change the value of @code{VARTEXFONTS} -in @file{texmf.cnf} to refer to some globally known directory. -@xref{mktex configuration}. - -@cindex append-only directories and @code{mktexpk} -The first restriction you can apply is to make newly-created directories -under @file{texmf} be append-only with an option in @file{mktex.cnf}. -@xref{mktex configuration}. - -@cindex group-writable directories -@cindex setgid scripts -Another approach is to establish a group (or user) for @TeX{} files, -make the @file{texmf} tree writable only to that group (or user), and -make @code{mktexpk} et al.@: setgid to that group (or setuid to that -user). Then users must invoke the scripts to install things. (If -you're worried about the inevitable security holes in scripts, then you -could write a C wrapper to exec the script.) - -@cindex file permissions -@cindex permissions, file -The @file{mktex@dots{}} scripts install files with the same read and -write permissions as the directory they are installed in. The -executable, sgid, suid, and sticky bits are always cleared. - -@cindex directory permissions -@cindex permissions, directory -Any directories created by the @file{mktex@dots{}} scripts have the -same permissions as their parent directory, unless the -@code{appendonlydir} feature is used, in which case the sticky bit is -always set. - - -@node TeX directory structure -@chapter @TeX{} directory structure - -@vindex TEXMF -@cindex @TeX{} directory structure -@cindex directory structure, for @TeX{} files -@cindex skeleton @TeX{} directory -@cindex TDS - -This section describes the default installation hierarchy of the -distribution. It conforms to both the GNU coding standards and the -@TeX{} directory structure (TDS) standard. For rationale and further -explanation, please see those documents. The GNU document is -available from @url{https://gnu.org/prep/standards}. The TDS -document is available from @url{http://mirror.ctan.org/tds} -(@pxref{unixtex.ftp}). - -In short, here is a skeleton of the default directory structure, -extracted from the TDS document: - -@example -@var{prefix}/ @r{installation root (@file{/usr/local} by default)} - bin/ @r{executables} - man/ @r{man pages} - include/ @r{C header files} - info/ @r{GNU info files} - lib/ @r{libraries (@file{libkpathsea.*})} - share/ @r{architecture-independent files} - texmf/ @r{TDS root} - bibtex/ @r{Bib@TeX{} input files} - bib/ @r{Bib@TeX{} databases} - base/ @r{base distribution (e.g., @samp{xampl.bib})} - misc/ @r{single-file databases} - @var{pkg}/ @r{name of a package} - bst/ @r{Bib@TeX{} style files} - base/ @r{base distribution (e.g., @samp{plain.bst}, @samp{acm.bst})} - misc/ @r{single-file styles} - @var{pkg}/ @r{name of a package} - doc/ @r{additional documentation} - dvips/ @r{@samp{.pro}, @samp{.ps}, @samp{psfonts.map}} - fonts/ @r{font-related files} - @var{type}/ @r{file type (e.g., @samp{tfm}, @samp{pk})} - @var{mode}/ @r{type of output device (types @samp{pk} and @samp{gf} only)} - @var{supplier}/ @r{name of a font supplier (e.g., @samp{public})} - @var{typeface}/ @r{name of a typeface (e.g., @samp{cm})} - dpi@var{nnn}/ @r{font resolution (types @samp{pk} and @samp{gf} only)} - metafont/ @r{Metafont (non-font) input files} - base/ @r{base distribution (e.g., @samp{plain.mf})} - misc/ @r{single-file packages (e.g., @samp{modes.mf})} - @var{pkg}/ @r{name of a package (e.g., @samp{mfpic})} - metapost/ @r{MetaPost input files} - base/ @r{base distribution (e.g., @samp{plain.mp})} - misc/ @r{single-file packages} - @var{pkg}/ @r{name of a package} - support/ @r{support files for MetaPost-related utilities (e.g., @samp{trfonts.map})} - mft/ @r{@samp{MFT} inputs (e.g., @samp{plain.mft})} - tex/ @r{@TeX{} input files} - @var{format}/ @r{name of a format (e.g., @samp{plain})} - base/ @r{base distribution for @var{format} (e.g., @samp{plain.tex})} - misc/ @r{single-file packages (e.g., @samp{webmac.tex})} - local/ @r{local additions to or local configuration files for @var{format}} - @var{pkg}/ @r{name of a package (e.g., @samp{graphics}, @samp{mfnfss})} - generic/ @r{format-independent packages} - hyphen/ @r{hyphenation patterns (e.g., @samp{hyphen.tex})} - images/ @r{image input files (e.g., Encapsulated PostScript)} - misc/ @r{single-file format-independent packages (e.g., @samp{null.tex}).} - @var{pkg}/ @r{name of a package (e.g., @samp{babel})} - web2c/ @r{implementation-dependent files (@file{.pool}, @file{.fmt}, @file{texmf.cnf}, etc.)} -@end example - -Some concrete examples for most file types: - -@example -/usr/local/bin/tex -/usr/local/man/man1/xdvi.1 -/usr/local/info/kpathsea.info -/usr/local/lib/libkpathsea.a -/usr/local/share/texmf/bibtex/bst/base/plain.bst -/usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk -/usr/local/share/texmf/fonts/source/public/pandora/pnr10.mf -/usr/local/share/texmf/fonts/tfm/public/cm/cmr10.tfm -/usr/local/share/texmf/fonts/type1/adobe/utopia/putr.pfa -/usr/local/share/texmf/metafont/base/plain.mf -/usr/local/share/texmf/metapost/base/plain.mp -/usr/local/share/texmf/tex/plain/base/plain.tex -/usr/local/share/texmf/tex/generic/hyphen/hyphen.tex -/usr/local/share/texmf/web2c/tex.pool -/usr/local/share/texmf/web2c/tex.fmt -/usr/local/share/texmf/web2c/texmf.cnf -@end example - - -@node Path searching -@chapter Path searching - -@cindex path searching - -This chapter describes the generic path searching mechanism Kpathsea -provides. For information about searching for particular file types -(e.g., @TeX{} fonts), see the next chapter. - -@cindex translations, of path searching description -This section, with minor differences, has been translated into several -other languages (Chinese, Spanish, Russian, Japanese, French, German, -@dots{}) as part of the @TeX{} Live guide; see -@url{https://tug.org/texlive/doc.html} for links. - -@menu -* Searching overview:: Basic scheme for searching. -* Path sources:: Where search paths can be defined. -* Path expansion:: Special constructs in search paths. -* Casefolding search:: Fallback to case-insensitive search. -* Filename database:: Using an externally-built list to search. -* Invoking kpsewhich:: Standalone path lookup. -@end menu - - -@node Searching overview -@section Searching overview - -@cindex searching overview -@cindex path searching, overview -@cindex overview of path searching - -@cindex search path, defined -A @dfn{search path} is a colon-separated list of @dfn{path elements}, -which are directory names with a few extra frills. A search path can -come from (a combination of) many sources; see below. To look up a file -@samp{foo} along a path @samp{.:/dir}, Kpathsea checks each element of -the path in turn: first @file{./foo}, then @file{/dir/foo}, returning -the first match (or possibly all matches). - -@cindex magic characters -@kindex : @r{may not be :} -@kindex / @r{may not be /} -The ``colon'' and ``slash'' mentioned here aren't necessarily @samp{:} -and @samp{/} on non-Unix systems. Kpathsea tries to adapt to other -operating systems' conventions. - -@cindex database search -@cindex searching the database -To check a particular path element @var{e}, Kpathsea first sees if a -prebuilt database (@pxref{Filename database}) applies to @var{e}, i.e., -if the database is in a directory that is a prefix of @var{e}. If so, -the path specification is matched against the contents of the database. - -@cindex floating directories -@cindex filesystem search -@cindex disk search -@cindex searching the disk -If the database does not exist, or does not apply to this path element, -or contains no matches, the filesystem is searched (if this was not -forbidden by the specification with @samp{!!} and if the file being -searched for must exist). Kpathsea constructs the list of directories -that correspond to this path element, and then checks in each for the -file being searched for. (To help speed future lookups of files in the -same directory, the directory in which a file is found is floated to the -top of the directory list.) - -@cindex must exist -@cindex VF files, not found -@flindex cmr10.vf -@findex \openin -The ``file must exist'' condition comes into play with VF files and -input files read by the @TeX{} @samp{\openin} command. These files -might very well not exist (consider @file{cmr10.vf}), and so it would -be wrong to search the disk for them. Therefore, if you fail to -update @file{ls-R} when you install a new VF file, it will not be -found. - -Each path element is checked in turn: first the database, then the -disk. If a match is found, the search stops and the result is -returned (unless the search explicitly requested all matches). This -avoids possibly-expensive processing of path specifications that are -never needed on a particular run. - -On Unix-like systems, if no match is found by any of the above, and -the path element allows checking the filesystem (per the above), a -final check is made for a case-insensitive match. Thus, looking for a -name like @samp{./FooBar.TeX} will match a file @samp{./foobar.tex}, -and vice versa. This is not done on Windows. @xref{Casefolding -search}. - -@cindex expansion, path element -Although the simplest and most common path element is a directory name, -Kpathsea supports additional features in search paths: layered default -values, environment variable names, config file values, users' home -directories, and recursive subdirectory searching. Thus, we say that -Kpathsea @dfn{expands} a path element, meaning transforming all the -magic specifications into the basic directory name or names. This -process is described in the sections below. It happens in the same -order as the sections. - -@cindex absolute filenames -@cindex relative filenames -@cindex explicitly relative filenames -@cindex filenames, absolute or explicitly relative -Exception to all of the above: If the filename being searched for is -absolute or explicitly relative, i.e., starts with @samp{/} or @samp{./} -or @samp{../}, Kpathsea simply checks if that file exists, with a -fallback to a casefolding match if needed and enabled, as described above. - -@cindex permission denied -@cindex unreadable files -@cindex access warnings -@cindex warnings, file access -@flindex lost+found @r{directory} -@vindex TEX_HUSH -Ordinarily, if Kpathsea tries to access a file or directory that -cannot be read, it gives a warning. This is so you will be alerted to -directories or files that accidentally lack any read permission (for -example, a @file{lost+found} directory). If you prefer not to see -these warnings, include the value @samp{readable} in the -@code{TEX_HUSH} environment variable or config file value. - -This generic path searching algorithm is implemented in -@file{kpathsea/pathsearch.c}. It is employed by a higher-level -algorithm when searching for a file of a particular type (@pxref{File -lookup}, and @ref{Glyph lookup}). - - -@node Path sources -@section Path sources - -@cindex path sources -@cindex sources for search paths - -A search path or other configuration value can come from many sources. -In the order in which Kpathsea looks for them: - -@enumerate -@item -@opindex @samp{--cnf-line}, source for path -A command-line option such as @code{--cnf-line}, available in -@file{kpsewhich} and most @TeX{} engines. @xref{Path searching -options}. - -@cindex environment variable, source for path -A user-set environment variable, e.g., @code{TEXINPUTS}. -Environment variables with an underscore and the program name appended -override; for example, @code{TEXINPUTS_latex} overrides @code{TEXINPUTS} -if the program being run is named @samp{latex}. - -@item -A program-specific configuration file, e.g., an @samp{S /a:/b} line in -Dvips' @file{config.ps} (@pxref{Config files,,, dvips, Dvips}). - -@item -@cindex configuration file, source for path -@cindex Kpathsea config file, source for path -@flindex texmf.cnf@r{, source for path} -A line in a Kpathsea configuration file @file{texmf.cnf}, e.g., -@samp{TEXINPUTS=/c:/d} (see below). - -@item -@cindex compilation value, source for path -The compile-time default (specified in @file{kpathsea/paths.h}). -@end enumerate - -You can see each of these values for a given search path by using the -debugging options (@pxref{Debugging}). - -These sources may be combined via default expansion (@pxref{Default -expansion}). - -@menu -* Config files:: Kpathsea's runtime config files (texmf.cnf). -@end menu - - -@node Config files -@subsection Config files - -@cindex config files -@flindex texmf.cnf@r{, definition for} - -@cindex runtime configuration files -@vindex TEXMFCNF -As mentioned above, Kpathsea reads @dfn{runtime configuration files} -named @file{texmf.cnf} for search path and other definitions. The -search path used to look for these configuration files is named -@code{TEXMFCNF}, and is constructed in the usual way, as described -above, except that configuration files cannot be used to define the -path, naturally; also, an @file{ls-R} database is not used to search for -them. - -Kpathsea reads @emph{all} @file{texmf.cnf} files in the search path, not -just the first one found; definitions in earlier files override those in -later files. Thus, if the search path is @samp{.:$TEXMF}, values from -@file{./texmf.cnf} override those from @file{$TEXMF/texmf.cnf}. - -@vindex KPATHSEA_WARNING -@cindex warning, about missing @file{texmf.cnf} -@cindex @file{texmf.cnf} missing, warning about -If Kpathsea cannot find any @file{texmf.cnf} file, it reports a -warning including all the directories it checked. If you don't want -to see this warning, set the environment variable -@env{KPATHSEA_WARNING} to the single character @samp{0} (zero, not -oh). - -While (or instead of) reading this description, you may find it helpful -to look at the distributed @file{texmf.cnf}, which uses or at least -mentions most features. The format of @file{texmf.cnf} files follows: - -@itemize @bullet -@item -@cindex comments, in @file{texmf.cnf} -Comments start with @samp{%}, either at the beginning of a line or -preceded by whitespace, and continue to the end of the line. That is, -similar to most shells, a @samp{%} in the ``middle'' of a value does not -start a comment. Examples: - -@example -% this is a comment -var = a%b % but the value of var will be "a%b" -@end example - -@item -@cindex blank lines, in @file{texmf.cnf} -Blank lines are ignored. - -@item -@cindex backslash-newline -@cindex continuation character -@cindex whitespace, not ignored on continuation lines -@kindex \@r{, line continuation in @file{texmf.cnf}} -A @samp{\} at the end of a line acts as a continuation character, i.e., -the next line is appended. Whitespace at the beginning of continuation -lines is not ignored. - -@item Each remaining line will look like: - -@example -@var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value} -@end example - -@noindent where the @samp{=} and surrounding whitespace is optional. - -@item -@cindex identifiers, characters valid in -The @var{variable} name may contain any character other than whitespace, -@samp{=}, or @samp{.}, but sticking to @samp{A-Za-z_} is safest. - -@kindex .@var{progname} @r{qualifier in @file{texmf.cnf}} -@item If @samp{.@var{progname}} is present (preceding spaces are -ignored), the definition only applies if the program that is running -is named (i.e., the last component of @code{argv[0]} is) -@var{progname} or @file{@var{progname}.@{exe,bat,cmd,...@}}. Most -notably, this allows different flavors of @TeX{} to have different -search paths. The @var{progname} value is used literally, without -variable or other expansions. - -@item -@cindex right-hand side of variable assignments -Considered as strings, @var{value} may contain any character. -However, in practice most @file{texmf.cnf} values are related to path -expansion, and since various special characters are used in expansion, -such as braces and commas, they cannot be used in directory names. - -The @samp{$@var{var}.@var{prog}} feature is not available on the -right-hand side; instead, you must use an additional variable (see -below for example). - -@kindex ; @r{translated to @samp{:} in @file{texmf.cnf}} -A @samp{;} in @var{value} is translated to @samp{:} if running under -Unix, in order to have a single @file{texmf.cnf} that can support both -Unix and Windows systems. This translation happens with any value, not -just search paths, but fortunately in practice @samp{;} is not needed -in other values. - -@item All definitions are read before anything is expanded, so you can -use variables before they are defined (like Make, unlike most other -programs). -@end itemize - -@noindent Here is a configuration file fragment illustrating most of -these points: - -@example -% TeX input files -- i.e., anything to be found by \input or \openin ... -latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex// -latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex// -TEXINPUTS = .:$TEXMF/tex// -TEXINPUTS.latex209 = $latex209_inputs -TEXINPUTS.latex2e = $latex2e_inputs -TEXINPUTS.latex = $latex2e_inputs -@end example - -@cindex shell scripts as configuration files -@cindex configuration files as shell scripts. -This format has some similarity to Bourne shell scripts---change the -comment character to @code{#}, disallow spaces around the @code{=}, -and get rid of the @code{.@var{name}} convention, and it could be run -through the shell. However, there seemed little advantage in this, -since all the information would have to passed back to Kpathsea and -parsed there anyway, since the @code{sh} process couldn't affect its -parent's environment. - -@kindex = @r{omitted in @file{texmf.cnf} and misparsing} -The combination of spaces being ignored before the @code{.} of a -program name qualifer and the optional @samp{=} for the assignment has -an unexpected consequence: if the value begins with a literal @samp{.} -and the @samp{=} is omitted, the intended value is interpreted as a -program name. For example, a line @code{var .;/some/path} is taken as -an empty value for @code{var} running under the program named -@samp{;/some/path}. To diagnose this, Kpathsea warns if the program -name contains a path separator or other special character. The -simplest way to avoid the problem is to use the @code{=}. - -Exactly when a character will be considered special or act as itself -depends on the context in which it is used. The rules are inherent in -the multiple levels of interpretation of the configuration (parsing, -expansion, search, @dots{}) and so cannot be concisely stated, -unfortunately. There is no general escape mechanism; in particular, -@samp{\} is not an ``escape character'' in @file{texmf.cnf} files. -When it comes choosing directory names for installation, it is safest to -avoid them all. - -@flindex cnf.c -The implementation of all this is in @file{kpathsea/cnf.c}. - - -@node Path expansion -@section Path expansion - -@cindex path expansion -@cindex expansion, search path - -Kpathsea recognizes certain special characters and constructions in -search paths, similar to that in shells. As a general example: -@samp{~$USER/@{foo,bar@}//baz} expands to all subdirectories under -directories @file{foo} and @file{bar} in @t{$USER}'s home directory that -contain a directory or file @file{baz}. - -These expansions are explained in the sections below. - -@menu -* Default expansion:: a: or :a or a::b expands to a default. -* Variable expansion:: $foo and $@{foo@} expand to environment values. -* Tilde expansion:: ~ and ~user expand to home directories. -* Brace expansion:: a@{foo,bar@}b expands to afoob abarb. -* KPSE_DOT expansion:: . is replaced with $KPSE_DOT if it is defined. -* Subdirectory expansion:: a// and a//b recursively expand to subdirs. -@end menu - - -@node Default expansion -@subsection Default expansion - -@kindex :: @r{expansion} -@cindex doubled colons -@cindex leading colons -@cindex trailing colons -@cindex extra colons -@cindex default expansion -@cindex expansion, default - -If the highest-priority search path (@pxref{Path sources}) contains an -@dfn{extra colon} (i.e., leading, trailing, or doubled), Kpathsea -inserts at that point the next-highest-priority search path that is -defined. If that inserted path has an extra colon, the same happens -with the next-highest. (An extra colon in the compile-time default -value has unpredictable results, so installers beware.) - -For example, given an environment variable setting - -@example -setenv TEXINPUTS /home/karl: -@end example - -@noindent and a @code{TEXINPUTS} value from @file{texmf.cnf} of - -@example -.:$TEXMF//tex -@end example - -@noindent then the final value used for searching will be: - -@example -/home/karl:.:$TEXMF//tex -@end example - -Put another way, default expansion works on ``formats'' (search -paths), and not directly on environment variables. Example, showing -the trailing @samp{:} ignored in the first case and expanded in the second: - -@example -$ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS' -/tmp -$ env TTFONTS=/tmp: kpsewhich --show-path=.ttf -/tmp:.:/home/olaf/texmf/fonts/truetype//:... -@end example - -Since Kpathsea looks for multiple configuration files, it would be -natural to expect that (for example) an extra colon in -@file{./texmf.cnf} would expand to the path in @file{$TEXMF/texmf.cnf}. -Or, with Dvips' configuration files, that an extra colon in -@file{config.$PRINTER} would expand to the path in @file{config.ps}. -This doesn't happen. It's not clear this would be desirable in all -cases, and trying to devise a way to specify the path to which the extra -colon should expand seemed truly baroque. -@cindex Bach, Johann Sebastian - -Technicality: Since it would be useless to insert the default value in -more than one place, Kpathsea changes only one extra @samp{:} and leaves -any others in place (they will eventually be ignored). Kpathsea checks -first for a leading @samp{:}, then a trailing @samp{:}, then a doubled -@samp{:}. - -@flindex kdefault.c -You can trace this by debugging ``paths'' (@pxref{Debugging}). -Default expansion is implemented in the source file -@file{kpathsea/kdefault.c}. - - -@node Variable expansion -@subsection Variable expansion - -@kindex $ @r{expansion} -@cindex environment variables in paths -@cindex variable expansion -@cindex expansion, variable -@flindex texmf.cnf@r{, and variable expansion} - -@samp{$foo} or @samp{$@{foo@}} in a path element is replaced by (1) the -value of an environment variable @samp{foo} (if defined); (2) the value -of @samp{foo} from @file{texmf.cnf} (if defined); (3) the empty string. - -If the character after the @samp{$} is alphanumeric or @samp{_}, the -variable name consists of all consecutive such characters. If the -character after the @samp{$} is a @samp{@{}, the variable name consists -of everything up to the next @samp{@}} (braces may not be nested around -variable names). Otherwise, Kpathsea gives a warning and ignores the -@samp{$} and its following character. - -@cindex quoting variable values -@cindex shell variables -You must quote the @t{$}'s and braces as necessary for your shell. -@emph{Shell} variable values cannot be seen by Kpathsea, i.e., ones -defined by @code{set} in C shells and without @code{export} in Bourne -shells. - -For example, given -@example -setenv tex /home/texmf -setenv TEXINPUTS .:$tex:$@{tex@}prev -@end example -@noindent the final @code{TEXINPUTS} path is the three directories: -@example -.:/home/texmf:/home/texmfprev -@end example - -The @samp{.@var{progname}} suffix on variables and -@samp{_@var{progname}} on environment variable names are not implemented -for general variable expansions. These are only recognized when search -paths are initialized (@pxref{Path sources}). - -@flindex variable.c -Variable expansion is implemented in the source file -@file{kpathsea/variable.c}. - - -@node Tilde expansion -@subsection Tilde expansion - -@kindex ~ @r{expansion} -@cindex home directories in paths -@cindex tilde expansion -@cindex expansion, tilde - -@vindex HOME@r{, as ~ expansion} -@vindex USERPROFILE@r{, as ~ expansion} -A leading @samp{~} in a path element is replaced by the value of the -environment variable @code{HOME}, or @file{.} if @code{HOME} is not -set. On Windows, the environment variable @code{USERPROFILE} is -checked instead of @code{HOME}. - -A leading @samp{~@var{user}} in a path element is replaced by -@var{user}'s home directory from the system @file{passwd} database. - -For example, -@example -setenv TEXINPUTS ~/mymacros: -@end example - -@noindent will prepend a directory @file{mymacros} in your home -directory to the default path. - -@cindex @t{root} user -@cindex trailing @samp{/} in home directory -@kindex /@r{, trailing in home directory} -As a special case, if a home directory ends in @samp{/}, the trailing -slash is dropped, to avoid inadvertently creating a @samp{//} construct -in the path. For example, if the home directory of the user @samp{root} -is @samp{/}, the path element @samp{~root/mymacros} expands to just -@samp{/mymacros}, not @samp{//mymacros}. - -@flindex tilde.c -Tilde expansion is implemented in the source file @file{kpathsea/tilde.c}. - - -@node Brace expansion -@subsection Brace expansion - -@kindex @{ @r{expansion} -@cindex brace expansion - -@samp{x@{@var{a},@var{b}@}y} expands to @samp{x@var{a}y:x@var{b}y}. -For example: - -@example -foo/@{1,2@}/baz -@end example - -@noindent expands to @samp{foo/1/baz:foo/2/baz}. @samp{:} is the path -separator on the current system; e.g., on a Windows system, it's @samp{;}. - -Braces can be nested; for example, @samp{x@{A,B@{1,2@}@}y} expands to -@samp{xAy:xB1y:xB2y}. - -Multiple non-nested braces are expanded from right to left; for example, -@samp{x@{A,B@}@{1,2@}y} expands to @samp{x@{A,B@}1y:x@{A,B@}2y}, which -expands to @samp{xA1y:xB1y:xA2y:xB2y}. - -@cindex multiple @TeX{} hierarchies -This feature can be used to implement multiple @TeX{} hierarchies, by -assigning a brace list to @code{$TEXMF}, as mentioned in -@file{texmf.in}. - -You can also use the path separator instead of the comma. The last -example could have been written @samp{x@{A:B@}@{1:2@}y} (on Unix). - - -@flindex expand.c -Brace expansion is implemented in the source file -@file{kpathsea/expand.c}. - - -@node KPSE_DOT expansion -@subsection @code{KPSE_DOT} expansion - -@kindex KPSE_DOT @r{expansion} - -When @code{KPSE_DOT} is defined in the environment, it names a directory -that should be considered the current directory for the purpose of -looking up files in the search paths. This feature is needed by the -@samp{mktex@dots{}} scripts @ref{mktex scripts}, because these -change the working directory. You should not ever define it yourself. - - -@node Subdirectory expansion -@subsection Subdirectory expansion - -@kindex // -@cindex subdirectory searching -@cindex expansion, subdirectory - -@cindex alphabetical order, not -Two or more consecutive slashes in a path element following a directory -@var{d} is replaced by all subdirectories of @var{d}: first those -subdirectories directly under @var{d}, then the subsubdirectories under -those, and so on. At each level, the order in which the directories are -searched is unspecified. (It's ``directory order'', and definitely not -alphabetical.) - -If you specify any filename components after the @samp{//}, only -subdirectories which match those components are included. For example, -@samp{/a//b} would expand into directories @file{/a/1/b}, @file{/a/2/b}, -@file{/a/1/1/b}, and so on, but not @file{/a/b/c} or @file{/a/1}. - -You can include multiple @samp{//} constructs in the path. - -@samp{//} at the beginning of a path is ignored; you didn't really want -to search every directory on the system, did you? - -@cindex trick for detecting leaf directories -@cindex leaf directory trick -@cindex Farwell, Matthew -@cindex MacKenzie, David -I should mention one related implementation trick, which I took from GNU -find. Matthew Farwell suggested it, and David MacKenzie implemented it. - -@vindex st_nlink -The trick is that in every real Unix implementation (as opposed to the -POSIX specification), a directory which contains no subdirectories will -have exactly two links (namely, one for @file{.} and one for @file{..}). -That is to say, the @code{st_nlink} field in the @samp{stat} structure -will be two. Thus, we don't have to stat everything in the bottom-level -(leaf) directories---we can just check @code{st_nlink}, notice it's two, -and do no more work. - -But if you have a directory that contains a single subdirectory and 500 -regular files, @code{st_nlink} will be 3, and Kpathsea has to stat every -one of those 501 entries. Therein lies slowness. - -@vindex ST_NLINK_TRICK -You can disable the trick by undefining @code{ST_NLINK_TRICK} in -@file{kpathsea/config.h}. (It is undefined by default except under Unix.) - -@flindex elt-dirs.c -Unfortunately, in some cases files in leaf directories are -@code{stat}'d: if the path specification is, say, -@samp{$TEXMF/fonts//pk//}, then files in a subdirectory -@samp{@dots{}/pk}, even if it is a leaf, are checked. The reason -cannot be explained without reference to the implementation, so read -@file{kpathsea/elt-dirs.c} (search for @samp{may descend}) if you are -curious. And if you find a way to solve the problem, please let me -know. - -@flindex elt-dirs.c -Subdirectory expansion is implemented in the source file -@file{kpathsea/elt-dirs.c}. - - -@node Casefolding search -@section Casefolding search - -@cindex casefolding search -@cindex search, case-insensitive - -In Kpathsea version 6.3.0 (released with @TeX{} Live 2018), a new -fallback search was implemented on Unix-like systems, including Macs: -for each path element in turn, if no match is found by the normal -search, and the path element allows for checking the filesystem, a -second check is made for a case-insensitive match. - -@vindex texmf_casefold_search -This is enabled at compile-time on Unix systems, and enabled at -runtime by setting the configuration variable -@code{texmf_casefold_search}, to a true value, e.g., @samp{1}; this is -done by default in @TeX{} Live. - -@menu -* Rationale: Casefolding rationale. -* Examples: Casefolding examples. -@end menu - -@node Casefolding rationale -@subsection Casefolding rationale - -@cindex casefolding fallback rationale -@cindex rationale for casefolding fallback -@cindex system-dependent casefolding behavior - -@cindex filesystem, case-(in)sensitive -@cindex Apple filesystem, case-insensitive -@cindex Mac filesystem, case-insensitive -The purpose of the fallback casefolding search is to ease moving -complex documents between case-insensitive (file)systems and -case-sensitive ones. In particular, Apple decided to make the default -filesystem on Macs be case-insensitive some years ago, and this has -exacerbated a problem of people creating documents that use, say, an -image under the name @file{foo.jpg}, while the actual file is named -@file{foo.JPG} or @file{Foo.jpg}. It works on the Mac but if the -document is transferred and run on a standard case-sensitive Unix -(file)system, the file can't be found, due only to differences in -case. - -This same problematic scenario has always existed on Windows, but for -whatever reason, it has become much more common since Apple also went -to a case-insensitive filesystem. Hence the relatively late change -to the Kpathsea behavior. - -@cindex Windows and casefolding -The fallback case-insensitive search is omitted at compile-time on -Windows, where (for practical purposes) all file names are -case-insensitive at the kernel level, and so the normal search will -already have definitively matched or not. Therefore, search results -in unusual cases can be different on Windows and Unix---but this has -always been true. - - -@node Casefolding examples -@subsection Casefolding examples - -@cindex casefolding examples -@cindex examples, of casefolding searches - -The casefolding implementation prefers exact matches to casefolded -matches within a given path element, so as to retain most -compatibility. Backward compatibility is not perfect, however, as a -casefolded match may be found in an earlier path element than an exact -match was previously found (see example #4 below). Still, preferring -the match in the earlier element seemed potentially less confusing -than otherwise, and is in fact consistent with past behavior on -Windows. Since case mismatches are rare to begin with, and name -collisions with respect only to case thus even more rare, the hope is -that it will not cause difficulties in practice. - -If it's desirable in a given situation to have the exact same search -behavior as previously, that can be accomplished by setting the -configuration variable @code{texmf_casefold_search} to @samp{0} -(@pxref{Path sources}). - -Some examples to illustrate the new behavior follow. - -Example #1: suppose the file @file{./foobar.tex} exists. Now, -searching for @file{./FooBar.TeX} (or any other case variation) will -succeed, returning @file{./foobar.tex}---the name as stored on disk. -In previous releases, or if @code{texmf_casefold_search} is false, the -search would fail. - -Example #2: suppose we are using a case-sensitive (file)system, and -the search path is @samp{.:/somedir}, and the files -@file{./foobar.tex} and @file{/somedir/FooBar.TeX} both exist. Both -now and previously, searching for @file{foobar.tex} returns -@file{./foobar.tex}. However, searching for @file{FooBar.TeX} now -returns @file{./foobar.tex} instead of @file{/somedir/FooBar.TeX}; -this is the incompatibility mentioned above. Also (as expected), -searching for @file{FOOBAR.TEX} (or whatever variation) will now -return @file{./foobar.tex}, whereas before it would fail. Searching -for all (@samp{kpsewhich --all}) @file{foobar.tex} will return both -matches. - -Example #3: same as example #2, but on a case-insensitive -(file)system: both now and previously, searching for @file{FooBar.TeX} -returns @file{./foobar.tex}, since the system considers that a match. -The Kpathsea casefolding never comes into play. - -Example #4: if we have (on a case-sensitive system) both -@file{./foobar.tex} and @file{./FOOBAR.TEX}, searching with the exact -case returns that exact match, now and previously. Searching for -@file{FooBar.tex} will now return one or the other (chosen -arbitrarily), rather than failing. Perhaps unexpectedly, searching -for all @file{foobar.tex} or @file{FooBar.tex} will also return only -one or the other, not both (see more below). - -Example #5: the font file @file{STIX-Regular.otf} is included in -@TeX{} Live in the system directory -@file{texmf-dist/fonts/opentype/public/stix}. Because Kpathsea never -searches the disk in the big system directory, the casefolding is not -done, and a search for @samp{stix-regular.otf} will fail (on -case-sensitive systems), as it always has. - -@kindex !! @r{and casefolding} -The caveat about not searching the disk amounts to saying that -casefolding does not happen in the trees specified with @samp{!!} -(@pxref{ls-R}), that is, where only database (@file{ls-R}) searching -is done. In @TeX{} Live, that is the @samp{texmf-local} and -@samp{texmf-dist} trees (also @code{$TEXMFSYSCONFIG} and -@code{$TEXMFSYSVAR}, but those are rarely noticed). The rationale for -this is that in practice, case mangling happens with user-created -files, not with packages distributed as part of the @TeX{} system. - -One more caveat: the purpose of @code{kpsewhich} is to exercise the -path searching in Kpathsea as it is actually done. Therefore, as -shown above, @samp{kpsewhich --all} will not return all matches -regardless of case within a given path element. If you want to find -all matches in all directories, @code{find} is the best tool, although -the setup takes a couple steps: - -@example -kpsewhich -show-path=tex >/tmp/texpath # search path specification -kpsewhich -expand-path="`cat /tmp/texpath`" >/tmp/texdirs # all dirs -tr ':' '\n' </tmp/texdirs >/tmp/texdirlist # colons to newlines -find `cat /tmp/texdirlist` -iname somefile.tex -print </tmp/texdirlist -@end example - -@cindex Findutils, GNU package -@opindex -iname@r{, find predicate} -Sorry that it's annoyingly lengthy, but implementing this inside -Kpathsea would be a lot of error-prone trouble for something that is -only useful for debugging. If your @code{find} does not support -@code{-iname}, you can get GNU Find from -@url{https://gnu.org/software/findutils}. - -The casefolding search is implemented in the source file -@file{kpathsea/pathsearch.c}. Two implementation points: - -@itemize -@findex access @r{system call} -@item -Kpathsea never tries to check if a given directory resides on a -case-insensitive filesystem, because there is no efficient and -portable way to do so. All it does is try to see if a potential file -name is a readable normal file (with, usually, the @code{access} -system call). - -@item -Kpathsea does not do any case-insensitive matching of the directories -along the path. It's not going to find @file{/Some/Random/file.tex} -when looking for @file{/some/random/file.tex}. The casefolding only -happens with the elements of the leaf directory. - -@end itemize - - -@node Filename database -@section Filename database (@code{ls-R}) - -@cindex filename database -@cindex database, for filenames -@cindex externally-built filename database - -Kpathsea goes to some lengths to minimize disk accesses for searches -(@pxref{Subdirectory expansion}). Nevertheless, in practice searching -every possible directory in typical @TeX{} installations takes an -excessively long time. - -Therefore, Kpathsea can use an externally-built @dfn{filename -database} file named @file{ls-R} that maps files to directories, thus -avoiding the need to exhaustively search the disk. - -A second database file @file{aliases} allows you to give additional -names to the files listed in @file{ls-R}. - -The @file{ls-R} and @file{aliases} features are implemented in the -source file @file{kpathsea/db.c}. - -@menu -* ls-R:: The main filename database. -* Filename aliases:: Aliases for those names. -* Database format:: Syntax details of the database file. -@end menu - - -@node ls-R -@subsection @file{ls-R} - -@flindex ls-R @r{database file} - -As mentioned above, you must name the main filename database -@file{ls-R}. You can put one at the root of each @TeX{} installation -hierarchy you wish to search (@code{$TEXMF} by default, which expands -to a braced list of several hierarchies in @TeX{} Live). - -@vindex TEXMFDBS -@kindex !! @r{in @code{TEXMFDBS}} -Kpathsea looks for @file{ls-R} files along the @code{TEXMFDBS} -path. It is best for this to contain all and only those hierarchies -from @code{$TEXMF} which are specified with @code{!!}---and also to -specify them with @code{!!} in @code{TEXMFDBS}. (See the end of this -section for more on @code{!!}.) - -The recommended way to create and maintain @samp{ls-R} is to run the -@code{mktexlsr} script, which is installed in @samp{$(bindir)} -(@file{/usr/local/bin} by default). That script goes to some trouble to -follow symbolic links as necessary, etc. It's also invoked by the -distributed @samp{mktex@dots{}} scripts. - -@flindex ls-R@r{, simplest build} -At its simplest, though, you can build @file{ls-R} with the command -@example -cd @var{/your/texmf/root} && ls -LAR ./ >ls-R -@end example - -@noindent -@opindex --color=tty -@flindex /etc/profile @r{and aliases} -presuming your @code{ls} produces the right output format (see the -section below). GNU @code{ls}, for example, outputs in this format. -Also presuming your @code{ls} hasn't been aliased in a system file -(e.g., @file{/etc/profile}) to something problematic, e.g., @samp{ls ---color=tty}. In that case, you will have to disable the alias before -generating @file{ls-R}. For the precise definition of the file format, -see @ref{Database format}. - -Regardless of whether you use the supplied script or your own, you -will almost certainly want to invoke it via @code{cron}, so when you -make changes in the installed files (say if you install a new @LaTeX{} -package), @file{ls-R} will be automatically updated. However, for -those using @TeX{} Live or system distributions, the package managers -should run @code{mktexlsr} as needed. - -@opindex -A @r{option to @code{ls}} -@cindex dot files -@flindex . @r{files} -@flindex . @r{directories, ignored} -@flindex .tex @r{file, included in @file{ls-R}} -The @samp{-A} option to @code{ls} includes files beginning with @samp{.} -(except for @file{.} and @file{..}), such as the file @file{.tex} -included with the @LaTeX{} tools package. (On the other hand, -@emph{directories} whose names begin with @samp{.} are always ignored.) - -@cindex symbolic links, and @file{ls-R} -@opindex -L @r{option to @code{ls}} -If your system does not support symbolic links, omit the @samp{-L}. - -@cindex automounter, and @file{ls-R} -@cindex NFS and @file{ls-R} -@code{ls -LAR @var{/your/texmf/root}} will also work. But using -@samp{./} avoids embedding absolute pathnames, so the hierarchy can be -easily transported. It also avoids possible trouble with automounters -or other network filesystem conventions. - -@cindex warning about unusable @file{ls-R} -@cindex unusable @file{ls-R} warning -Kpathsea warns you if it finds an @file{ls-R} file, but the file does -not contain any usable entries. The usual culprit is running plain -@samp{ls -R} instead of @samp{ls -LR ./} or @samp{ls -R -@var{/your/texmf/root}}. Another possibility is some system directory -name starting with a @samp{.} (perhaps if you are using AFS); Kpathsea -ignores everything under such directories. - -@kindex !! @r{in path specifications} -@cindex disk searching, avoiding -If a particular path element begins with @samp{!!}, @emph{only} the -database will be searched for that element, never the disk; and if the -database does not exist, nothing at all will be searched. In @TeX{} -Live, most of the trees are specified with @samp{!!}. - -For path elements that do not begin with @samp{!!}, if the database -exists, it will be used, and the disk will not be searched. However, -in this case, if the database does not exist, the disk will be -searched. In @TeX{} Live, the most notable case of this is the -@code{TEXMFHOME} tree, to allow users to add and remove files from -their own tree without having to worry about @code{ls-R}. - -(Aside: there are uncommon cases where a @samp{!!} tree will be -searched on disk even if the @code{ls-R} file exists; they are too -obscure to try to explain here. See @file{pathsearch.c} in the source -if you need to know.) - -To sum up: do not create an @code{ls-R} file unless you also take care -to keep it up to date. Otherwise newly-installed files will not be -found. - - - -@node Filename aliases -@subsection Filename aliases - -@cindex filename aliases -@cindex aliases, for filenames - -In some circumstances, you may wish to find a file under several names. -For example, suppose a @TeX{} document was created using a DOS system -and tries to read @file{longtabl.sty}. But now it's being run on a Unix -system, and the file has its original name, @file{longtable.sty}. The -file won't be found. You need to give the actual file -@file{longtable.sty} an alias @samp{longtabl.sty}. - -@c As another example, suppose you are creating a @TeX{} distribution on a -@c CD-ROM or a DOS system; then the file @file{mf.base} gets stored as -@c @file{mf.bas}. But Metafont on Unix wants to find @file{mf.base}. Here -@c you need to give the actual file @file{mf.bas} an alias @samp{mf.base}. - -You can handle this by creating a file @file{aliases} as a companion to -the @file{ls-R} for the hierarchy containing the file in question. (You -must have an @file{ls-R} for the alias feature to work.) - -The format of @file{aliases} is simple: two whitespace-separated words -per line; the first is the real name @file{longtable.sty}, and second is -the alias (@file{longtabl.sty}). These must be base filenames, with no -directory components. @file{longtable.sty} must be in the sibling -@file{ls-R}. - -Also, blank lines and lines starting with @samp{%} or @samp{#} are -ignored in @file{aliases}, to allow for comments. - -If a real file @file{longtabl.sty} exists, it is used regardless of any -aliases. - - -@node Database format -@subsection Database format - -@cindex format of external database -@cindex database, format of - -The ``database'' read by Kpathsea is a line-oriented file of plain -text. The format is that generated by GNU (and most other) @code{ls} -programs given the @samp{-R} option, as follows. - -@itemize @bullet -@item -Blank lines are ignored. - -@item -If a line begins with @samp{/} or @samp{./} or @samp{../} and ends with -a colon, it's the name of a directory. (@samp{../} lines aren't useful, -however, and should not be generated.) - -@item -All other lines define entries in the most recently seen directory. -@t{/}'s in such lines will produce possibly-strange results. - -@item -Files with no preceding directory line are ignored. -@end itemize - -For example, here's the first few lines of @file{ls-R} (which totals -about 30K bytes) on my system: - -@example -bibtex -dvips -fonts -ls-R -metafont -metapost -tex -web2c - -./bibtex: -bib -bst -doc - -./bibtex/bib: -asi.bib -btxdoc.bib -@dots{} -@end example - - -@node Invoking kpsewhich -@section @code{kpsewhich}: Standalone path searching - -@pindex kpsewhich -@cindex path searching, standalone -@cindex standalone path searching - -The Kpsewhich program exercises the path searching functionality -independent of any particular application. This can also be useful as a -sort of @code{find} program to locate files in your @TeX{} hierarchies, -perhaps in administrative scripts. It is used heavily in the -distributed @samp{mktex@dots{}} scripts. - -Synopsis: - -@example -kpsewhich @var{option}@dots{} @var{filename}@dots{} -@end example - -The options and filename(s) to look up can be intermixed. -Options can start with either @samp{-} or @samp{--}, and any unambiguous -abbreviation is accepted. - -@menu -* Path searching options:: Changing the mode, resolution, etc. -* Specially-recognized files:: Default formats for texmf.cnf, etc. -* Auxiliary tasks:: Path and variable expansion, etc. -* Standard options:: @samp{--help} and @samp{--version}. -@end menu - - -@node Path searching options -@subsection Path searching options - -@cindex path searching options - -Kpsewhich looks up each non-option argument on the command line as a -filename, and returns the first file found. - -Various options alter the path searching behavior: - -@table @samp -@item --all -@opindex --all -@cindex all matches, finding -Report all matches found, one per line. By default, if there is more -than one match, just one will be reported (chosen effectively at -random). Exception: with the glyph formats (@code{pk}, @code{gf}), -this option has no effect and only the first match is returned. - -@item --casefold-search -@itemx --no-casefold-search -@opindex --casefold-search -@opindex --no-casefold-search -Explicitly enable or disable the fallback to a case-insensitive search -on Unix platforms (@pxref{Casefolding search}); no effect on Windows. -The default is enabled, set in @code{texmf.cnf}. Disabling -(@code{--no-casefold-search}) does not mean that searches magically -become case-sensitive when the underlying (file)system is -case-insensitive, it merely means that Kpathsea does not do any -casefolding itself. - -@item --cnf-line=@var{str} -@opindex --cnf-line -Parse @var{str} as if it were a line in the @file{texmf.cnf} -configuration file (@pxref{Config files}), overriding settings in the -actual configuration files, and also in the environment (@pxref{Path -sources}). This is implemented by making any settings from @var{str} -in the environment, overwriting any value already there. Thus, an -extra colon in a @samp{--cnf-line} value will refer to the value from -a configuration file, not a user-set environment variable. - -Furthermore, any variable set from @var{str} will also be set with the -program name suffix. For example, @code{pdftex ---cnf-line=TEXINPUTS=/foo:} will set both @code{TEXINPUTS} and -@code{TEXINPUTS_pdftex} in the environment (and the value will be -@file{/foo} followed by the setting from @file{texmf.cnf}, ignoring -any user-set @code{TEXINPUTS}). - -This behavior is desirable because, in practice, many variables in the -distributed @file{texmf.cnf} are program-specific, and the intuitive -behavior is for values set on the command line with @code{--cnf-line} -to override them. - -@item --dpi=@var{num} -@opindex --dpi=@var{num} -@opindex -D @var{num} -@cindex resolution, setting -Set the resolution to @var{num}; this only affects @samp{gf} and -@samp{pk} lookups. @samp{-D} is a synonym, for compatibility with -Dvips. Default is 600. - -@item --engine=@var{name} -@opindex --engine=@var{name} -@cindex engine name -Set the engine name to @var{name}. By default it is not set. The -engine name is used in some search paths to allow files with the same -name but used by different engines to coexist. - -In particular, since the memory dump files -(@file{.fmt}/@file{.base}/@file{.mem}) are now stored in -subdirectories named for the engine (@file{tex}, @file{pdftex}, -@file{xetex}, etc.), you must specify an engine name in order to find -them. For example, @file{cont-en.fmt} typically exists for both -@file{pdftex} and @file{xetex}. With the default path settings, you -can use @samp{--engine=/} to look for any dump file, regardless of -engine; if a dump file exists for more than one engine, it's -indeterminate which one is returned. (The @samp{/} ends up specifying -a normal recursive search along the path where the dumps are stored, -namely @samp{$TEXMF/web2c@{/$engine,@}}.) - -@item --format=@var{name} -@opindex --format=@var{name} -Set the format for lookup to @var{name}. By default, the format is -guessed from the filename, with @samp{tex} being used if nothing else -fits. The recognized filename extensions (including any leading -@samp{.}) are also allowable @var{name}s. - -All formats also have a name, which is the only way to specify formats -with no associated suffix. For example, for Dvips configuration files -you can use @samp{--format="dvips config"}. (The quotes are for the -sake of the shell.) - -Here's the current list of recognized names and the associated suffixes. -@xref{Supported file formats}, for more information on each of these. - -The strings in parentheses are abbreviations recognized only by -@code{kpsewhich} (not the underlying library calls). They are -provided when it would otherwise require an argument containing a -space to specify the format, to simplify quoting of calls from shells. - -@example -gf: gf -pk: pk -bitmap font (bitmapfont): -tfm: .tfm -afm: .afm -base: .base -bib: .bib -bst: .bst -cnf: .cnf -ls-R: ls-R ls-r -fmt: .fmt -map: .map -mem: .mem -mf: .mf -mfpool: .pool -mft: .mft -mp: .mp -mppool: .pool -MetaPost support (mpsupport): -ocp: .ocp -ofm: .ofm .tfm -opl: .opl .pl -otp: .otp -ovf: .ovf .vf -ovp: .ovp .vpl -graphic/figure: .eps .epsi -tex: .tex .sty .cls .fd .aux .bbl .def .clo .ldf -TeX system documentation (doc): -texpool: .pool -TeX system sources (source): .dtx .ins -PostScript header: .pro -Troff fonts (trofffont): -type1 fonts: .pfa .pfb -vf: .vf -dvips config (dvipsconfig): -ist: .ist -truetype fonts: .ttf .ttc .TTF .TTC .dfont -type42 fonts: .t42 .T42 -web2c files (web2c): -other text files (othertext): -other binary files (otherbin): -misc fonts (miscfont): -web: .web .ch -cweb: .w .web .ch -enc files: .enc -cmap files (cmap): -subfont definition files: .sfd -opentype fonts: .otf -pdftex config (pdftexconfig): -lig files: .lig -texmfscripts: -lua: .lua .luatex .luc .luctex .texlua .texluc .tlu -font feature files: .fea -cid maps: .cid .cidmap -mlbib: .mlbib .bib -mlbst: .mlbst .bst -clua: .dll .so -ris: .ris -bltxml: .bltxml -@end example - -This option and @samp{--path} are mutually exclusive. - -@item --interactive -@opindex --interactive -@cindex interactive query -After processing the command line, read additional filenames to look up -from standard input. - -@item --mktex=@var{filetype} -@itemx --no-mktex=@var{filetype} -@opindex --mktex=@var{filetype} -@opindex --no-mktex=@var{filetype} -Turn on or off the @samp{mktex} script associated with @var{filetype}. -Usual values for @var{filetype} are @samp{pk}, @samp{mf}, @samp{tex}, -and @samp{tfm}. By default, all are off in Kpsewhich, even if they -are enabled for @TeX{}. This option implies setting -@code{--must-exist}. @xref{mktex scripts}. - -@item --mode=@var{string} -@opindex --mode=@var{string} -Set the mode name to @var{string}; this also only affects @samp{gf} and -@samp{pk} lookups. No default: any mode will be found. @xref{mktex -script arguments}. - -@item --must-exist -@opindex --must-exist -Do everything possible to find the files, notably including searching -the disk and running the @samp{mktex} scripts. By default, only the -@file{ls-R} database is checked, in the interest of efficiency. - -@item --path=@var{string} -@opindex --path=@var{string} -Search along the path @var{string} (colon-separated as usual), instead -of guessing the search path from the filename. @samp{//} and all the -usual expansions are supported (@pxref{Path expansion}). This option -and @samp{--format} are mutually exclusive. To output the complete -directory expansion of a path, instead of doing a one-shot lookup, see -@samp{--expand-path} and @samp{--show-path} in the following section. - -@item --progname=@var{name} -@opindex --progname=@var{name} -Set the program name to @var{name}; default is @samp{kpsewhich}. This -can affect the search paths via the @samp{.@var{prognam}} feature in -configuration files (@pxref{Config files}). - -@item --subdir=@var{string} -@opindex --subdir=@var{string} -Report only those matches whose directory part @emph{ends} with -@var{string} (compared literally, except case is ignored on a -case-insensitive operating system). For example, suppose there are -two matches for a given name: - -@example -kpsewhich foo.sty -@result{} /some/where/foo.sty -/another/place/foo.sty -@end example - -@noindent -Then we can narrow the result to what we are interested in with -@option{--subdir}: - -@example -kpsewhich --subdir=where foo.sty -@result{} /some/where/foo.sty - -kpsewhich --subdir=place foo.sty -@result{} /another/place/foo.sty -@end example - -@noindent -The string to match must be at the end of the directory part of the -match, and it is taken literally, with no pattern matching: - -@example -kpsewhich --subdir=another foo.sty -@result{} -@end example - -@noindent -The string to match may cross directory components: - -@example -kpsewhich --subdir=some/where foo.sty -@result{} /some/where/foo.sty -@end example - -@noindent -@option{--subdir} implies @option{--all}; if there is more than one -match, they will all be reported (in our example, both @samp{where} -and @samp{place} end in @samp{e}): - -@example -kpsewhich --subdir=e -@result{} /some/where/foo.sty -/another/place/foo.sty -@end example - -@noindent -Because of the above rules, the presence of a leading @samp{/} is -important, since it ``anchors'' the match to a full component name: - -@example -kpsewhich --subdir=/lace foo.sty -@result{} -@end example - -@noindent -However, a trailing @samp{/} is immaterial (and ignored), since the -match always takes place at the end of the directory part: - -@example -kpsewhich --subdir=lace/ foo.sty -@result{} /another/place/foo.sty -@end example - -@noindent -The purpose of these rules is to make it convenient to find results -only within a particular area of the tree. For instance, a given -script named @file{foo.lua} might exist within both -@file{texmf-dist/scripts/pkg1/} and @file{texmf-dist/scripts/pkg2/}. -By specifying, say, @samp{--subdir=/pkg1}, you can be sure of getting -the one you are interested in. - -We only match at the end because a site might happen to install @TeX{} -in @file{/some/coincidental/pkg1/path/}, and we wouldn't want to match -@file{texmf-dist/scripts/pkg2/} that when searching for @samp{/pkg1}. - -@end table - - -@node Specially-recognized files -@subsection Specially-recognized files for @command{kpsewhich} - -@command{kpsewhich} recognizes a few special filenames on the command -line and defaults to using the `known' file formats for them, merely -to save the time and trouble of specifying the format. This is only a -feature of @command{kpsewhich}; when using the Kpathsea library -itself, none of these special filenames are recognized, and it's still -up to the caller to specify the desired format. - -Here is the list of special filenames to @command{kpsewhich}, along -with their corresponding format: - -@table @file - -@flindex config.ps -@item config.ps -@code{dvips config} - -@flindex dvipdfmx.cfg -@item dvipdfmx.cfg -@samp{other text files} - -@flindex fmtutil.cnf -@item fmtutil.cnf -@samp{web2c files} - -@flindex glyphlist.txt -@item glyphlist.txt -@samp{map} - -@flindex mktex.cnf -@item mktex.cnf -@samp{web2c files} - -@flindex pdfglyphlist.txt -@item pdfglyphlist.txt -@samp{map} - -@flindex pdftex.cfg -@flindex pdftexconfig.tex -@item pdftex.cfg -@samp{pdftex config} (although @file{pdftex.cfg} is not used any more; -look for the file @file{pdftexconfig.tex} instead.) - -@flindex texmf.cnf -@item texmf.cnf -@samp{cnf} - -@flindex XDvi -@item XDvi -@samp{other text files} - -@end table - -A user-specified format will override the above defaults. - -@flindex tcfmgr.map -Another useful configuration file in this regard is @file{tcfmgr.map}, -found in @file{texmf/texconfig/tcfmgr.map}, which records various -information about the above configuration files (among others). - - -@node Auxiliary tasks -@subsection Auxiliary tasks - -@cindex auxiliary tasks - -Kpsewhich provides some features in addition to path lookup as such: - -@table @samp -@item --debug=@var{num} -@opindex --debug=@var{num} -Set debugging options to @var{num}. @xref{Debugging}. - -@item --expand-braces=@var{string} -@opindex --expand-braces=@var{string} -Output variable, tilde, and brace expansion of @var{string}, which is -assumed to be a single path element. @xref{Path expansion}. - -@item --expand-path=@var{string} -@opindex --expand-path=@var{string} -Output the complete expansion of @var{string}, with each element -separated by the usual path separator on the current system (@samp{;} -on Windows, @samp{:} otherwise). This may be useful to construct a -custom search path for a format not otherwise supported. To retrieve -the search path for a format that is already supported, see -@samp{--show-path}. - -Nonexistent directories are culled from the output: - -@example -$ kpsewhich --expand-path '/tmp' -@result{} /tmp -$ kpsewhich --expand-path '/nonesuch' -@result{} -@end example - -For one-shot uses of an arbitrary (not built in to Kpathsea) path, see -@samp{--path} (@pxref{Path searching options}). - -@item --expand-var=@var{string} -@opindex --expand-var=@var{string} -Output the variable and tilde expansion of @var{string}. For example, -with the usual @file{texmf.cnf}, @samp{kpsewhich ---expand-var='$TEXMF'} returns the @TeX{} system hierarchy root(s). -@xref{Path expansion}. The specified @var{string} can contain -anything, though, not just variable references. This calls -@code{kpse_var_expand} (@pxref{Programming with config files}). - -@item --help-formats -@opindex --help-formats -Output information about each supported format (@pxref{Supported file -formats}), including the names and abbreviations, variables -looked for, and the original path. - -@item --safe-in-name=@var{name} -@itemx --safe-out-name=@var{name} -@opindex --safe-in-name=@var{name} -@opindex --safe-out-name=@var{name} -Exit successfully if @var{name} is safe to open for reading or -writing, respectively, else unsuccessfully. No output is written. -These tests take account of the related Kpathsea configuration -settings (@pxref{Calling sequence}). - -@item --show-path=@var{name} -@opindex --show-path=@var{name} -Show the path that would be used for file lookups of file type -@var{name}. Either a filename extension (@samp{pk}, @samp{.vf}, etc.) -or an integer can be used, just as with @samp{--format}, described in -the previous section. - -@item --var-brace-value=@var{variable} -@opindex --var-brace-value=@var{variable} -Like @samp{--var-value} (next), but also expands @samp{@{...@}} -constructs. (@pxref{Brace expansion}). Thus, the value is assumed to -possibly be several path elements, and @samp{~} is expanded at the -beginning of each. The path separator is changed to that of the -current system in the expansion. - -Example: @samp{FOO='.;~' kpsewhich --var-brace-value=FOO} outputs (on -a Unix-ish system) @samp{.:/home/karl}, supposing the latter is the -current user's home directory. Note that the @samp{;} in the source -value, as commonly used in @file{texmf.cnf}, has changed to a -@samp{:}, as the normal path separator on the current system. On a -Windows-ish system, the @samp{;} would remain. - -@item --var-value=@var{variable} -@opindex --var-value=@var{variable} -Outputs the value of @var{variable} (a simple identifier like -@samp{TEXMFDIST}, with no @samp{$} or other constructs), expanding -@samp{$} (@pxref{Variable expansion}) and @samp{~} (@pxref{Tilde -expansion}) constructs in the value. @samp{~} expansion happens at the -beginning of the overall value and at the beginning of a variable -expansion, but not arbitrarily within the string. Braces are not expanded. - -Example: @samp{--var-value=texmf_casefold_search} outputs (if the -default is not changed) @samp{1}. - -Example to contrast with @samp{--var-brace-value}: @samp{FOO='.;~' -kpsewhich --var-value=FOO} outputs @samp{.;~}, i.e., the same as the -input value, on all systems. - -@end table - - -@node Standard options -@subsection Standard options - -@cindex standard options - -Kpsewhich accepts the standard GNU options: - -@itemize @bullet -@item -@opindex --help -@samp{--help} prints a help message on standard output and exits -successfully. - -@item -@opindex --version -@samp{--version} prints the Kpathsea version number and exits successfully. -@end itemize - - -@node TeX support -@chapter @TeX{} support - -@cindex @TeX{} support - -Although the basic features in Kpathsea can be used for any type of -path searching, it came about, as usual, with a specific application -in mind: I wrote Kpathsea specifically for @TeX{} system programs. I -had been struggling with the programs I was using (Dvips, Xdvi, and -@TeX{} itself) having slightly different notions of how to specify -paths; and debugging was painful, since no code was shared. - -Therefore, Kpathsea provides some @TeX{}-specific formats and -features. Indeed, many of the purportedly generic path searching -features were provided because they seemed useful in that con@TeX{}t -(font lookup, particularly). - -Kpathsea provides a standard way to search for files of any of the -supported file types; glyph fonts are a bit different than all the -rest. Searches are based solely on names of files, not their -contents---if a GF file is (mis)named @file{cmr10.600pk}, it will be -found as a PK file. - -@menu -* Supported file formats:: File types Kpathsea knows about. -* File lookup:: Searching for most kinds of files. -* Glyph lookup:: Searching for bitmap fonts. -* Suppressing warnings:: Avoiding warnings via TEX_HUSH. -* mktex scripts:: Generating files at runtime. -@end menu - - -@node Supported file formats -@section Supported file formats - -@cindex supported file formats -@cindex file formats, supported - -@cindex environment variables for @TeX{} -@cindex @TeX{} environment variables - -Kpathsea has support for a number of file types. Each file type has a -list of environment and config file variables that are checked to define -the search path, and most have a default suffix that plays a role in -finding files (see the next section). Some also define additional -suffixes, and/or a program to be run to create missing files on the fly. - -@cindex program-varying paths -Since environment variables containing periods, such as -@samp{TEXINPUTS.latex}, are not allowed on some systems, Kpathsea looks -for environment variables with an underscore, e.g., -@samp{TEXINPUTS_latex} (@pxref{Config files}). - -The following table lists the above information. You can also get the -list by giving the @samp{--help-formats} option to @code{kpsewhich} -(@pxref{Auxiliary tasks}). - -@table @samp -@item afm -@flindex .afm -@vindex AFMFONTS -(Adobe font metrics, @pxref{Metric files,,, dvips, Dvips}) -@code{AFMFONTS}; -suffix @samp{.afm}. - -@item base -@flindex .base -@vindex MFBASES -@vindex TEXMFINI -(Metafont memory dump, @pxref{Memory dumps,,, web2c, Web2c}) -@code{MFBASES}, @code{TEXMFINI}; -suffix @samp{.base}. - -@item bib -@flindex .bib -@vindex BIBINPUTS -@vindex TEXBIB -(Bib@TeX{} bibliography source, @pxref{bibtex invocation,,, web2c, Web2c}) -@code{BIBINPUTS}, @code{TEXBIB}; -suffix @samp{.bib}. - -@item bltxml -@flindex .bltxml -@vindex BLTXMLINPUTS -(Bib@LaTeX{}ML bibliography files for Biber, @url{https://ctan.org/pkg/biber}) -@code{BLTXMLINPUTS} -suffix @samp{.bltxml}. - -@item bst -@flindex .bst -@vindex BSTINPUTS -(Bib@TeX{} style, @pxref{Basic BibTeX style files,, Basic Bib@TeX{} -style files, web2c, Web2c}) -@code{BSTINPUTS}; -suffix @samp{.bst}. - -@item clua -@flindex .dll -@flindex .so -@vindex CLUAINPUTS -(dynamic libraries for Lua, @url{https://ctan.org/pkg/luatex}) -@code{CLUAINPUTS} -suffixes @samp{.dll} and @samp{.so}. - -@item cmap -@flindex .cmap -@vindex CMAPFONTS -(character map files) -@code{CMAPFONTS}; -suffix @samp{.cmap}. - -@item cnf -@flindex .cnf -@vindex TEXMFCNF -(Runtime configuration files, @pxref{Config files}) -@code{TEXMFCNF}; -suffix @samp{.cnf}. - -@item cweb -@flindex .w -@flindex .web -@vindex CWEBINPUTS -(CWEB input files) -@code{CWEBINPUTS}; -suffixes @samp{.w}, @samp{.web}; -additional suffix @samp{.ch}. - -@item dvips config -@vindex TEXCONFIG -@flindex config.ps@r{, search path for} -(Dvips @samp{config.*} files, such as @file{config.ps}, @pxref{Config -files,,, dvips, Dvips}) -@code{TEXCONFIG}. - -@item enc files -@flindex .enc -@vindex ENCFONTS -(encoding vectors) -@code{ENCFONTS}; -suffix @samp{.enc}. - -@item fmt -@flindex .fmt -@vindex TEXFORMATS -@vindex TEXMFINI -(@TeX{} memory dump, @pxref{Memory dumps,,, web2c, Web2c}) -@code{TEXFORMATS}, @code{TEXMFINI}; -suffix @samp{.fmt}. - -@item font cid map -@flindex .cid -@vindex FONTCIDMAPS -(CJK mapping) -@code{FONTCIDMAPS} -suffix @samp{.cid}. - -@item font feature files -@flindex .fea -@vindex FONTFEATURES -(primarily for OpenType font features) -@code{FONTFEATURES} -suffix @samp{.fea}. - -@item gf -@flindex gf -@vindex GFFONTS -@vindex GLYPHFONTS -@vindex TEXFONTS -(generic font bitmap, @pxref{Glyph files,,, dvips, Dvips}) -@code{@var{program}FONTS}, @code{GFFONTS}, @code{GLYPHFONTS}, @code{TEXFONTS}; -suffix @samp{gf}. - -@item graphic/figure -@flindex .eps -@flindex .epsi -@vindex TEXPICTS -@vindex TEXINPUTS -(Encapsulated PostScript figures, @pxref{PostScript figures,,, dvips, Dvips}) -@code{TEXPICTS}, @code{TEXINPUTS}; -additional suffixes: @samp{.eps}, @samp{.epsi}. - -@item ist -@flindex .ist -@vindex TEXINDEXSTYLE -@vindex INDEXSTYLE -(makeindex style files) -@code{TEXINDEXSTYLE}, @code{INDEXSTYLE}; -suffix @samp{.ist}. - -@item lig files -@flindex .lig -@vindex LIGFONTS -(ligature definition files) -@code{LIGFONTS}; -suffix @samp{.lig}. - -@item ls-R -@flindex ls-R -@vindex TEXMFDBS -(Filename databases, @pxref{Filename database}) -@code{TEXMFDBS}. - -@item map -@flindex .map -@vindex TEXFONTMAPS -(Fontmaps, @pxref{Fontmap}) -@code{TEXFONTMAPS}; -suffix @samp{.map}. - -@item mem -@flindex .mem -@vindex MPMEMS -@vindex TEXMFINI -(MetaPost memory dump, @pxref{Memory dumps,,, web2c, Web2c}) -@code{MPMEMS}, @code{TEXMFINI}; -suffix @samp{.mem}. - -@item @r{MetaPost support} -@vindex MPSUPPORT -(MetaPost support files, used by DMP; @pxref{dmp invocation,,, web2c, Web2c}) -@code{MPSUPPORT}. - -@item mf -@flindex .mf -@vindex MFINPUTS -(Metafont source, @pxref{mf invocation,,, web2c, Web2c}) -@code{MFINPUTS}; -suffix @samp{.mf}; -dynamic creation program: @code{mktexmf}. - -@item mfpool -@flindex .pool -@vindex MFPOOL -(Metafont program strings, @pxref{pooltype invocation,,, web2c, Web2c}) -@code{MFPOOL}, @code{TEXMFINI}; -suffix @samp{.pool}. - -@item mft -@flindex .mft -@vindex MFTINPUTS -(@code{MFT} style file, @pxref{mft invocation,,, web2c, Web2c}) -@code{MFTINPUTS}; -suffix @samp{.mft}. - -@item misc fonts -@vindex MISCFONTS -(font-related files that don't fit the other categories) -@code{MISCFONTS} - -@item mlbib -@flindex .mlbib -@vindex MLBIBINPUTS -@vindex BIBINPUTS -@vindex TEXBIB -(MlBib@TeX{} bibliography source) -@code{MLBIBINPUTS}, @code{BIBINPUTS}, @code{TEXBIB}; -suffixes @samp{.mlbib}, @samp{.mlbib}. - -@item mlbst -@flindex .mlbst -@vindex MLBSTINPUTS -@vindex BSTINPUTS -(MlBib@TeX{} style) -@code{MLBSTINPUTS}, @code{BSTINPUTS}; -suffixes @samp{.mlbst}, @samp{.bst}. - -@item mp -@flindex .mp -@vindex MPINPUTS -(MetaPost source, @pxref{mpost invocation,,, web2c, Web2c}) -@code{MPINPUTS}; -suffix @samp{.mp}. - -@item mppool -@flindex .pool -@vindex MPPOOL -(MetaPost program strings, @pxref{pooltype invocation,,, web2c, Web2c}) -@code{MPPOOL}, @code{TEXMFINI}; -suffix @samp{.pool}. - -@item ocp -@flindex .ocp -@vindex OCPINPUTS -(Omega compiled process files) -@code{OCPINPUTS}; @* -suffix @samp{.ocp}; -dynamic creation program: @code{MakeOmegaOCP}. - -@item ofm -@flindex .ofm -@vindex OFMFONTS -(Omega font metrics) -@code{OFMFONTS}, @code{TEXFONTS}; @* -suffixes @samp{.ofm}, @samp{.tfm}; -dynamic creation program: @code{MakeOmegaOFM}. - -@item opentype fonts -@vindex OPENTYPEFONTS -(OpenType fonts) -@code{OPENTYPEFONTS}. - -@item opl -@flindex .opl -(Omega property lists) -@code{OPLFONTS}, @code{TEXFONTS}; -suffix @samp{.opl}. - -@item otp -@flindex .otp -@vindex OTPINPUTS -(Omega translation process files) -@code{OTPINPUTS}; -suffix @samp{.otp}. - -@item ovf -@flindex .ovf -@vindex OVFFONTS -(Omega virtual fonts) -@code{OVFFONTS}, @code{TEXFONTS}; -suffix @samp{.ovf}. - -@item ovp -@flindex .ovp -@vindex OVPFONTS -(Omega virtual property lists) -@code{OVPFONTS}, @code{TEXFONTS}; -suffix @samp{.ovp}. - -@item pdftex config -@vindex PDFTEXCONFIG -(PDF@TeX{}-specific configuration files) -@code{PDFTEXCONFIG}. - -@item pk -@flindex .pk -@vindex PKFONTS -@vindex TEXPKS -@vindex GLYPHFONTS -@vindex TEXFONTS -(packed bitmap fonts, @pxref{Glyph files,,, dvips, Dvips}) -@code{@var{PROGRAM}FONTS} (@var{program} being @samp{XDVI}, etc.), -@code{PKFONTS}, @code{TEXPKS}, @code{GLYPHFONTS}, @code{TEXFONTS}; -suffix @samp{pk}; -dynamic creation program: @code{mktexpk}. - -@item PostScript header -@flindex .pro -@vindex TEXPSHEADERS -@vindex PSHEADERS -(downloadable PostScript, @pxref{Header files,,, dvips, Dvips}) -@code{TEXPSHEADERS}, @code{PSHEADERS}; -additional suffix @samp{.pro}. - -@item ris -@flindex .ris -@vindex RISINPUTS -(RIS bibliography files, primarily for Biber, @url{https://ctan.org/pkg/biber}) -@code{RISINPUTS} -suffix @samp{.ris}. - -@item subfont definition files -@flindex .sfd -@vindex SFDFONTS -(subfont definition files) -@code{SFDFONTS} -suffix @samp{.sfd}. - -@item tex -@flindex .tex -@vindex TEXINPUTS -(@TeX{} source, @pxref{tex invocation,,, web2c, Web2c}) -@code{TEXINPUTS}; -suffix @samp{.tex}; -additional suffixes: none, because such a list cannot be complete; -dynamic creation program: @code{mktextex}. - -@item TeX system documentation -@flindex doc files -@vindex TEXDOCS -(Documentation files for the @TeX{} system) -@code{TEXDOCS}. - -@item TeX system sources -@flindex source files -@vindex TEXSOURCES -(Source files for the @TeX{} system) -@code{TEXSOURCES}. - -@item texmfscripts -@vindex TEXMFSCRIPTS -(Architecture-independent executables distributed in the texmf trees) -@code{TEXMFSCRIPTS}. - -@item texpool -@flindex .pool -@vindex TEXPOOL -(@TeX{} program strings, @pxref{pooltype invocation,,, web2c, Web2c}) -@code{TEXPOOL}, @code{TEXMFINI}; -suffix @samp{.pool}. - -@item tfm -@flindex .tfm -@vindex TFMFONTS -@vindex TEXFONTS -(@TeX{} font metrics, @pxref{Metric files,,, dvips, Dvips}) -@code{TFMFONTS}, @code{TEXFONTS}; -suffix @samp{.tfm}; -dynamic creation program: @code{mktextfm}. - -@item Troff fonts -@vindex TRFONTS -(Troff fonts, used by DMP; @pxref{DMP invocation,,, web2c, Web2c}) -@code{TRFONTS}. - -@item truetype fonts -@flindex .ttf -@flindex .ttc -@vindex TTFONTS -(TrueType outline fonts) @code{TTFONTS}; suffixes @samp{.ttf} and -@samp{.TTF}, @samp{.ttc} and @samp{.TTC}, @samp{.dfont}. - -@item type1 fonts -@flindex .pfa -@flindex .pfb -@vindex T1FONTS -@vindex T1INPUTS -@vindex TEXPSHEADERS -@vindex DVIPSHEADERS -(Type 1 PostScript outline fonts, @pxref{Glyph files,,, dvips, Dvips}) -@code{T1FONTS}, @code{T1INPUTS}, @code{TEXPSHEADERS}, @code{DVIPSHEADERS}; -suffixes @samp{.pfa}, @samp{.pfb}. - -@item type42 fonts -@vindex T42FONTS -(Type 42 PostScript outline fonts) @code{T42FONTS}. - -@item vf -@flindex .vf -@vindex VFFONTS -@vindex TEXFONTS -(virtual fonts, @pxref{Virtual fonts,,, dvips, Dvips}) -@code{VFFONTS}, @code{TEXFONTS}; -suffix @samp{.vf}. - -@item web -@flindex .web -@vindex WEBINPUTS -(WEB input files) -@code{WEBINPUTS}; -suffix @samp{.web}; -additional suffix @samp{.ch}. - -@item web2c files -@vindex WEB2C -(files specific to the web2c implementation) -@code{WEB2C}. -@end table - -There are two special cases, because the paths and environment variables -always depend on the name of the program: the variable name is -constructed by converting the program name to upper case, and then -appending @samp{INPUTS}. Assuming the program is called @samp{foo}, -this gives us the following table. - -@table @samp -@item other text files -@vindex FOOINPUTS -(text files used by @samp{foo}) -@code{FOOINPUTS}. - -@item other binary files -@vindex FOOINPUTS -(binary files used by @samp{foo}) -@code{FOOINPUTS}. -@end table - -If an environment variable by these names are set, the corresponding -@file{texmf.cnf} definition won't be looked at (unless, as usual, the -environment variable value has an extra @samp{:}). @xref{Default -expansion}. - -For the font variables, the intent is that: -@itemize @bullet -@item -@code{TEXFONTS} is the default for everything. - -@item -@code{GLYPHFONTS} is the default for bitmap (or, more precisely, -non-metric) files. - -@item -Each font format has a variable of its own. - -@item -@vindex XDVIFONTS -@vindex DVIPSFONTS -Each program has its own font override path as well; e.g., -@code{DVIPSFONTS} for Dvipsk. Again, this is for bitmaps, not metrics. - -@end itemize - - -@node File lookup -@section File lookup - -@cindex file lookup -@cindex searching for files -@cindex @TeX{} file lookup - -This section describes how Kpathsea searches for most files (bitmap font -searches are the exception, as described in the next section). - -Here is the search strategy for a file @var{name}: - -@enumerate -@item -If the file format defines default suffixes, and the suffix of -@var{name} name is not already a known suffix for that format, try the -name with each default appended, and use alternative names found in -the fontmaps if necessary. Example: given @samp{foo.bar}, look for -@samp{foo.bar.tex}. - -@item -Search for @var{name}, and if necessary for alternative names found in -the fontmaps. Example: given @samp{foo.bar}, we also look for -@samp{foo.bar}. - -@item -If the file format defines a program to invoke to create missing files, -run it (@pxref{mktex scripts}). -@end enumerate - -@cindex extensions, filename -@cindex suffixes, filename -@vindex try_std_extension_first -The order in which we search for ``suffixed'' name (item@tie{}1) or -the ``as-is'' name (item@tie{}2) is controlled by the -@file{try_std_extension_first} configuration value. The default set -in @file{texmf.cnf} is true, since common suffixes are already -recognized: @samp{babel.sty} will only look for @samp{babel.sty}, not -@samp{babel.sty.tex}, regardless of this setting. - -When the suffix is unknown (e.g., @samp{foo.bar}), both names are -always tried; the difference is the order in which they are tried. - -@file{try_std_extension_first} only affects names being looked up -which *already* have an extension. A name without an extension (e.g., -@samp{tex story}) will always have an extension added first. - -@flindex tex-file.c -@findex kpathsea_find_file -This algorithm is implemented in the function -@code{kpathsea_find_file} in the source file -@file{kpathsea/tex-file.c}. You can watch it in action with the -debugging options (@pxref{Debugging}). - - -@node Glyph lookup -@section Glyph lookup - -@cindex glyph lookup -@cindex searching for glyphs -@cindex @TeX{} glyph lookup - -This section describes how Kpathsea searches for a bitmap font in GF or -PK format (or either) given a font name (e.g., @samp{cmr10}) and a -resolution (e.g., 600). - -Here is an outline of the search strategy (details in the sections -below) for a file @var{name} at resolution @var{dpi}. The search stops -at the first successful lookup. - -@enumerate -@item -Look for an existing file @var{name}.@var{dpi}@var{format} in the -specified format(s). - -@item If @var{name} is an alias for a file @var{f} in the fontmap -file @file{texfonts.map}, look for @var{f}.@var{dpi}. - -@item Run an external program (typically named @samp{mktexpk}) to -generate the font (@pxref{mktex scripts}) - -@item Look for @var{fallback}.@var{dpi}, where @var{fallback} is some -last-resort font (typically @samp{cmr10}). -@end enumerate - -@flindex tex-glyph.c -@findex kpathsea_find_glyph -This is implemented in @code{kpathsea_find_glyph} in -@file{kpathsea/tex-glyph.c}. - -@menu -* Basic glyph lookup:: Features common to all glyph lookups. -* Fontmap:: Aliases for fonts. -* Fallback font:: Resolutions and fonts of last resort. -@end menu - - -@node Basic glyph lookup -@subsection Basic glyph lookup - -@cindex basic glyph lookup -@cindex common features in glyph lookup - -When Kpathsea looks for a bitmap font @var{name} at resolution @var{dpi} -in a format @var{format}, it first checks each directory in the search -path for a file @samp{@var{name}.@var{dpi}@var{format}}; for example, -@samp{cmr10.600pk}. Kpathsea looks for a PK file first, then a GF file. - -If that fails, Kpathsea looks for -@samp{dpi@var{dpi}/@var{name}.@var{format}}; for example, -@samp{dpi600/cmr10.pk}. This is how fonts are typically stored on -filesystems (such as DOS) that permit only three-character extensions. - -@cindex tolerance for glyph lookup -@cindex glyph lookup bitmap tolerance -@findex KPSE_BITMAP_TOLERANCE -If that fails, Kpathsea looks for a font with a close-enough @var{dpi}. -``Close enough'' is defined by the macro @code{KPSE_BITMAP_TOLERANCE} in -@file{kpathsea/tex-glyph.h} to be @code{@var{dpi} / 500 + 1}. This is -slightly more than the 0.2% minimum allowed by the DVI standard -(@url{@var{CTAN:}/dviware/driv-standard/level-0}). - - -@node Fontmap -@subsection Fontmap - -@cindex fontmap files -@cindex font alias files -@cindex aliases for fonts - -@flindex texfonts.map -If a bitmap font or metric file is not found with the original name (see -the previous section), Kpathsea looks through any @dfn{fontmap} files -for an @dfn{alias} for the original font name. These files are named -@file{texfonts.map} and searched for along the @code{TEXFONTMAPS} -environment/config file variable. All @file{texfonts.map} files that -are found are read; earlier definitions override later ones. - -This feature is intended to help in two respects: - -@enumerate - -@item -@cindex fontnames, arbitrary length -An alias name is limited in length only by available memory, not by your -filesystem. Therefore, if you want to ask for @samp{Times-Roman} -instead of @file{ptmr}, you can (you get @samp{ptmr8r}). - -@item -@cindex circle fonts -@flindex lcircle10 -A few fonts have historically had multiple names: specifically, -La@TeX{}'s ``circle font'' has variously been known as @file{circle10}, -@file{lcircle10}, and @file{lcirc10}. Aliases can make all the names -equivalent, so that it no longer matters what the name of the installed -file is; @TeX{} documents will find their favorite name. - -@end enumerate - -The format of fontmap files is straightforward: - -@itemize @bullet -@cindex comments, in fontmap files -@item Comments start with the last @samp{%} on a line and continue to -the end of the line. (This provides for names that include a %, -ill-advised as that may be.) - -@cindex whitespace, in fontmap files -@item Blank lines are ignored. - -@item Each nonblank line is broken up into a series of @dfn{words}: - a sequence of non-whitespace characters. - -@findex include @r{fontmap directive} -@item If the first word is @samp{include}, the second word is used as - a filename, and it is searched for and read. - -@item Otherwise, the first word on each line is the true filename; - -@item the second word is the alias; - -@item subsequent words are ignored. -@end itemize - -If an alias has an extension, it matches only those files with that -extension; otherwise, it matches anything with the same root, regardless -of extension. For example, an alias @samp{foo.tfm} matches only when -@file{foo.tfm} is being searched for; but an alias @samp{foo} matches -@file{foo.vf}, @file{foo.600pk}, etc. - -As an example, here is an excerpt from the @file{texfonts.map} in the -Web2c distribution. It makes the old and new names of the @LaTeX{} -circle fonts equivalent. - -@example -circle10 lcircle10 -circle10 lcirc10 -lcircle10 circle10 -lcircle10 lcirc10 -lcirc10 circle10 -lcirc10 lcircle10 -@dots{} -@end example - -Fontmaps are implemented in the file @file{kpathsea/fontmap.c}. -The Fontname distribution has much more information on font naming -(@pxref{,,,fontname, Filenames for @TeX{} fonts}). - - -@node Fallback font -@subsection Fallback font - -@cindex fallback font -@cindex fallback resolutions -@cindex font of last resort -@cindex resolutions, last-resort -@cindex last-resort font - -@vindex DVIPSSIZES -@vindex XDVISIZES -@vindex DVILJSIZES -@vindex TEXSIZES -@vindex default_texsizes -If a bitmap font cannot be found or created at the requested size, -Kpathsea looks for the font at a set of @dfn{fallback resolutions}. You -specify these resolutions as a colon-separated list (like search paths). -Kpathsea looks first for a program-specific environment variable (e.g., -@code{DVIPSSIZES} for Dvipsk), then the environment variable -@code{TEXSIZES}, then a default specified at compilation time (the Make -variable @code{default_texsizes}). You can set this list to be empty if -you prefer to find fonts at their stated size or not at all. - -@flindex cmr10@r{, as fallback font} -@findex kpathsea_init_prog -Finally, if the font cannot be found even at the fallback resolutions, -Kpathsea looks for a fallback font, typically @file{cmr10}. Programs -must enable this feature by calling @code{kpathsea_init_prog} -(@pxref{Calling sequence}); the default is no fallback font. - - -@node Suppressing warnings -@section Suppressing warnings - -@cindex warnings, suppressing -@cindex suppressing warnings - -@vindex TEX_HUSH -Kpathsea provides a way to suppress selected usually-harmless warnings; -this is useful at large sites where most users are not administrators, -and thus the warnings are merely a source of confusion, not a help. To -do this, you set the environment variable or configuration file value -@code{TEX_HUSH} to a colon-separated list of values. Here are the -possibilities: - -@vtable @samp -@item all -Suppress everything possible. - -@item checksum -@cindex mismatched checksum warnings -Suppress mismatched font checksum warnings. - -@item lostchar -@cindex missing character warnings -Suppress warnings when a character is missing from a font that a DVI or -VF file tries to typeset. - -@item none -Don't suppress any warnings. - -@item readable -@cindex unreadable file warnings -Suppress warnings about attempts to access a file whose permissions -render it unreadable. - -@item special -@cindex unknown special warnings -@findex \special@r{, suppressing warnings about} -Suppresses warnings about an unimplemented or unparsable -@samp{\special} command. -@end vtable - -@noindent @file{tex-hush.c} defines the function that checks the -variable value. Each driver implements its own checks where -appropriate. - - -@node mktex scripts -@section @file{mktex} scripts - -@cindex @file{mktex} scripts -@cindex scripts for file creation - -@cindex font set, infinite -@cindex dynamic creation of files -@cindex Sauter fonts, and dynamic source creation -@cindex EC fonts, and dynamic source creation -If Kpathsea cannot otherwise find a file, for some file types it is -configured by default to invoke an external program to create it -dynamically (@pxref{mktex configuration}). These are collectively -known as @dfn{@code{mktex} scripts}, since most of them are named -@code{mktex...}. - -For example, this is useful for fonts (bitmaps, TFM's, and -arbitrarily-sizable Metafont sources such as the Sauter and EC fonts), -since any given document can use fonts never before referenced. -Building all fonts in advance is therefore impractical, if not -impossible. - -It is also useful for the @TeX{} @samp{.fmt} (and Metafont -@samp{.base} and Metapost @samp{.mem} files, @pxref{Memory -dumps,,,Web2c,web2c}), where pre-generating every format consumes a -lot of both time and space. - -The script is passed the name of the file to create and possibly other -arguments, as explained below. It must echo the full pathname of the -file it created (and nothing else) to standard output; it can write -diagnostics to standard error. - -@menu -* config: mktex configuration. -* names: mktex script names. -* args: mktex script arguments. -@end menu - - -@node mktex configuration -@subsection @file{mktex} configuration - -@cindex @file{mktex} script configuration -@cindex configuration of @file{mktex} scripts -@cindex enabling @file{mktex} scripts -@cindex disabling @file{mktex} scripts - -The list of file types and program names that can run an external -program to create missing files is listed in the next section. In the -absence of @code{configure} options specifying otherwise, everything -but @file{mktextex} will be enabled by default. The @code{configure} -options to change the defaults are: - -@cindex @code{configure} options for @file{mktex} scripts -@opindex --without-mktexfmt-default -@opindex --without-mktexmf-default -@opindex --without-mktexocp-default -@opindex --without-mktexofm-default -@opindex --without-mktexpk-default -@opindex --without-mktextfm-default -@opindex --with-mktextex-default -@example ---without-mktexfmt-default ---without-mktexmf-default ---without-mktexocp-default ---without-mktexofm-default ---without-mktexpk-default ---without-mktextfm-default ---with-mktextex-default -@end example - -The @code{configure} setting is overridden if the environment variable -or configuration file value named for the script is set; e.g., -@file{MKTEXPK} (@pxref{mktex script arguments}). - -@flindex fmtutils.cnf -@code{mktexfmt} reads a file @file{fmtutil.cnf}, typically located in -@file{texmf/web2c/} to glean its configuration information. The rest -of the files and features in this section are primarily intended for -the font generation scripts. - -@flindex mktex.cnf -@flindex mktex.opt -@cindex site overrides for @code{mktex@dots{}} -As distributed, all the scripts source a file -@file{texmf/web2c/mktex.cnf} if it exists, so you can override various -defaults. -See @file{mktex.opt}, for instance, which defines the default mode, -resolution, some special directory names, etc. If you prefer not to -change the distributed scripts, you can simply create @file{mktex.cnf} -with the appropriate definitions (you do not need to create it if you -have nothing to put in it). @file{mktex.cnf} has no special syntax; -it's an arbitrary Bourne shell script. The distribution contains a -sample @file{mktex.cnf} for you to copy and modify as you please (it -is not installed anywhere). - -@flindex mktex.opt -@vindex MT_FEATURES -In addition, you can configure a number of features with the -@code{MT_FEATURES} variable, which you can define: - -@itemize @bullet -@item -in @file{mktex.opt}, as just mentioned; - -@item -by editing the file @file{mktex.opt}, either before @samp{make -install} (in the source hierarchy) or after (in the installed -hierarchy); - -@item -or in the environment. -@end itemize - -If none of the options below are enabled, @code{mktexpk}, -@code{mktextfm}, and @code{mktexmf} follow the following procedure to -decide where fonts should be installed. Find the tree where the font's -sources are, and test the permissions of the @samp{fonts} directory of -that tree to determine whether it is writable. If it is, put the files -in the tree in appropriate locations. If it isn't writable, see whether -the tree is a system tree (named in @code{SYSTEXMF}). If so, the -@code{VARTEXFONTS} tree is used. In all other cases the working -directory is used. - -The @samp{appendonlydir} option is enabled by default. - -@vtable @samp -@item appendonlydir -@cindex directories, making append-only -@flindex mktexdir -Tell @code{mktexdir} to create directories append-only, i.e., set -their sticky bit (@pxref{Mode Structure,,, coreutils, GNU Core -Utilities}). This feature is silently ignored on non-Unix platforms -(e.g. Windows/NT and MS-DOS) which don't support similar functionality. -This feature is enabled by default. - -@item dosnames -@cindex 8.3 filenames, using -@cindex DOS compatible names -@flindex dpi@var{nnn} directories -Use 8.3 names; e.g., @file{dpi600/cmr10.pk} instead of -@file{cmr10.600pk}. Note that this feature only affects filenames that -would otherwise clash with other TeX-related filenames; @file{mktex} -scripts do nothing about filenames which exceed the 8+3 MS-DOS limits -but remain unique when truncated (by the OS) to these limits, and nether -do the scripts care about possible clashes with files which aren't -related with TeX. For example, @file{cmr10.600pk} would clash with -@file{cmr10.600gf} and is therefore changed when @samp{dosnames} is in -effect, but @file{mf.pool} and @file{mp.base} don't clash with any -TeX-related files and are therefore unchanged. - -This feature is turned on by default on MS-DOS. If you do not wish -@samp{dosnames} to be set on an MS-DOS platform, you need to set the -@code{MT_FEATURES} environment variable to a value that doesn't include -@samp{dosnames}. You can also change the default setting by editing -@file{mktex.opt}, but only if you use the @file{mktex} shell scripts; -the emulation programs don't consult @file{mktex.opt}. - -@item fontmaps -@cindex fontmaps -@cindex fontname -Instead of deriving the location of a font in the destination tree from -the location of the sources, the aliases and directory names from the -Fontname distribution are used. (@pxref{Top,, Introduction, fontname, -Fontname}). - -@item nomfdrivers -@cindex metafont driver files -Let mktexpk and mktextfm create metafont driver files in a temporary -directory. These will be used for just one metafont run and not -installed permanently. - -@item nomode -@cindex mode directory, omitting -Omit the directory level for the mode name; this is fine as long as -you generate fonts for only one mode. - -@item stripsupplier -@cindex supplier directory, omitting -Omit the font supplier name directory level. - -@item striptypeface -@cindex typeface directory, omitting -Omit the font typeface name directory level. - -@item strip -@cindex supplier directory, omitting -@cindex typeface directory, omitting -Omit the font supplier and typeface name directory levels. This feature -is deprecated in favour of @samp{stripsupplier} and @samp{striptypeface}. - -@item varfonts -@flindex /var/tmp/texfonts -@vindex VARTEXFONTS -@cindex Linux File System Standard -When this option is enabled, fonts that would otherwise be written in -system texmf tree go to the @code{VARTEXFONTS} tree instead. The -default value in @file{kpathsea/Makefile.in} is -@file{/var/tmp/texfonts}. The @cite{Linux File System Standard} -recommends @file{/var/tex/fonts}. - -@vindex USE_VARTEXFONTS -The @samp{varfonts} setting in @code{MT_FEATURES} is overridden by the -@code{USE_VARTEXFONTS} environment variable: if set to @samp{1}, the -feature is enabled, and if set to @samp{0}, the feature is disabled. - -@item texmfvar -@vindex TEXMFVAR -Force generated files that would go into a system tree (as defined by -@code{SYSTEXMF}) into @code{TEXMFVAR}. Starting with te@TeX{}-3.0, the -variable @code{TEXMFVAR} is always set. The @samp{varfonts} feature takes -precedence if also set. - -@vindex USE_TEXMFVAR -The @samp{texmfvar} setting in @code{MT_FEATURES} is overridden by the -@code{USE_TEXMFVAR} environment variable: if set to @samp{1}, the -feature is enabled, and if set to @samp{0}, the feature is disabled. -@end vtable - - -@node mktex script names -@subsection @file{mktex} script names - -@cindex @file{mktex} script names -@cindex names for @file{mktex} scripts - -The following table shows the default name of the script for each -of the file types which support runtime generation. - -@table @file -@item mktexfmt -@pindex mktexfmt -@pindex fmtutil -(@samp{.fmt}, @samp{.base}, @samp{.mem}) @TeX{}/Metafont/MetaPost -formats. This script is also named @command{fmtutil}, and reads -@file{fmtutil.cnf} for configuration information. - -@item mktexmf -@pindex mktexmf -(@samp{.mf}) Metafont input files. - -@item mkocp -@pindex mkocp -(@samp{.ocp}) Omega compiled process files. - -@item mkofm -@pindex mkofm -(@samp{.ofm}) Omega font metric files. - -@item mktexpk -@pindex mktexpk -(@samp{pk}) Glyph fonts. - -@item mktextex -@pindex mktextex -(@samp{.tex}) @TeX{} input files (disabled by default). - -@item mktextfm -@pindex mktextfm -(@samp{.tfm}) TFM files. -@end table - -@vindex DVIPSMAKEPK -@vindex XDVIMAKEPK -@vindex DVILJMAKEPK -@noindent These names can be overridden by an environment variable specific -to the program---for example, @code{DVIPSMAKEPK} for Dvipsk. - -@comment next two paragraphs are repeated in dvips.texi -@flindex missfont.log -@cindex failed @code{mktex@dots{}} script invocation -If a @code{mktex@dots{}} script fails, the invocation is appended to a -file @file{missfont.log} (by default) in the current directory. You can -then execute the log file to create the missing files after fixing the -problem. - -@vindex TEXMFOUTPUT -@vindex MISSFONT_LOG -If the current directory is not writable and the environment variable or -configuration file value @code{TEXMFOUTPUT} is set, its value is -used. Otherwise, nothing is written. The name @samp{missfont.log} is -overridden by the @code{MISSFONT_LOG} environment variable or -configuration file value. - - -@node mktex script arguments -@subsection @file{mktex} script arguments - -@cindex arguments to @file{mktex} - -The first argument to a @file{mktex} script is always the name -of the file to be created. - -In the default @file{mktexpk} implementation, additional arguments may -also be passed: - -@table @samp -@item --dpi @var{num} -Sets the resolution of the generated font to @var{num}. -@item --mfmode @var{name} -Sets the Metafont mode to @var{name}. -@item --bdpi @var{num} -Sets the ``base dpi'' for the font. This must match the mode being -used. -@item --mag @var{string} -A ``magstep'' string suitable for the Metafont @code{mag} variable. -This must match the combination of @var{bdpi} and @var{dpi} being used. -@item --destdir @var{string} -A directory name. If the directory is absolute, it is used as-is. -Otherwise, it is appended to the root destination directory set in the -script. -@end table - - -@node Programming -@chapter Programming - -This chapter is for programmers who wish to use Kpathsea. -@xref{Introduction}, for the conditions under which you may do so (in -short, it is released under LGPLv2.1 or later). - -@menu -* Overview: Programming overview. Introduction. -* Calling sequence:: Specifics of what to call. -* Program-specific files:: How to handle these. -* Config: Programming with config files. Getting info from texmf.cnf. -@end menu - - -@node Programming overview -@section Programming overview - -@cindex programming overview -@cindex overview of programming with Kpathsea - -Aside from this manual, your best source of information is the source -to the programs that use Kpathsea (@pxref{Introduction}). First, -Kpsewhich is a small utility program whose sole purpose is to exercise -the main path-searching functionality. Of the drivers, Dviljk is -probably the simplest full application program. 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. - -@cindex re-entrant API -@cindex API, re-entrant -When looking at these program sources, you should know that previous -versions of the library had a different programming interface; the -current interface supports re-entrancy. Historically, the library -function names were prefixed with @code{kpse_} instead of -@code{kpathsea_}, and they did not need an instance variable as first -argument. This change was made in 2009. The old functions will never -disappear, and can reliably continue to be used when they suffice, as -they do for the programs above. The main application using the -re-entrant API is the MetaPost library used by MetaPost and Lua@TeX{}. - -@flindex pathsearch.h -@flindex tex-file.h -@flindex tex-glyph.h -@flindex kpathsea.h -Beyond these examples, the @file{.h} files in the Kpathsea source -describe the interfaces and functionality (and of course the @file{.c} -files define the actual routines, which are the ultimate documentation). -@file{pathsearch.h} declares the basic searching routine. -@file{tex-file.h} and @file{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 @code{#include -<kpathsea/kpathsea.h>}, which includes every Kpathsea header. - -@flindex config.h -@flindex c-auto.h -If you want to include only specific headers, you should still consider -including @file{kpathsea/config.h} before including any other Kpathsea -header, as it provides symbols used in the other headers. Note that -@file{kpathsea/config.h} includes @file{kpathsea/c-auto.h}, which is -generated by Autoconf. - -@cindex file types, registering new -The library provides no way for an external program to register new file -types: @file{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 @file{texmf.cnf} (and its descendant @file{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. - - -@node Calling sequence -@section Calling sequence - -@cindex programming with Kpathsea -@cindex calling sequence - -The typical way to use Kpathsea in your program goes something like this: - -@enumerate - -@item -@findex kpathsea_new -Call @code{kpathsea_new} to create a new library instance. This variable -must be passed as the first argument to all the following library functions. -The rest of this manual will be using @code{kpse} as a placeholder for -the name of this variable. - -@item -@findex kpathsea_set_program_name -@vindex argv[0] -Call @code{kpathsea_set_program_name} with @code{argv[0]} as the second -argument; the third argument is a string or @code{NULL}. The third -argument is used by Kpathsea as the program name for the -@code{.@var{program}} feature of config files (@pxref{Config files}). -If the third argument is @code{NULL}, the value of the second argument -is used. This function must be called before any other use of the -Kpathsea library. - -@vindex kpse->invocation_name -@vindex kpse->invocation_short_name -@vindex kpse->program_name -@cindex error message macros -@code{kpathsea_set_program_name} always sets the variables -@code{kpse->invocation_name} and @code{kpse->invocation_short_name}. -These variables are used in the error message macros defined in -@file{kpathsea/lib.h}. It sets the variable -@code{kpse->program_name} to the program name it uses. - -@vindex KPATHSEA_DEBUG -It also initializes debugging options based on the environment -variable @code{KPATHSEA_DEBUG} (if that is set). - -@cindex SELFAUTOLOC -@cindex SELFAUTODIR -@cindex SELFAUTOPARENT -@cindex symlinks, resolving -@cindex expanding symlinks -Finally, it sets the environment variables @code{SELFAUTOLOC}, @code{SELFAUTODIR} -and @code{SELFAUTOPARENT} to the location, parent and grandparent -directory of the executable, removing @file{.} and @file{..} path -elements and resolving symbolic links. These are used in the default -configuration file to allow people to invoke TeX from anywhere. You -can use @samp{kpsewhich --expand-var=\$SELFAUTOLOC}, etc., to see the -values. - -@item -@vindex kpse->debug @r{variable} -@cindex debugging options, in Kpathsea-using program -Set debugging options. @xref{Debugging}. If your program doesn't have a -debugging option already, you can define one and set -@code{kpse->debug} to the number that the user supplies (as in Dviljk -and Web2c), or you can just omit this altogether (people can always set -@code{KPATHSEA_DEBUG}). If you do have runtime debugging already, you -need to merge Kpathsea's options with yours (as in Dvipsk and Xdvik). - -@item -@vindex client_path @r{in @code{kpse->format_info}} -@vindex kpse->format_info -@flindex resident.c -@cindex config files, for Kpathsea-using programs -If your program has its own configuration files that can define search -paths, you should assign those paths to the @code{client_path} member in -the appropriate element of the @code{kpse->format_info} array. (This -array is indexed by file type; see @file{tex-file.h}.) See -@file{resident.c} in Dvipsk for an example. - -@item -@findex kpathsea_init_prog -@flindex proginit.h -Call @code{kpathsea_init_prog} (see @file{proginit.c}). It's useful for the -DVI drivers, at least, but for other programs it may be simpler to -extract the parts of it that actually apply. This does not initialize -any paths, it just looks for (and sets) certain environment variables -and other random information. (A search path is always initialized at -the first call to find a file of that type; this eliminates much useless -work, e.g., initializing the Bib@TeX{} search paths in a DVI driver.) - -@item -@findex kpathsea_find_file -The routine to actually find a file of type @var{format} is -@file{kpathsea_find_file}. You can call -@code{kpathsea_find_file} after doing only the first and second of the -initialization steps above---Kpathsea automatically reads the -@file{texmf.cnf} generic config files, looks for environment variables, -and does expansions at the first lookup. - -@item -To find PK and/or GF bitmap fonts, the routine -is @code{kpathsea_find_glyph}, defined in -@file{tex-glyph.h}. This returns a structure in addition to the -resultant filename, because fonts can be found in so many ways. See the -documentation in the source. - -@item -@findex kpathsea_open_file -To actually open a file, not just return a filename, call -@code{kpathsea_open_file}. This function takes the name to look up and a -Kpathsea file format as arguments, and returns the usual @code{FILE *}. -It always assumes the file must exist, and thus will search the disk if -necessary (unless the search path specified @samp{!!}, etc.). In other -words, if you are looking up a VF or some other file that need not -exist, don't use this. - -@item -@findex kpathsea_out_name_ok -@TeX{} can write output files, via the @code{\openout} primitive; this opens -a security hole vulnerable to Trojan horse attack: an unwitting user could -run a @TeX{} program that overwrites, say, @file{~/.rhosts}. Analogous -security holes exist for many other programs. To alleviate this, there is a -configuration variable @code{openout_any}, which selects one of three levels -of security. When it is set to @samp{a} (for ``any''), no restrictions are -imposed. When it is set to @samp{r} (for ``restricted''), filenames -beginning with @samp{.} are disallowed (except @file{.tex} because @LaTeX{} -needs it). When it is set to @samp{p} (for ``paranoid'') additional -restrictions are imposed: an absolute filename must refer to a file in (a -subdirectory) of @code{TEXMFOUTPUT}, and any attempt to go up a directory -level is forbidden (that is, paths may not contain a @samp{..} component). -The paranoid setting is the default. (For backwards compatibility, @samp{y} -and @samp{1} are synonyms of @samp{a}, while @samp{n} and @samp{0} are -synonyms for @samp{r}.) The function @code{kpathsea_out_name_ok}, with a -filename as second argument, returns @code{true} if that filename is -acceptable to be opend for output or @code{false} otherwise. - -@item -@findex kpathsea_in_name_ok -Similarly, the function @code{kpathsea_in_name_ok}, with a filename as -second argument, returns @code{true} if that filename is acceptable to be -opend for input or @code{false} otherwise, depending on the value of the -configuration variable @code{openin_any} (with @samp{a} as default). - -@item -@findex kpathsea_finish -To close the kpathsea library instance you are using, call -@code{kpathsea_finish}. This function closes any open log files and -frees the memory used by the instance. - -@end enumerate - -@cindex hash table routines -@cindex memory allocation routines -@cindex string routines -@cindex reading arbitrary-length lines -@cindex input lines, reading -@cindex lines, reading arbitrary-length -Kpathsea also provides many utility routines. Some are generic: hash -tables, memory allocation, string concatenation and copying, string -lists, reading input lines of arbitrary length, etc. Others are -filename-related: default path, tilde, and variable expansion, -@code{stat} calls, etc. (Perhaps someday I'll move the former to a -separate library.) - -@flindex c-*.h -@pindex autoconf@r{, recommended} -The @file{c-*.h} header files can also help your program adapt to many -different systems. You will almost certainly want to use Autoconf and -probably Automake for configuring and building your software if you use -Kpathsea; I strongly recommend using Autoconf and Automake regardless. -They are available from @url{https://gnu.org/software}. - - -@node Program-specific files -@section Program-specific files - -Many programs will need to find some configuration files. Kpathsea -contains some support to make it easy to place them in their own -directories. The Standard @TeX{} directory structure (@pxref{Top,, -Introduction, tds, A Directory Structure for @TeX{} files}), specifies -that such files should go into a subdirectory named after the program, -like @samp{texmf/ttf2pk}. - -Two formats, @samp{kpse_program_text_format} and -@samp{kpse_program_binary_format}, use @code{.:$TEXMF/@var{program}//} -as their compiled-in search path. To override this default, you can -use the variable @code{@var{PROGRAM}INPUTS} in the environment and/or -@samp{texmf.cnf}. That is to say, the name of the variable is -constructed by converting the name of the program to upper case, and -appending @code{INPUTS}. - -The only difference between these two formats is whether -@code{kpathsea_open_file} will open the files it finds in text or binary -mode. - - -@node Programming with config files -@section Programming with config files - -@cindex programming with config files -@cindex config files, programming with - -You can (and probably should) use the same @code{texmf.cnf} -configuration file that Kpathsea uses for your program. This helps -installers by keeping all configuration in one place. - -@findex kpathsea_var_value -@flindex variable.h -@vindex shell_escape@r{, example for code} -To retrieve a value for a configuration variable @var{var}, the best -way is to call @code{kpathsea_var_value} on the string -@code{@var{var}}. This will look first for an environment variable -@var{var}, then a config file value. The result will be the value -found or @samp{NULL}. This function is declared in -@file{kpathsea/variable.h}. For an example, see the -@code{shell_escape} code in @file{web2c/lib/texmfmp.c}. - -The routine to do full variable and tilde expansion of an arbitrary -string in the context of a search path (as opposed to simply -retrieving a value) is @code{kpathsea_var_expand}, also declared in -@file{kpathsea/variable.h}. However, it's generally only necessary to -set the search path structure components as explained in the previous -section instead of using this directly. Because of its usage with any -input string, undefined @code{$FOO} constructs in the argument to -@code{kpathsea_var_expand} are returned literally (@code{"$FOO"}), -while undefined @code{$@{FOO@}} constructs are expanded to the empty -string. - -@findex kpathsea_cnf_get -@flindex cnf.h -If for some reason you want to retrieve a value @emph{only} from a -config file, not automatically looking for a corresponding environment -variable, call @code{kpathsea_cnf_get} (declared in @file{kpathsea/cnf.h}) -with the string @var{var}. - -No initialization calls are needed. - - -@node Reporting bugs -@chapter Reporting bugs - -@cindex reporting bugs -@cindex bugs, reporting - -@flindex tex-k@@tug.org @r{(bug address)} -@cindex bug address -If you have problems or suggestions, please report them to -@email{tex-k@@tug.org} using the bug checklist below. - -Please report bugs in the documentation; not only factual errors or -inconsistent behavior, but unclear or incomplete explanations, typos, -wrong fonts, @dots{} - -@menu -* Bug checklist:: What to include in a good bug report. -* Mailing lists:: Joining the bugs or announcements mailing lists. -* Debugging:: Analyzing runtime problems. -* Logging:: Recording searches. -* Common problems:: When things go wrong. -@end menu - - -@node Bug checklist -@section Bug checklist - -@cindex checklist for bug reports -@cindex bug checklist - -Before reporting a bug, please check below to be sure it isn't already -known (@pxref{Common problems}). - -Bug reports should be sent via electronic mail to -@email{tex-k@@tug.org}. - -The general principle is that a good bug report includes all the -information necessary for reproduction. Therefore, to enable -investigation, your report should include the following: - -@itemize @bullet -@item -@cindex version numbers, determining -The version number(s) of the program(s) involved, and of Kpathsea -itself. You can get the former by giving a sole option @samp{--version} -to the program, and the latter by running @samp{kpsewhich --version}. -The @file{NEWS} and @file{ChangeLog} files also contain the version -number. - -@item -@pindex uname -The hardware, operating system (including version), compiler, and -@code{make} program you are using (the output of @code{uname -a} is a -start on the first two, though incomplete). - -@item -@flindex config.log -Any options you gave to @code{configure}. This is recorded in the -@file{config.status} files. - -@cindex configuration bugs -@flindex config.status -If you are reporting a bug in @samp{configure} itself, it's probably -system-dependent, and it will be unlikely the maintainers can do -anything useful if you merely report that thus-and-such is broken. -Therefore, you need to do some additional work: for some bugs, you can -look in the file @file{config.log} where the test that failed should -appear, along with the compiler invocation and source program in -question. You can then compile it yourself by hand, and discover why -the test failed. Other @samp{configure} bugs do not involve the -compiler; in that case, the only recourse is to inspect the -@code{configure} shell script itself, or the Autoconf macros that -generated @code{configure}. - -@item -The log of all debugging output, if the bug is in path searching. You -can get this by setting the environment variable @code{KPATHSEA_DEBUG} -to @samp{-1} before running the program. Please look at the log -yourself to make sure the behavior is really a bug before reporting it; -perhaps ``old'' environment variable settings are causing files not to -be found, for example. - -@item -The contents of any input files necessary to reproduce the bug. For -bugs in DVI-reading programs, for example, this generally means a DVI -file (and any EPS or other files it uses)---@TeX{} source files are -helpful, but the DVI file is required, because that's the actual -program input. - -@item -@cindex context diff -@cindex sending patches -@flindex ChangeLog @r{entry} -If you are sending a patch (do so if you can!), please do so in the form -of a context diff (@samp{diff -c}) against the original distribution -source. Any other form of diff is either not as complete or harder for -me to understand. Please also include a @file{ChangeLog} entry. - -@item -@cindex stack trace -@cindex debugger -@cindex crashes, reporting -@cindex core dumps, reporting -@cindex null pointers, dereferencing -@pindex gdb@r{, recommended} -If the bug involved is an actual crash (i.e., core dump), it is easy -and useful to include a stack trace from a debugger (I recommend the -GNU debugger GDB (@url{https://gnu.org/software/gdb}). If the -cause is apparent (a @code{NULL} value being dereferenced, for -example), please send the details along. If the program involved is -@TeX{} or Metafont, and the crash is happening at apparently-sound -code, however, the bug may well be in the compiler, rather than in the -program or the library (@pxref{TeX or Metafont failing,, @TeX{} or -Metafont failing}). - -@item -Any additional information that will be helpful in reproducing, -diagnosing, or fixing the bug. -@end itemize - - -@node Mailing lists -@section Mailing lists - -@cindex mailing lists -@cindex bug mailing list -@cindex announcement mailing list - -@flindex tex-k@@tug.org -Web2c and Kpathsea in general are discussed on the mailing list -@email{tex-k@@tug.org}. You can subscribe and peruse the archives on -the web @url{https://lists.tug.org/tex-k}. - -You do not need to join to submit a report, nor will it affect whether -you get a response. Be aware that large data files are sometimes -included in bug reports. If this is a problem for you, do not join -the list. - -If you are looking for general @TeX{} help, such as how to install a -full @TeX{} system or how to use @LaTeX{}, please see -@url{https://tug.org/begin.html}. - - -@node Debugging -@section Debugging - -@cindex debugging -@cindex runtime debugging -@cindex options for debugging - -@vindex kpse->debug -@flindex debug.h -Kpathsea provides a number of runtime debugging options, detailed below -by their names and corresponding numeric values. When the files you -expect aren't being found, the thing to do is enable these options and -examine the output. - -You can set these with some runtime argument (e.g., @samp{-d}) to the -program; in that case, you should use the numeric values described in -the program's documentation (which, for Dvipsk and Xdvik, are different -than those below). It's best to give the @samp{-d} (or whatever) option -first, for maximal output. Dvipsk and Xdvik have additional -program-specific debugging options as well. - -@vindex KPATHSEA_DEBUG -@vindex kpse->debug -You can also set the environment variable @code{KPATHSEA_DEBUG}; in this -case, you should use the numbers below. If you run the program under a -debugger and set the instance variable @code{kpse->debug}, also use the numbers -below. - -@kindex -1 @r{debugging value} -In any case, by far the simplest value to use is @samp{-1}, which will -turn on all debugging output. This is usually better than guessing -which particular values will yield the output you need. - -@cindex debugging output -@cindex standard error and debugging output -Debugging output always goes to standard error, so you can redirect it -easily. For example, in Bourne-compatible shells: -@example -dvips -d -1 @dots{} 2>/tmp/debug -@end example - -@cindex Kpsewhich, and debugging -It is sometimes helpful to run the standalone Kpsewhich utility -(@pxref{Invoking kpsewhich}), instead of the original program. - -@cindex numeric debugging values -In any case, you cannot use the names below; you must always use -somebody's numbers. (Sorry.) To set more than one option, just sum -the corresponding numbers. - -@vtable @code -@item KPSE_DEBUG_STAT @r{(1)} -Report @samp{stat}(2) calls. This is useful for verifying that your -directory structure is not forcing Kpathsea to do many additional file -tests (@pxref{Slow path searching}, and @pxref{Subdirectory -expansion}). If you are using an up-to-date @file{ls-R} database -(@pxref{Filename database}), this should produce no output unless a -nonexistent file that must exist is searched for. - -@item KPSE_DEBUG_HASH @r{(2)} -Report lookups in all hash tables: @file{ls-R} and @file{aliases} -(@pxref{Filename database}); font aliases (@pxref{Fontmap}); and config -file values (@pxref{Config files}). Useful when expected values are not -being found, e.g.., file searches are looking at the disk instead of -using @file{ls-R}. - -@item KPSE_DEBUG_FOPEN @r{(4)} -@findex fopen@r{, redefined} -Report file openings and closings. Especially useful when your system's -file table is full, for seeing which files have been opened but never -closed. In case you want to set breakpoints in a debugger: this works by -redefining @samp{fopen} (@samp{fclose}) to be @samp{kpse_fopen_trace} -(@samp{kpse_fclose_trace}). - -@item KPSE_DEBUG_PATHS @r{(8)} -@tindex kpse_format_info_type -Report general path information for each file type Kpathsea is asked to -search. This is useful when you are trying to track down how a -particular path got defined---from @file{texmf.cnf}, @file{config.ps}, -an environment variable, the compile-time default, etc. This is the -contents of the @code{kpse_format_info_type} structure defined in -@file{tex-file.h}. - -@item KPSE_DEBUG_EXPAND @r{(16)} -Report the directory list corresponding to each path element Kpathsea -searches. This is only relevant when Kpathsea searches the disk, since -@file{ls-R} searches don't look through directory lists in this way. - -@item KPSE_DEBUG_SEARCH @r{(32)} -Report on each file search: the name of the file searched for, the path -searched in, whether or not the file must exist (when drivers search for -@file{cmr10.vf}, it need not exist), and whether or not we are -collecting all occurrences of the file in the path (as with, e.g., -@file{texmf.cnf} and @file{texfonts.map}), or just the first (as with -most lookups). This can help you correlate what Kpathsea is doing with -what is in your input file. - -@item KPSE_DEBUG_VARS @r{(64)} -Report the value of each variable Kpathsea looks up. This is useful for -verifying that variables do indeed obtain their correct values. - -@item GSFTOPK_DEBUG @r{(128)} -Activates debugging printout specific to @code{gsftopk} program. - -@item MAKETEX_DEBUG @r{(512)} -If you use the optional @code{mktex} programs instead of the -traditional shell scripts, this will report the name of the site file -(@file{mktex.cnf} by default) which is read, directories created by -@code{mktexdir}, the full path of the @file{ls-R} database built by -@code{mktexlsr}, font map searches, @code{MT_FEATURES} in effect, -parameters from @code{mktexnam}, filenames added by -@code{mktexupd}, and some subsidiary commands run by the programs. - -@item MAKETEX_FINE_DEBUG @r{(1024)} -When the optional @code{mktex} programs are used, this will print -additional debugging info from functions internal to these programs. -@end vtable - -@cindex @samp{kdebug:} -@vindex hash_summary_only @r{variable for debugging} -@cindex hash table buckets, printing -Debugging output from Kpathsea is always written to standard error, and -begins with the string @samp{kdebug:}. (Except for hash table buckets, -which just start with the number, but you can only get that output -running under a debugger. See comments at the @code{hash_summary_only} -variable in @file{kpathsea/db.c}.) - - -@node Logging -@section Logging - -@cindex log file - -@cindex logging successful searches -@cindex recording successful searches -@cindex usage patterns, finding -@cindex disk usage, reducing -Kpathsea can record the time and filename found for each successful -search. This may be useful in finding good candidates for deletion when -your filesystem is full, or in discovering usage patterns -at your site. - -@vindex TEXMFLOG -To do this, define the environment or config file variable -@code{TEXMFLOG}. The value is the name of the file to append the -information to. The file is created if it doesn't exist, and appended -to if it does. - -@cindex epoch, seconds since -@findex time @r{system call} -Each successful search turns into one line in the log file: two words -separated by a space. The first word is the time of the search, as the -integer number of seconds since ``the epoch'', i.e., UTC midnight 1 -January 1970 (more precisely, the result of the @code{time} system -call). The second word is the filename. - -For example, after @code{setenv TEXMFLOG /tmp/log}, running Dvips on -@file{story.dvi} appends the following lines: - -@example -774455887 /usr/local/share/texmf/dvips/config.ps -774455887 /usr/local/share/texmf/dvips/psfonts.map -774455888 /usr/local/share/texmf/dvips/texc.pro -774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk -774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk -774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk -774455889 /usr/local/share/texmf/dvips/texc.pro -@end example - -@cindex privacy, semblance of -@noindent Only filenames that are absolute are recorded, to preserve -some semblance of privacy. - -In addition to this Kpathsea-specific logging, @command{pdftex} -provides an option @option{-recorder} to write the names of all files -accessed during a run to the file @file{@var{basefile}.fls}. - -Finally, most systems provide a general tool to output each system -call, thus including opening and closing files. It might be named -@command{strace}, @command{truss}, @command{struss}, or something -else. - - -@node Common problems -@section Common problems - -@cindex common problems -@cindex problems, common -@cindex FAQ, Kpathsea - -Here are some common problems with configuration, compilation, linking, -execution, @dots{} - -@menu -* Unable to find files:: If your program can't find fonts (or whatever). -* Slow path searching:: If it takes forever to find anything. -* Unable to generate fonts:: If mktexpk fails. -* TeX or Metafont failing:: Likely compiler bugs. -@end menu - -@node Unable to find files -@subsection Unable to find files - -@cindex unable to find files -@cindex files, unable to find - -If a program complains it cannot find fonts (or other input files), any -of several things might be wrong. In any case, you may find the -debugging options helpful. @xref{Debugging}. - -@itemize @bullet -@item -Perhaps you simply haven't installed all the necessary files; the basic -fonts and input files are distributed separately from the programs. -@xref{unixtex.ftp}. - -@item -@flindex /etc/profile -@cindex environment variables, old -You have (perhaps unknowingly) told Kpathsea to use search paths that -don't reflect where the files actually are. One common cause is having -environment variables set from a previous installation, thus overriding -what you carefully set in @file{texmf.cnf} (@pxref{Supported file -formats}). System @file{/etc/profile} or other files such may be the -culprit. - -@item -@cindex symbolic links not found -@cindex leaf directories wrongly guessed -Your files reside in a directory that is only pointed to via a symbolic -link, in a leaf directory and is not listed in @file{ls-R}. - -Unfortunately, Kpathsea's subdirectory searching has an irremediable -deficiency: If a directory @var{d} being searched for subdirectories -contains plain files and symbolic links to other directories, but no -true subdirectories, @var{d} will be considered a leaf directory, i.e., -the symbolic links will not be followed. @xref{Subdirectory expansion}. - -You can work around this problem by creating an empty dummy subdirectory -in @var{d}. Then @var{d} will no longer be a leaf, and the symlinks will -be followed. - -The directory immediately followed by the @samp{//} in the path -specification, however, is always searched for subdirectories, even if -it is a leaf. Presumably you would not have asked for the directory to -be searched for subdirectories if you didn't want it to be. - -@item -If the fonts (or whatever) don't already exist, @code{mktexpk} (or -@code{mktexmf} or @code{mktextfm}) will try to create them. If -these rather complicated shell scripts fail, you'll eventually get an -error message saying something like @samp{Can't find font -@var{fontname}}. The best solution is to fix (or at least report) the -bug in @code{mktexpk}; the workaround is to generate the necessary -fonts by hand with Metafont, or to grab them from a CTAN site -(@pxref{unixtex.ftp}). - -@item -There is a bug in the library. @xref{Reporting bugs}. -@end itemize - - -@node Slow path searching -@subsection Slow path searching - -@cindex excessive startup time -@cindex slow startup time -@cindex startup time, excessive - -If your program takes an excessively long time to find fonts or other -input files, but does eventually succeed, here are some possible culprits: - -@itemize @bullet -@item -Most likely, you just have a lot of directories to search, and that -takes a noticeable time. The solution is to create and maintain a -separate @file{ls-R} file that lists all the files in your main @TeX{} -hierarchy. @xref{Filename database}. Kpathsea always uses @file{ls-R} -if it's present; there's no need to recompile or reconfigure any of the -programs. - -@item -Your recursively-searched directories (e.g., -@file{/usr/local/share/texmf/fonts//}), contain a mixture of files and -directories. This prevents Kpathsea from using a useful optimization -(@pxref{Subdirectory expansion}). - -It is best to have only directories (and perhaps a @file{README}) in the -upper levels of the directory structure, and it's very important to have -@emph{only} files, and no subdirectories, in the leaf directories where -the dozens of TFM, PK, or whatever files reside. -@end itemize - -In any case, you may find the debugging options helpful in determining -precisely when the disk or network is being pounded. @xref{Debugging}. - - -@node Unable to generate fonts -@subsection Unable to generate fonts - -@cindex unable to generate fonts -@cindex font generation failures - -Metafont outputs fonts in bitmap format, tuned for a particular -device at a particular resolution, in order to allow for the -highest-possible quality of output. Some DVI-to-whatever programs, -such as Dvips, try to generate these on the fly when they are needed, -but this generation may fail in several cases. - -@cindex @code{mktexpk} can't guess mode -If @code{mktexpk} runs, but fails with this error: -@example -mktexpk: Can't guess mode for @var{nnn} dpi devices. -mktexpk: Use a config file to specify the mode, or update me. -@end example -you need to ensure the resolution and mode match; just -specifying the resolution, as in @code{-D 360}, is not enough. - -You can specify the mode name with the @code{-mode} option on the -Dvips command line, or in a Dvips configuration file (@pxref{Config -files,,, dvips, Dvips}), such as @file{config.ps} in your document -directory, @file{~/.dvipsrc} in your home directory, or in a system -directory (again named @file{config.ps}). (Other drivers use other -files, naturally.) - -For example, if you need 360@dmn{dpi} fonts, you could include this in -a configuration file: -@example -D 360 -M lqmed -@end example - -@cindex Metafont using the wrong device -@cindex device, wrong -If Metafont runs, but generates fonts at the wrong resolution or for -the wrong device, most likely @code{mktexpk}'s built-in guess for the -mode is wrong, and you should override it as above. - -See @url{https://ctan.org/pkg/modes} for a list of resolutions and mode -names for most devices (additional submissions are welcome). - -@flindex .2602gf -@flindex 2602gf -@cindex Metafont making too-large fonts -@cindex proof mode -@cindex online Metafont display, spurious -If Metafont runs but generates fonts at a resolution of 2602@dmn{dpi} -(and prints out the name of each character as well as just a character -number, and maybe tries to display the characters), then your Metafont -base file probably hasn't been made properly. (It's using the default -@code{proof} mode, instead of an actual device mode.) To make a proper -@file{plain.base}, assuming the local mode definitions are contained in -a file @file{modes.mf}, run the following command (assuming Unix): - -@example -inimf "plain; input modes; dump" -@end example - -@noindent -@flindex plain.base -Then copy the @file{plain.base} file from the current directory to where -the base files are stored on your system -(@file{/usr/local/share/texmf/web2c} by default), and make a link -(either hard or soft) from @file{plain.base} to @file{mf.base} in that -directory. -@xref{inimf invocation,,, web2c, Web2c}. - -@cindex Metafont installation -If @code{mf} is a command not found at all by @code{mktexpk}, then you -need to install Metafont (@pxref{unixtex.ftp}). - - -@node TeX or Metafont failing -@subsection @TeX{} or Metafont failing - -@cindex @TeX{} failures -@cindex Metafont failures -@cindex compiler bugs -If @TeX{} or Metafont get a segmentation fault or otherwise fail while -running a normal input file, the problem is usually a compiler bug -(unlikely as that may sound). Even if the trip and trap tests are -passed, problems may lurk. Optimization occasionally causes trouble in -programs other than @TeX{} and Metafont themselves, too. - -@cindex optimization caveat -For a workaround, if you enabled any optimization flags, it's best to -omit optimization entirely. In any case, the way to find the facts is -to run the program under the debugger and see where it's failing. - -@cindex GNU C compiler bugs -@cindex system C compiler bugs -Also, if you have trouble with a system C compiler, I advise trying the -GNU C compiler. And vice versa, unfortunately; but in that case I also -recommend reporting a bug to the GCC mailing list; see @ref{Bugs,,, gcc, -Using and Porting GNU CC}. - -@cindex compiler bugs, finding -To report compiler bugs effectively requires perseverance and -perspicacity: you must find the miscompiled line, and that usually -involves delving backwards in time from the point of error, checking -through @TeX{}'s (or whatever program's) data structures. Good luck. - - -@node Index -@unnumbered Index - -@printindex cp - -@bye diff --git a/Build/source/texk/kpathsea/doc/unixtex.texi b/Build/source/texk/kpathsea/doc/unixtex.texi deleted file mode 100644 index f91f453ce8c..00000000000 --- a/Build/source/texk/kpathsea/doc/unixtex.texi +++ /dev/null @@ -1,50 +0,0 @@ -@ifclear version -@defcodeindex fl -@defcodeindex op -@end ifclear - -@node unixtex.ftp -@chapter @file{unixtex.ftp}: Obtaining @TeX{} - -@cindex obtaining @TeX{} -@cindex retrieving @TeX{} - -@flindex unixtex.ftp -@flindex tug.org -@flindex www.tug.org -@flindex ftp.tug.org -This -@iftex -chapter -@end iftex -is @uref{ftp://tug.org/tex/unixtex.ftp}, a.k.a.@: -@uref{https://tug.org/unixtex.ftp}, last updated 29 February 2020. -Email @email{tex-k@@tug.org} with comments or questions. - -The principal free @TeX{} distribution for Unix-like systems is @TeX{} -Live, on the web at @url{http://tug.org/texlive}. The pages there -describe many ways to acquire and/or build @TeX{}, over the Internet -or on physical media, both the sources and precompiled binaries for -many systems, either standalone or as part of various operating system -distributions. - -Web2c, Kpathsea, Dvips, and Dviljk, among others, are no longer -released as a separate packages. Their sources are now maintained as -part of @TeX{} Live. - -@flindex ftp.cs.stanford.edu -@flindex tex.web -@cindex Knuth, Donald E., archive of programs by -The host @t{ftp.cs.stanford.edu} is the original source for the files -for which Donald Knuth is directly responsible: @file{tex.web}, -@file{plain.tex}, etc. However, unless you want to undertake the -project of building your @TeX{} system from scratch, it is more -reliable and less work to retrieve these files as part of a larger -package. - -In any case, the Stanford ftp site is not the canonical source for -anything except what was created as part of Knuth's original @TeX{}, -so do not rely on any other files available there being up-to-date. -The best place to check for up-to-date files is CTAN (the -Comprehensive @TeX{} Archive Network), @url{https://ctan.org}. - |