diff options
author | Peter Breitenlohner <peb@mppmu.mpg.de> | 2009-03-20 09:22:53 +0000 |
---|---|---|
committer | Peter Breitenlohner <peb@mppmu.mpg.de> | 2009-03-20 09:22:53 +0000 |
commit | 34720aca96718a0d370b50dfbc3726a3367f4f49 (patch) | |
tree | 95cd3c3eee204aa71840c35a661801c87c4c7b31 /Build/source/texk/kpathsea/doc | |
parent | 298c183c634c96bfde3fad20b8e7ec16268dd1d8 (diff) |
new build system
git-svn-id: svn://tug.org/texlive/trunk@12454 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/kpathsea/doc')
-rw-r--r-- | Build/source/texk/kpathsea/doc/Makefile.am | 9 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/Makefile.in | 587 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/bugs.texi | 901 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/hier.texi | 102 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/install.texi | 1239 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/kpathsea.texi | 2455 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/unixtex.ftp | 151 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/unixtex.texi | 286 |
8 files changed, 5730 insertions, 0 deletions
diff --git a/Build/source/texk/kpathsea/doc/Makefile.am b/Build/source/texk/kpathsea/doc/Makefile.am new file mode 100644 index 00000000000..daeaf375f4b --- /dev/null +++ b/Build/source/texk/kpathsea/doc/Makefile.am @@ -0,0 +1,9 @@ +## +EXTRA_DIST = unixtex.ftp + +DISTCLEANFILES = $(DVIS) $(PSS) + +## The info files +info_TEXINFOS = kpathsea.texi +kpathsea_TEXINFOS = bugs.texi hier.texi install.texi unixtex.texi + diff --git a/Build/source/texk/kpathsea/doc/Makefile.in b/Build/source/texk/kpathsea/doc/Makefile.in new file mode 100644 index 00000000000..2aa2e85e4f6 --- /dev/null +++ b/Build/source/texk/kpathsea/doc/Makefile.in @@ -0,0 +1,587 @@ +# Makefile.in generated by automake 1.10.2 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008 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@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@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 +DIST_COMMON = $(kpathsea_TEXINFOS) $(srcdir)/Makefile.am \ + $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/../../m4/kpse-common.m4 \ + $(top_srcdir)/../../m4/kpse-web2c.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)/ac/web2c.ac $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/c-auto.h +CONFIG_CLEAN_FILES = +SOURCES = +DIST_SOURCES = +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__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 = `echo $$p | sed -e 's|^.*/||'`; +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AR = @AR@ +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@ +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_VERSNUM = @KPSE_LT_VERSNUM@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +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_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +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@ +lt_ECHO = @lt_ECHO@ +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@ +EXTRA_DIST = unixtex.ftp +DISTCLEANFILES = $(DVIS) $(PSS) +info_TEXINFOS = kpathsea.texi +kpathsea_TEXINFOS = bugs.texi hier.texi install.texi 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'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --foreign doc/Makefile +.PRECIOUS: 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__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + 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 + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs + +.texi.info: + restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && 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; \ + cd $(srcdir); \ + else \ + rc=$$?; \ + cd $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $< + +.texi.pdf: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $< + +.texi.html: + rm -rf $(@:.html=.htp) + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@; \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ + else \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ + 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: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; for p in $$list; do \ + f=$(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)' && \ + (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; 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'"; \ + install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + 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)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; for p in $$list; do \ + f=$(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.aux kpathsea.cm kpathsea.cp kpathsea.cps kpathsea.fl \ + kpathsea.fn kpathsea.ky kpathsea.log kpathsea.op kpathsea.pg \ + kpathsea.tmp kpathsea.toc kpathsea.tp kpathsea.vr \ + 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 +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(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 $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$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: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES) + +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-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) + test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" + @list='$(DVIS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/$$f"; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" + @list='$(HTMLS)'; for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + if test -d "$$d$$p"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \ + else \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \ + fi; \ + done +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + 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 \ + relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ + echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ + $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + 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) + test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" + @list='$(PDFS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \ + done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" + @list='$(PSS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(psdir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(psdir)/$$f"; \ + 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-generic clean-libtool \ + 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 \ + uninstall uninstall-am uninstall-dvi-am uninstall-html-am \ + uninstall-info-am uninstall-pdf-am uninstall-ps-am + +# 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/bugs.texi b/Build/source/texk/kpathsea/doc/bugs.texi new file mode 100644 index 00000000000..4ec2d560a57 --- /dev/null +++ b/Build/source/texk/kpathsea/doc/bugs.texi @@ -0,0 +1,901 @@ +@ifclear version +@defcodeindex fl +@defcodeindex op +@end ifclear + +@node Reporting bugs +@section Reporting bugs + +@cindex reporting bugs +@cindex bugs, reporting + +@ifset version +(A copy of this chapter is in the file @file{kpathsea/BUGS}.) +@end ifset + +@flindex tex-k@@mail.tug.org @r{(bug address)} +@cindex bug address +If you have problems or suggestions, please report them to +@email{tex-k@@mail.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 +@subsection 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@@mail.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 number), compiler, and +@code{make} program you are using (the output of @code{uname -a} is a +start on the first two, though often incomplete). If the bug involves +the X window system, include X version and supplier information as well +(examples: X11R6 from MIT; X11R4 from HP; OpenWindows 3.3 bundled with +SunOS 4.1.4). + +@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 necessary, 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, available from @url{ftp://prep.ai.mit.edu/pub/gnu}). 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 +@subsection Mailing lists + +@cindex mailing lists +@cindex bug mailing list +@cindex announcement mailing list + +Web2c and Kpathsea in general are discussed on the mailing list +@email{tex-k@@mail.tug.org}. +@flindex tex-k-request@@mail.tug.org +To join, email @email{tex-k-request@@mail.tug.org} with a line +consisting of + +@example +subscribe @var{you}@@@var{your.preferred.email.address} +@end example + +@noindent in the body of the message. + +You do not need to join to submit a report, nor will it affect whether +you get a response. There is no Usenet newsgroup equivalent (if you can +be the one to set this up, email @samp{tex-k-request}). Traffic on the +list is fairly light, and is mainly bug reports and enhancement requests +to the software. The best way to decide if you want to join or not is +read some of the archives from @url{ftp://ftp.tug.org/mail/archives/tex-k/}. + +Be aware that large data files are sometimes included in bug reports. +If this is a problem for you, do not join the list. + +@flindex tex-archive@@math.utah.edu +@cindex announcement mailing list +If you only want announcements of new releases, not bug reports and +discussion, join @email{tex-archive@@math.utah.edu} (via mail to +@email{tex-archive-request@@math.utah.edu}). + +@cindex @TeX{} help mailing list +@cindex La@TeX{} help mailing list +@cindex Usenet @TeX{} newsgroup +@cindex newsgroup for @TeX{} +@cindex help, mailing list for general @TeX{} +@flindex info-tex@@shsu.edu +@flindex comp.text.tex +If you are looking for general @TeX{} help, such as how to use La@TeX{}, +please use the mailing list @email{info-tex@@shsu.edu} mailing list, +which is gatewayed to the @samp{comp.text.tex} Usenet newsgroup (or post +to the newsgroup; the gateway is bidirectional). + + +@node Debugging +@subsection Debugging + +@cindex debugging +@cindex runtime debugging +@cindex options for debugging + +@vindex kpathsea_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 kpathsea_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 variable @code{kpathsea_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 can @emph{not} use the @emph{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 +@subsection 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 +@subsection 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. + +* Empty Makefiles:: When configure produces empty makefiles. +* XtStrings:: When _XtStrings is undefined. +* dlopen:: When dlopen is undefined. +* ShellWidgetClass:: For dynamic linking troubles under OpenWindows. +* Pointer combination warnings:: For old compilers that don't grok char *. +@end menu + +@node Unable to find files +@subsubsection 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 +@subsubsection 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 +@subsubsection 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{ftp://ftp.tug.org/tex/modes.mf} 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 +@subsubsection @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. + +Insufficient swap space may also cause core dumps or other erratic +behavior. + +@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. Things are +not helped by all-too-common bugs in the debugger itself. Good luck. + +@cindex ANSI C +@cindex HP-UX, compiling on +@cindex compiling on HP-UX +One known cause of trouble is the way arrays are handled. Some of the +Pascal arrays have a lower index other than 0, and the C code will take +the pointer to the allocated memory, subtract the lower index, and use +the resulting pointer for the array. While this trick often works, ANSI +C doesn't guarantee that it will. It it known to fail on HP-UX 10 +mchines when the native compiler is used, unless the @samp{+u} compiler +switch was specified. Using GCC will work on this platform as well. + +@node Empty Makefiles +@subsubsection Empty Makefiles + +@cindex Makefiles, empty +@pindex sed @r{error from @code{configure}} +@pindex configure @r{error from @code{sed}} +@cindex NetBSD @code{configure} error +@cindex FreeBSD @code{configure} error +@cindex Mach10 @code{configure} error +@cindex AIX 4.1 @code{configure} error +@cindex NeXT @code{sed} error + +On some systems (NetBSD, FreeBSD, AIX 4.1, and Mach10), @code{configure} +may fail to properly create the Makefiles. Instead, you get an error +which looks something like this: + +@example +prompt$ ./configure +@dots{} +creating Makefile +sed: 1: "\\@@^ac_include make/pat ...": \ can not be used as a string delimiter +@end example + +So far as I know, the bug here is in @code{/bin/sh} on these systems. I +don't have access to a machine running any of them, so if someone can +find a workaround that avoids the quoting bug, I'd be most +grateful. (Search for @code{ac_include} in the @code{configure} script +to get to the problematic code.) + +It should work to run @code{bash configure}, instead of using +@code{/bin/sh}. You can get Bash from +@url{ftp://prep.ai.mit.edu/pub/gnu} and mirrors. + +Another possible cause (reported for NeXT) is a bug in the @code{sed} +command. In that case the error may look like this: + +@example +Unrecognized command: \@@^ac_include make/paths.make@@r make/paths.make +@end example + +In this case, installing GNU @code{sed} should solve the problem. You +can get GNU @code{sed} from the same places as Bash. + +@ignore +@node wchar_t +@subsubsection @code{wchar_t} + +@vindex FOIL_X_WCHAR_T +@tindex wchar_t + +The upshot of all the following is that if you get error messages +regarding @code{wchar_t}, try defining @code{NO_FOIL_X_WCHAR_T} (for +Web2c) or @code{FOIL_X_WCHAR_T} (for everything else), as in: + +@example +make XCFLAGS=-DNO_FOIL_X_WCHAR_T @var{other-make-options} +@end example + +@flindex Xlib.h +@flindex stddef.h +@code{wchar_t} has caused infinite trouble. None of my code ever uses +@code{wchar_t}; all I want to do is include X header files and various +system header files, possibly compiling with GCC. This seems an +impossible task! The basic problem is that the X11 header +@file{<Xlib.h>} and GCC's @file{<stddef.h>} have conflicting definitions +for @code{wchar_t}. + +The particulars: @file{<X11/Xlib.h>} from MIT X11R5 defines +@code{wchar_t} if @code{X_WCHAR} is defined, which is defined if +@code{X_NOT_STDC_ENV} is defined, and we define @emph{that} if +@code{STDC_HEADERS} is not defined (@samp{configure} decides if +@code{STDC_HEADERS} gets defined). But when compiling with GCC on SunOS +4.1.x, @code{STDC_HEADERS} is not defined (@file{string.h} doesn't +declare the @samp{mem}* functions), so we do get X's +@code{wchar_t}---and we also get GCC's @code{wchar_t} from its +@file{<stddef.h>}. Conflict. + +On the other hand, SunOS 4.1.1 with some other X configurations actually +needs GCC to define @code{wchar_t}, and fails otherwise. + +My current theory is to define @code{wchar_t} to a nonsense symbol +before the X include files are read; that way its definition (if any) +will be ignored by other system include files. Going along with that, +define @code{X_WCHAR} to tell X not to use @file{<stddef.h>}, that we've +already included, but instead to make its own definition. + +But this is not the end of the story. The X11 include files distributed +with DG/UX 5.4.2 for the Aviion have been modified to include +@file{<_int_wchar_t.h>} if @code{X_WCHAR}, so our @code{#define} will +not have any typedef to change---but the uses of @code{wchar_t} in the X +include files will be changed to reference this undefined symbol. So +there's nothing to foil in this case. I don't know how to detect this +automatically, so it's up to you to define @code{NO_FOIL_X_WCHAR_T} +yourself. +@end ignore + +@node XtStrings +@subsubsection @code{XtStrings} + +@findex XtStrings +You may find that linking X programs results in an error from the linker +that @samp{XtStrings} is undefined, something like this: + +@example +gcc -o virmf @dots{} +@dots{}/x11.c:130: undefined reference to `XtStrings' +@end example + +This generally happens because of a mismatch between the X include files +with which you compiled and the X libraries with which you linked; +often, the include files are from MIT and the libraries from Sun. + +The solution is to use the same X distribution for compilation and +linking. Probably @samp{configure} was unable to guess the proper +directories from your installation. You can use the @code{configure} +options @samp{--x-includes=@var{path}} and +@samp{--x-libraries=@var{path}} to explicitly specify them. + + +@node dlopen +@subsubsection @code{dlopen} + +@cindex static linking and @code{dlsym} +@flindex dlopen +@flindex dlsym +@flindex dlclose +@flindex wcstombs +@flindex libdl.a +(This section adapted from the file @file{dlsym.c} in the X distribution.) + +The @code{Xlib} library uses the standard C function @code{wcstombs}. +Under SunOS 4.1, @code{wcstombs} uses the @samp{dlsym} interface defined +in @file{libdl.so}. Unfortunately, the SunOS 4.1 distribution does not +include a static @samp{libdl.a} library. + +As a result, if you try to link an X program statically under SunOS, you +may get undefined references to @code{dlopen}, @code{dlsym}, and +@code{dlclose}. One workaround is to include these definitions +when you link: + +@example +void *dlopen() @{ return 0; @} +void *dlsym() @{ return 0; @} +int dlclose() @{ return -1; @} +@end example + +@flindex dlsym.c +@noindent These are contained in the @file{dlsym.c} file in the MIT X +distribution. + + +@node ShellWidgetClass +@subsubsection @code{ShellWidgetClass} + +@cindex dynamic linking problems with OpenWin libraries +@cindex OpenWin libraries, dynamic linking problems +@findex get_wmShellWidgetClass +@findex get_applicationShellWidgetClass + +@flindex comp.sys.sun.admin @r{FAQ} +@cindex FAQ, @t{comp.sys.sun.admin} +(This section adapted from the @t{comp.sys.sun.admin} FAQ.) + +If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x, you +may get undefined symbols @code{_get_wmShellWidgetClass} and +@code{_get_applicationShellWidgetClass} when linking. This problem does +not arise using the standard MIT X libraries under SunOS. + +@findex Xmu @r{library problems} +The cause is bugs in the @code{Xmu} shared library as shipped from Sun. +There are several fixes: + +@itemize @bullet + +@item Install the free MIT distribution from @samp{ftp.x.org} and mirrors. + +@item Get the OpenWindows patches listed below. + +@item Statically link the @code{Xmu} library into the executable. + +@item Avoid using @code{Xmu} at all. If you are compiling +Metafont, see @ref{Online Metafont graphics,,, web2c, Web2c}. If you are +compiling Xdvi, see the @code{-DNOTOOL} option in @file{xdvik/INSTALL}. + +@item Ignore the errors. The binary runs fine regardless. + +@end itemize + +@cindex Sun OpenWin patches +@cindex patches, Sun OpenWin +Here is the information for getting the two patches: + +@display +Patch ID: 100512-02 +Bug ID's: 1086793, 1086912, 1074766 +Description: 4.1.x OpenWindows 3.0 @code{libXt} jumbo patch + +Patch ID: 100573-03 +Bug ID: 1087332 +Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared @code{libXmu}. +@end display + +@cindex static linking +The way to statically link with @code{libXmu} depends on whether you are +using a Sun compiler (e.g., @code{cc}) or @code{gcc}. If the latter, +alter the @code{x_libs} Make variable to include + +@opindex -static +@opindex -dynamic +@example +-static -lXmu -dynamic +@end example + +@opindex -Bstatic +@opindex -Bdynamic +If you are using the Sun compiler, use @samp{-Bstatic} and @samp{-Bdynamic}. + + +@node Pointer combination warnings +@subsubsection Pointer combination warnings + +@cindex warnings, pointer combinations +@cindex pointer combination warnings +@cindex illegal pointer combination warnings +@pindex cc @r{warnings} +When compiling with old C compilers, you may get some warnings about +``illegal pointer combinations''. These are spurious; just ignore them. +I decline to clutter up the source with casts to get rid of them. + +@c This isn't worth including any more, OSF 1.x is too old. +@c The other XtInherit problem (R4 Xlib on Suns) should never come up, +@c but the answer from the X faq is included anyway. +@c +@c @node XtInherit +@c @subsubsection @code{XtInherit} +@c +@c @findex XtInherit @r{bug on OSF/1} +@c @cindex OSF/1 loader bug and @code{XtInherit} +@c @cindex Alpha OSF/1 loader bug and @code{XtInherit} +@c +@c On DEC OSF/1 1.x systems, the loader has a bug that manifests itself in +@c the following error (all on one line, but for the sake of the paper +@c width it's broken here): +@c +@c @example +@c xdvik/xdvi: /sbin/loader: Fatal Error: search_for_undefineds: +@c symbol _XtInherit should not have any relocation entry +@c @end example +@c +@c @noindent According to Michael Rickabaugh @code{<mjr@@quarry.enet.dec.com>}: +@c +@c @quotation +@c This is a bug fixed in DEC OSF/1 2.0. +@c +@c If you know how, installing @file{/sbin/loader} from a 2.0 system onto a +@c 1.3 system will work. Make sure that @file{/usr} is @emph{not} mounted +@c when you do this. (If you forget about umounting @code{/usr}, it is +@c possible most of your filesystems will become corrupted.) +@c +@c Otherwise, I suggest getting a later CD and running +@c @file{/usr/sbin/installupdate}. +@c @end quotation +@c +@c Alternatively, you may be able to use the freely available X11 libraries +@c that come with the MIT distribution (on @file{ftp.x.org}, for example). +@c +@c Linking statically, perhaps only with some of the X libraries, may also +@c work. +@c +@c The Sun XtInherit weirdness, from the comp.windows.x FAQ: +@c Subject: 126)! What are these problems with "*_XtInherit* not found" on the Sun? +@c When I link a X program that I wrote on a SunOS 4.0.3 or 4.1 machine I get the +@c error "ld.so: symbol not found *_XtInherit*". +@c +@c What you are seeing is a side-effect of a kludge in the R4 libXt.a to +@c get Sun shared libraries working. Apparently, you can't share a function that +@c is both called and compared, as *_XtInherit* is. This was handled by putting +@c *_XtInherit* in the same file as a function that is always used, thereby +@c guaranteeing that it would be loaded -- that is, in Initialize.c, where +@c XtToolkitInitialize() and XtInitialize() reside. These routines would normally +@c be called. +@c +@c You are probably seeing this error because your program is not a normal +@c Xt-based program and does not call XtToolkitInitialize() anywhere. +@c 1) it may be a program that uses Xt functions but never opens a +@c connection to the X server. [OSF/Motif's 1.1.0 UIL had this problem; it called +@c XtMalloc() and other Xt functions.] The solution is to add the call to your +@c program; the function does not have to be executed, just linked in. +@c 2) alternatively, your program doesn't need any Xt functions and is +@c correct in not calling XtToolkitInitialize() -- it may be an Xlib or XView +@c program. In this case, you can remove -lXt from your link command. +@c +@c It should not be necessary to link the shared libraries statically, +@c although this will certainly solve the problem. + +@c * Empty Makefiles:: If configure gives you sed errors. +@c * wchar_t:: For wchar_t difficulties. diff --git a/Build/source/texk/kpathsea/doc/hier.texi b/Build/source/texk/kpathsea/doc/hier.texi new file mode 100644 index 00000000000..007be809140 --- /dev/null +++ b/Build/source/texk/kpathsea/doc/hier.texi @@ -0,0 +1,102 @@ +@ifclear version +@defcodeindex fl +@defcodeindex op +@end ifclear + +@node TeX directory structure +@section @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 standard is available +as @url{ftp://prep.ai.mit.edu/pub/gnu/standards/standards.texi} and +mirrors. The TDS document is available from +@file{@var{CTAN:}/tex-archive/tds} (@pxref{unixtex.ftp}). + +You can change the default paths in many ways (@pxref{Changing search +paths}). One common desire is to put everything (binaries and all) +under a single top-level directory such as @file{/usr/local/texmf} or +@file{/opt/texmf}---in the terms used below, make @var{prefix} and +@var{texmf} the same. For specific instructions on doing that, +see @ref{configure scenarios}. + +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 diff --git a/Build/source/texk/kpathsea/doc/install.texi b/Build/source/texk/kpathsea/doc/install.texi new file mode 100644 index 00000000000..67e82a8acd1 --- /dev/null +++ b/Build/source/texk/kpathsea/doc/install.texi @@ -0,0 +1,1239 @@ +@ifclear version +@defcodeindex cm +@defcodeindex fl +@defcodeindex op +@end ifclear + +@node Installation +@chapter Installation + +@cindex installation +@cindex configuration +@cindex compilation + +@ifset version +(A copy of this chapter is in the distribution file @file{kpathsea/INSTALL}.) +@end ifset + +The procedure for Kpathsea (and Web2c, etc.) configuration and +installation follows. If you encounter trouble, see @ref{Common +problems}, a copy of which is in the file @file{kpathsea/BUGS}. + +@menu +* Simple installation:: If you just want to do it. +* Custom installation:: If you want to change things around. +* Security:: Who can write what files, etc. +* TeX directory structure:: Managing the horde of TeX input files. +* unixtex.ftp:: Getting software via FTP, on CD-ROM, or on tape. +* Reporting bugs:: Where and how to report bugs. +@end menu + + +@node Simple installation +@section Simple installation + +@cindex simple installation +@cindex installation, simple + +@cindex precompiled executables, instead of installation +@cindex installation, getting executables instead of +Installing @TeX{} and friends for the first time can be a daunting +experience. Thus, you may prefer to skip this whole thing and just get +precompiled executables: see @ref{unixtex.ftp}. + +This section explains what to do if you wish to take the defaults for +everything, and generally to install in the simplest possible way. Most +steps here refer to corresponding subsection in the next section which +explains how to override defaults and generally gives more details. + +By default everything will be installed under @file{/usr/local} and the +following discussion assumes this. However, if you already have @TeX{} +installed, its location is used to derive the directory under which +everything is to be installed. + +@enumerate +@item +Be sure you have enough disk space: approximately 8 megabytes for the +compressed archives, 15MB for sources, 50MB for compilation, 40MB for +the (initial) installed system (including library files). @xref{Disk +space}. + +@item +Retrieve these distribution archives: +@table @url +@item ftp://ftp.tug.org/tex/texk.tar.gz +These are the sources, which you will be compiling. + +@item ftp://ftp.tug.org/tex/texklib.tar.gz +This is a basic set of input files. You should unpack it in the +directory @file{/usr/local/share}; doing so will create a @file{texmf} +subdirectory there. +@end table + +These archives are mirrored on the CTAN hosts, in the +@file{systems/web2c} directory. + +@noindent @xref{Kpathsea application distributions}. + +@item +When using the default search paths, there is no need to edit any +distribution files. @xref{Changing search paths}. + +@item +At the top level of the distribution, run @samp{sh configure}. (If you +have the GNU Bash shell installed, run @samp{bash configure}.) +@xref{Running configure}. + +@item +@samp{make}. @xref{Running make}. If you are using a BSD 4.4 system +such as FreeBSD or NetBSD, you may have to use GNU make (often installed +in @file{/usr/local/bin}), not the BSD make. + +@item +@samp{make install}. @xref{Installing files}. + +@item +@samp{make distclean}. @xref{Cleaning up}. + +@item +Set up a cron job to rebuild the filename database that makes searching +faster. This line will rebuild it every midnight: +@example +0 0 * * * cd /usr/local/share/texmf && @var{/bindir}/mktexlsr +@end example +@xref{Filename database generation}, and @ref{Filename database}. + +@item +@cindex printer configuration files +@cindex PostScript fonts, additional +@cindex color printers, configuring +If you're installing Dvips, you also need to set up configuration files +for your printers and make any additional PostScript fonts available. +@xref{Installation,,, dvips, Dvips}. If you have any color printers, +see @ref{Color device configuration,,, dvips, Dvips}. + +@item +The first time you run a DVI driver, a bunch of PK fonts will be built +by Metafont via @code{mktexpk} (and added to the filename database). +This will take some time. Don't be alarmed; they will created only this +first time (unless something is wrong with your path definitions). + +By default, @code{mktexpk} will create these fonts in a hierarchy +under @file{/var/tmp/texfonts}; it simply assumes that @file{/var/tmp} +exists and is globally writable. If you need a different arrangement, +see @ref{mktex configuration}. + +@xref{mktex scripts}. + +@item +@cindex fonts, being created +@pindex mktexpk @r{, initial runs} +@cindex tests, simple +For some simple tests, try @samp{tex story \\bye} and @samp{latex +sample2e}. Then run @file{xdvi story} or @file{dvips sample2e} on the +resulting DVI files to preview/print the documents. @xref{Installation +testing}. +@end enumerate + + +@node Custom installation +@section Custom installation + +@cindex custom installation +@cindex installation, customized + +Most sites need to modify the default installation procedure in some +way, perhaps merely changing the prefix from @samp{/usr/local}, perhaps +adding extra compiler or loader options to work around @code{configure} +bugs. This section explains how to override default choices. For +additional distribution-specific information: +@itemize @bullet +@item @file{dviljk/INSTALL}. +@item @xref{Installation,,,dvips,Dvips}. +@item @xref{Installation,,,web2c,Web2c}. +@item @file{xdvik/INSTALL}. +@end itemize + +@cindex non-Unix operating systems +@cindex Amiga support +@cindex DOS support +@cindex OS/2 support +@cindex VMS support +These instructions are for Unix systems. Other operating-system +specific distributions have their own instructions. The code base +itself supports Amiga, DOS, OS/2, and VMS. + + +Following are the same steps as in the previous section (which describes +the simplest installation), but with much more detail. + +@menu +* Disk space:: +* Kpathsea application distributions:: +* Changing search paths:: +* Running configure:: +* Running make:: +* Installing files:: +* Cleaning up:: +* Filename database generation:: +* mktex scripts:: +* Installation testing:: +@end menu + + +@node Disk space +@subsection Disk space + +@cindex disk space, needed +@cindex total disk space +@cindex size of distribution archives +Here is a table showing the disk space needed for each distribution +(described in the next section). The `(totals)' line reflects the +@samp{texk} source distribution and @samp{texklib}; the individual +distributions don't enter into it. Sizes are in megabytes. All numbers +are approximate. + +@multitable {distribution} {.tar.gz} {unpacked} {compiled} {installed} +@item Distribution @tab .tar.gz @tab Unpacked @tab Compiled @tab Installed +@item dviljk @tab .9 @tab 3.8 @tab +@item dvipsk @tab .9 @tab 3.2 @tab +@item xdvik @tab .7 @tab 2.5 @tab +@item web2c @tab 1.3 @tab 5.0 @tab +@item web @tab 1.9 @tab 6.5 @tab - @tab - +@item texk @tab 7.5 @tab 32.1 @tab 95.3 @tab 33.5 +@item texklib @tab 6.3 @tab 15.0 @tab - @tab 15.0 +@item (totals) @tab 14.6 @tab 47.1 @tab 95.3 @tab 48.5 +@end multitable + + +@node Kpathsea application distributions +@subsection Kpathsea application distributions + +@cindex distributions, compiling simultaneously +@cindex version number, of Kpathsea +@cindex Kpathsea version number + +@cindex distributions, not compiling +@cindex NeXT, lacking X11 +@cindex X11, lacking on NeXT +The archive @url{ftp://ftp.tug.org/tex/texk.tar.gz} contains all of the +Kpathsea applications I maintain, and the library itself. For example, +since NeXT does not generally support X11, you'd probably want to skip +@samp{xdvik} (or simply remove it after unpacking @file{texk.tar.gz}. +If you are not interested in all of them, you can also retrieve them +separately: + +@cindex DVI drivers +@table @file +@item dviljk.tar.gz +@cindex PCL driver +@cindex LaserJet drive +DVI to PCL, for LaserJet printers. + +@item dvipsk.tar.gz +@cindex PDF generation +@cindex PostScript driver +DVI to PostScript, for previewers, printers, or PDF generation. + +@item web2c.tar.gz +The software needed to compile @TeX{} and friends. + +@item web.tar.gz +The original WEB source files, also used in compilation. + +@item xdvik.tar.gz +@cindex X11 previewer +DVI previewing under the X window system. + +@end table + +@cindex Babel +@cindex non-English typesetting +If you want to use the Babel La@TeX{} package for support of non-English +typesetting, you may need to retrieve additional files. See the file +@file{install.txt} in the Babel distribution. + + +@node Changing search paths +@subsection Changing search paths + +@cindex search paths, changing default +@cindex paths, changing default +@flindex texmf.in@r{, editing} +If the search paths for your installation differ from the standard +@TeX{} directory structure (@pxref{Top,, Introduction, tds, A Directory +Structure for @TeX{} files}), edit the file @file{kpathsea/texmf.in} +as desired, before running @code{configure}. For example, if you have +all your fonts or macros in one big directory. + +You may also wish to edit the file @file{mktex.cnf}, either before or +after installation, to control various aspects of @code{mktexpk} and +friends. @xref{mktex configuration}. + +You do not need to edit @file{texmf.in} to change the default +top-level or other installation @emph{directories} (only the paths). +You can and should do that when you run @code{configure} (next step). + +You also do not need to edit @file{texmf.in} if you are willing to +rely on @file{texmf.cnf} at runtime to define the paths, and let the +compile-time default paths be incorrect. Usually there is no harm in +doing this. + +The section below explains default generation in more detail. + +@menu +* Default path features:: +* Default path generation:: +@end menu + + +@node Default path features +@subsubsection Default path features + +@cindex default path features +@cindex features, of default paths + +The purpose of having all the different files described in the section +above is to avoid having the same information in more than one place. If +you change the installation directories or top-level prefix at +@code{configure}-time, those changes will propagate through the whole +sequence. And if you change the default paths in @file{texmf.in}, +those changes are propagated to the compile-time defaults. + +The Make definitions are all repeated in several @t{Makefile}'s; but +changing the top-level @file{Makefile} should suffice, as it passes down +all the variable definitions, thus overriding the submakes. (The +definitions are repeated so you can run Make in the subdirectories, if +you should have occasion to.) + +@vindex MAKETEX_MODE +@cindex paths, device name included in +By default, the bitmap font paths end with @samp{/$MAKETEX_MODE}, thus +including the device name (usually a Metafont mode name such as +@samp{ljfour}). This distinguishes two different devices with the same +resolution---a write/white from a write/black 300@dmn{dpi} printer, for +example. + +@findex kpse_init_prog@r{, and @code{MAKETEX_MODE}} +@flindex proginit.c +However, since most sites don't have this complication, Kpathsea +(specifically, the @code{kpse_init_prog} function in +@file{kpathsea/proginit.c}) has a special case: if the mode has not been +explicitly set by the user (or in a configuration file), it sets +@code{MAKETEX_MODE} to @code{/}. This makes the default PK path, for +example, expand into @code{@dots{}/pk//}, so fonts will be found even if +there is no subdirectory for the mode (if you arranged things that way +because your site has only one printer, for example) or if the program +is mode-independent (e.g., @code{pktype}). + +To make the paths independent of the mode, simply edit +@file{texmf.in} before installation, or the installed +@file{texmf.cnf}, and remove the @samp{$MAKETEX_MODE}. + +@xref{mktex script arguments}, for how this interacts with @code{mktexpk}. + +@flindex HIER +@flindex kpathsea/HIER +@xref{TeX directory structure,, @TeX{} directory structure}, for a +description of the default arrangement of the input files that comprise +the @TeX{} system. The file @file{kpathsea/HIER} is a copy of that +section. + + +@node Default path generation +@subsubsection Default path generation + +@cindex default paths, changing +@cindex paths, changing default +@cindex installation, changing default directories +@cindex directories, changing default installation + +This section describes how the default paths are constructed. + +You may wish to ignore the whole mess and simply edit @file{texmf.cnf} +after it is installed, perhaps even copying it into place beforehand so +you can complete the installation, if it seems necessary. + +@cindex default paths, how they're made +To summarize the chain of events that go into defining the default paths: + +@enumerate +@item +@samp{configure} creates a @file{Makefile} from each @file{Makefile.in}. + +@item +@flindex texmf.sed +When Make runs in the @file{kpathsea} directory, it creates a file +@file{texmf.sed} that substitutes the Make value of @code{$(var)} for a +string @code{@@var@@}. The variables in question are the one that +define the installation directories. + +@item +@flindex texmf.in +@flindex texmf.cnf@r{, generated} +@file{texmf.sed} (together with a little extra magic---see +@file{kpathsea/Makefile}) is applied to @file{texmf.in} to generate +@file{texmf.cnf}. This is the file that will eventually be installed +and used. + +@item +@flindex paths.h +The definitions in @file{texmf.cnf} are recast as C @code{#define}'s in +@file{paths.h}. These values will be the compile-time defaults; they +are not used at runtime unless no @file{texmf.cnf} file can be found. + +(That's a lie: the compile-time defaults are what any extra @t{:}'s in +@file{texmf.cnf} expand into; but the paths as distributed have no extra +@t{:}'s, and there's no particular reason for them to.) +@end enumerate + + +@node Running configure +@subsection Running @code{configure} + +@flindex configure@r{, running} +@flindex c-auto.in +@flindex Makefile.in +@findex ac_include@r{, Autoconf extension} +@cindex @@@var{var}@@ substitutions +@cindex system dependencies +Run @code{sh configure @var{options}} (in the top-level directory, the +one containing @file{kpathsea/}), possibly using a shell other than +@code{sh} (@pxref{configure shells}). + +@code{configure} adapts the source distribution to the present system +via @code{#define}'s in @file{*/c-auto.h}, which are created from the +corresponding @file{c-auto.in}. It also creates a @file{Makefile} from +the corresponding @file{Makefile.in}, doing @samp{@@@var{var}@@} and +@samp{ac_include} substitutions). + +@flindex README.CONFIGURE +@flindex kpathsea/README.CONFIGURE +@code{configure} is the best place to control the configuration, +compilation, and installed location of the software, either via +command-line options, or by setting environment variables before +invoking it. For example, you can disable @code{mktexpk} by default +with the option @samp{--disable-mktexpk}. +@xref{configure options}. + +@menu +* configure shells:: +* configure options:: +* configure environment:: +* configure scenarios:: +* Shared library:: +@end menu + + +@node configure shells +@subsubsection @code{configure} shells + +@cindex shells and @code{configure} +@pindex bash@r{, recommended for running @code{configure}} + +Considerable effort has gone into trying to ensure that the +@code{configure} scripts can be run by most Bourne shell variants. +If @code{sh} runs into trouble, your best bet is to use Bash, the GNU +Bourne-again shell (@pxref{Top,,,bash,Bash Reference Manual}). + +Bourne shell variants for which problems have been reported in the past +are: +@table @code +@item ksh +@pindex ksh@r{, losing with @code{configure}} +@pindex bsh@r{, ok with @code{configure}} +@cindex Korn shell@r{, losing with @code{configure}} +@cindex AIX shells and @code{configure} +Old versions of the Korn shell may fail to handle the scripts. The Korn +shell may be installed as @file{/bin/sh} on AIX, in which case +@file{/bin/bsh} may serve instead. + +@item ash +@pindex ash@r{, losing with @code{configure}} +@cindex NetBSD shells and @code{configure} +@cindex FreeBSD shells and @code{configure} +@cindex Linux shells and @code{configure} +Old versions of ash are unable to handle the scripts. Ash is sometimes +installed as @file{/bin/sh} on NetBSD, FreeBSD, and Linux systems. +@file{/bin/bash} should be available for those systems, but might not be +part of a default installation. + +@item @r{Ultrix} /bin/sh +@cindex DEC shells and @code{configure} +@cindex Ultrix shells and @code{configure} +@pindex sh5@r{, ok with @code{configure}} +@file{/bin/sh} under Ultrix is a DEC-grown shell that is notably +deficient in many ways. @file{/bin/sh5} may be necessary. +@end table + + +@node configure options +@subsubsection @code{configure} options + +@cindex @code{configure} options + +For a complete list of all @code{configure} options, run @samp{configure +--help} or see @ref{Invoking configure,, Running @code{configure} scripts, +autoconf, Autoconf}, (a copy is in the file @file{kpathsea/README.CONFIGURE}). +The generic options are listed first in the @samp{--help} output, and +the package-specific options come last. The environment variables +@code{configure} pays attention to are listed below. + +Options particularly likely to be useful are @samp{--prefix}, +@samp{--datadir}, and the like; see @ref{configure scenarios}. + +@opindex --with @r{options} +@opindex --enable @r{options} +@cindex configuration of optional features +@cindex options to @code{configure} +This section gives pointers to descriptions of the @samp{--with} and +@samp{--enable} options to @code{configure} that Kpathsea-using programs +accept. + +@table @samp +@item --without-mktexmf-default +@itemx --without-mktexpk-default +@itemx --without-mktextfm-default +@itemx --with-mktextex-default +Enable or disable the dynamic generation programs. @xref{mktex +configuration}. + +@item --enable-shared +@opindex --enable-shared +Build Kpathsea as a shared library, and link against it. Also build the +usual static library. @xref{Shared library}. + +@item --disable-static +@opindex --disable-static +Build only the shared library. Implies @samp{--enable-shared}. + +@item --enable-maintainer-mode +@opindex --enable-maintainer-mode +Enables make targets that are useful for the maintainer and likely to be +a pain for anyone else; the makefiles created when this option is +enabled may not work at all for you. You have been warned. +@end table + +@node configure environment +@subsubsection @code{configure} environment + +@code{configure} uses the value of the following environment variables in +determining your system's characteristics, and substitutes for them in +@t{Makefile}'s: + +@vtable @samp +@item CC +@pindex gcc@r{, compiling with} +@pindex cc@r{, compiling with} +The compiler to use: default is @code{gcc} if it's installed, otherwise +@code{cc}. + +@item CFLAGS +@cindex compiler options, specifying +Options to give the compiler: default is @samp{-g -O2} for @code{gcc}, +@samp{-g} otherwise. @code{CFLAGS} comes after any other options. You +may need to include @code{-w} here if your compilations commonly have +useless warnings (e.g., @code{NULL redefined}), or @code{configure} may +fail to detect the presence of header files (it takes the messages on +standard error to mean the header file doesn't exist). + +@item CPPFLAGS +@cindex configuration compiler options +Options to pass to the compiler preprocessor; this matters most for +configuration, not the actual source compilation. The @code{configure} +script often does only preprocessing (e.g., to check for the existence +of @t{#include} files), and @code{CFLAGS} is not used for this. You may +need to set this to something like +@samp{-I/usr/local/include/wwwhatever} if you have the libwww library +installed for hyper-xdvik (see @file{xdvik/INSTALL}). + +@item DEFS +@cindex preprocessor options +Additional preprocessor options, but not used by @code{configure}. +Provided for enabling or disabling program features, as documented in +the various program-specific installation instructions. @code{DEFS} +comes before any compiler options included by the distribution +@file{Makefile}s or by @code{configure}. + +@item LDFLAGS +@cindex loader options +Additional options to give to the loader. @code{LDFLAGS} comes before +any other linker options. + +@item LIBS +@cindex libraries, specifying additional +Additional libraries to link with. +@end vtable + + +@node configure scenarios +@subsubsection @code{configure} scenarios + +Here are some common installation scenarios: + +@itemize @bullet +@item +Including X support in Metafont. This is disabled by default, since +many sites have no use for it, and it's a leading cause of configuration +problems. +@example +configure --with-x +@end example + +@item +@cindex @TeX{} hierarchy, one +Putting the binaries, @TeX{} files, GNU info files, etc.@: into a single +@TeX{} hierarchy, say @file{/here/texmf}, requires overriding defaults in +@code{configure}: +@example +configure --prefix=/here/texmf --datadir=/here +@end example + +@item +@cindex multiple architectures, compiling on +@cindex architectures, compiling multiple +@cindex symbolic link trees, for multiple architectures +@opindex --srcdir@r{, for building multiple architectures} +@pindex lndir @r{for building symlink trees} +You can compile on multiple architectures simultaneously either by +building symbolic link trees with the @code{lndir} script from the X11 +distribution, or with the @samp{--srcdir} option: +@example +configure --srcdir=@var{srcdir} +@end example + +@item +@cindex multiple architectures, directories for +If you are installing binaries for multiple architectures into a single +hierarchy, you will probably want to override the default @file{bin} and +@file{lib} directories, something like this: +@example +configure --prefix=@var{texmf} --datadir=@var{texmf} \ + --bindir=@var{texmf}/@var{arch}/bin --libdir=@var{texmf}/@var{arch}/lib +make texmf=@var{texmf} +@end example +@pindex depot +@cindex automounter, and configuration +@noindent (Unless you make provisions for architecture-specific files in +other ways, e.g., with Depot or an automounter.) + +@item +@opindex -O@r{, compiling with} +@opindex -g@r{, compiling without} +@cindex optimization, enabling +@cindex debugging with @samp{-g}, disabling +To compile with optimization (to compile without debugging, remove the +@samp{-g}): +@example +env CFLAGS="-g -O" sh configure @dots{} +@end example +@noindent For a potential problem if you optimize, see @ref{TeX or +Metafont failing,, @TeX{} or Metafont failing}. +@end itemize + + +@node Shared library +@subsubsection Shared library + +@cindex shared library, making + +@opindex --enable-shared +You can compile Kpathsea as a shared library on a few systems, by +specifying the option @samp{--enable-shared} when you run +@samp{configure}. + +@cindex code sharing +The main advantage in doing this is that the executables can then share +the code, thus decreasing memory and disk space requirements. + +On some systems, you can record the location of shared libraries in a +binary, usually by giving certain options to the linker. Then +individual users do not need to set their system's environment variable +(e.g., @code{LD_LIBRARY_PATH}) to find shared libraries. If you want to +do this, you will need to add the necessary options to @code{LDFLAGS} +yourself; for example, on Solaris, include something like +@samp{-R$@{prefix@}/lib}, on IRIX or Linux, use +@samp{-rpath$@{prefix@}/lib}. (Unfortunately, making this happen by +default is very difficult, because of interactions with an existing +installed shared library.) + + +@node Running make +@subsection Running @code{make} + +@pindex make@r{, running} + +@flindex texmf.cnf@r{, creating} +@flindex paths.h@r{, creating} +@code{make} (still in the top-level directory). This also creates the +@file{texmf.cnf} and @file{paths.h} files that define the default search +paths, and (by default) the @samp{plain} and @samp{latex} @TeX{} formats. + +@cindex fallback resolutions, overriding +You can override directory names and other values at @code{make}-time. +@file{make/paths.make} lists the variables most commonly reset. For +example, @samp{make default_texsizes=600} changes the list of fallback +resolutions. + +You can also override each of @code{configure}'s environment variables +(@pxref{configure environment}). The Make variables have the same names. + +Finally, you can supply additional options via the following variables. +(@code{configure} does not use these.) + +@vtable @samp +@item XCPPFLAGS +@itemx XDEFS +@cindex preprocessor options, additional +Preprocessor options. + +@item XCFLAGS +@cindex compiler options, additional +Compiler options. + +@item XLDFLAGS +@cindex loader options, initial +Loader options (included at beginning of link commands). + +@item XLOADLIBES +@cindex loader options, final +More loader options (included at end of link commands). + +@item XMAKEARGS +@cindex Make arguments, additional +Additional Make arguments passed to all sub-@code{make}'s. You may need +to include assignments to the other variables here via @code{XMAKEARGS}; +for example: @samp{make XMAKEARGS="CFLAGS=-O XDEFS=-DA4"}. +@end vtable + +@cindex compiler, changing +@cindex libraries, changing +It's generally a bad idea to use a different compiler (@samp{CC}) or +libraries (@code{LIBS}) for compilation than you did for configuration, +since the values @code{configure} determined may then be incorrect. + +@cindex universe, BSD vs.@: system V +@cindex BSD universe +@cindex system V universe +@cindex Solaris BSD compatibility, not +@flindex libucb@r{, avoiding} +@flindex ucbinclude@r{, avoiding} +Adding compiler options to change the ``universe'' you are using +(typically BSD vs.@: system V) is generally a cause of trouble. It's +best to use the native environment, whatever that is; @code{configure} +and the software usually adapt best to that. In particular, under +Solaris 2.x, you should not use the BSD-compatibility library +(@file{libucb}) or include files (@file{ucbinclude}). + +@cindex Babel +If you want to use the Babel La@TeX{} package for support of non-English +typesetting, you need to modify some files before making the La@TeX{} +format. See the file @file{install.txt} in the Babel distribution. + + +@node Installing files +@subsection Installing files + +@cindex installing files + +The basic command is the usual @code{make install}. For security +issues, @pxref{Security}. + +The first time you install any manual in the GNU Info system, you should +add a line (you choose where) to the file @file{dir} in your +@samp{$(infodir)} directory. Sample text for this is given near the top +of the Texinfo source files (@file{kpathsea/kpathsea.texi}, +@file{dvipsk/dvips.texi}, and @file{web2c/doc/web2c.texi}). +If you have a recent version of the GNU Texinfo distribution installed +(@url{ftp://prep.ai.mit.edu/pub/gnu/texinfo-3.9.tar.gz} or later), this +should happen automatically. + +On the offchance that this is your first Info installation, the +@file{dir} file I use is included in the distribution as +@file{etc/dir-example}. + +@cindex multiple architectures, installing on +@cindex architecture-(in)dependent files, installing only +@cindex installation, architecture-(in)dependent files only +You may wish to use one of the following targets, especially if you are +installing on multiple architectures: +@itemize @bullet +@item +@findex install-exec @r{Make target} +@code{make install-exec} to install in architecture-dependent +directories, i.e., ones that depend on the @code{$(exec_prefix)} Make +variable. This includes links to binaries, libraries, etc., not just +``executables''. + +@item +@findex install-data @r{Make target} +@code{make install-data} to install in architecture-independent +directories, such as documentation, configuration files, pool files, etc. +@end itemize + +@cindex AFS +@cindex Andrew File System, installing with +@flindex /afs/@dots{} @r{, installing into} +If you use the Andrew File System, the normal path (e.g., +@var{prefix}/bin) only gets you to a read-only copy of the files, and +you must specify a different path for installation. The best way to do this +is by setting the @samp{prefix} variable on the @code{make} command +line. The sequence becomes something like this: +@example +configure --prefix=/whatever +make +make install prefix=/afs/.@var{system.name}/system/1.3/@@sys/whatever +@end example +@flindex ls-R @r{and AFS} +@cindex relative filenames in @file{ls-R} +@noindent With AFS, you will definitely want to use relative filenames in +@file{ls-R} (@pxref{Filename database}), not absolute filenames. This +is done by default, but check anyway. + + +@node Cleaning up +@subsection Cleaning up + +@findex distclean @r{Make target} +The basic command is @code{make distclean}. This removes all files +created by the build. + +Alternatively, +@itemize @bullet +@item +@findex mostlyclean @r{Make target} +@code{make mostlyclean} if you intend to compile on another +architecture. For Web2C, since the generated C files are portable, +they are not removed. If the @code{lex} vs.@: @code{flex} situation +is going to be different on the next machine, @code{rm +web2c/lex.yy.c}. + +@item +@findex clean @r{Make target} +@code{make clean} to remove files created by compiling, but leave +configuration files and Makefiles. + +@item +@findex maintainer-clean @r{Make target} +@code{make maintainer-clean} to remove everything that the Makefiles can +rebuild. This is more than @samp{distclean} removes, and you should +only use it if you are thoroughly conversant with (and have the necessary +versions of) Autoconf. + +@item +@findex extraclean @r{Make target} +@code{make extraclean} to remove other junk, e.g., core files, log +files, patch rejects. This is independent of the other @samp{clean} +targets. +@end itemize + + +@node Filename database generation +@subsection Filename database generation + +@cindex filename database generation +@cindex generation of filename database + +You will probably want to set up a @code{cron} entry on the appropriate +machine(s) to rebuild the filename database nightly or so, as in: +@example +0 0 * * * cd @var{texmf} && @var{/bindir}/mktexlsr +@end example +@noindent @xref{Filename database}. + +Although the @code{mktex@dots{}} scripts make every effort to add +newly-created files on the fly, it can't hurt to make sure you get a +fresh version every so often. + + +@node mktex scripts +@subsection @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 +@subsubsection @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 +@subsubsection @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 +@subsubsection @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 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 Installation testing +@subsection Installation testing + +@cindex testing, post-installation +@cindex installation testing + +Besides the tests listed in @ref{Simple installation}, you can try +running @samp{make check}. This includes the torture tests (trip, trap, +and mptrap) that come with Web2c (@pxref{Triptrap,,, web2c, Web2c}). + + +@node Security +@section 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. diff --git a/Build/source/texk/kpathsea/doc/kpathsea.texi b/Build/source/texk/kpathsea/doc/kpathsea.texi new file mode 100644 index 00000000000..c33aeb7aefe --- /dev/null +++ b/Build/source/texk/kpathsea/doc/kpathsea.texi @@ -0,0 +1,2455 @@ +\input texinfo +@setfilename kpathsea.info +@settitle Kpathsea: A library for path searching + +@set version 3.5.7 +@set month-year July 2008 + +@copying +This file documents the Kpathsea library for path searching. + +Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, +2004, 2005, 2007, 2008 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 Free Software Foundation. +@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 (@email{kb@@mail.tug.org}) +@author Olaf Weber (@email{infovore@@xs4all.nl}) + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + + +@contents + + +@ifnottex +@node Top +@top Kpathsea library + +This manual documents how to install and use the Kpathsea library for +filename lookup. It corresponds to version @value{version}, +released in @value{month-year}. + +@menu +* Introduction:: Overview. +* Installation:: Compilation, installation, and bug reporting. + +* Path searching:: How filename lookups work. +* TeX support:: Special support for TeX-related file lookups. + +* Programming:: How to use Kpathsea features in your program. + +* 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 we maintain, uses this library: + +@itemize @bullet +@item Dviljk (see the @samp{dvilj} man page) +@item Dvipsk (@pxref{Top, , Introduction, dvips, Dvips: A DVI driver}) +@item GNU font utilities (@pxref{Top, , Introduction, fontu, GNU font +utilities}) +@item Web2c (@pxref{Top, , Introduction, 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. + +@cindex interface, not frozen +@cindex comments, making +@cindex suggestions, making +We are still actively maintaining the library (and probably always will +be, despite our hopes). If you have comments or suggestions, please send +them to us (@pxref{Reporting bugs}). + +@cindex conditions for use +@cindex license for using the library +@cindex GNU General Public License +We distribute the library under the GNU Library General Public License +(LGPL). 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, although we hope you will. See the files +@file{GPL} and @file{LGPL} for the text of the GNU 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, great!). 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. Anyway, here is the address: + +@flindex tug@@tug.org +@display +@TeX{} Users Group +P.O. Box 2311 +Portland OR 97208-2311 +USA +phone: +1 503 223-9994 +fax: +1 503 223-3960 +email: @email{tug@@tug.org} +@end display + +@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 @cite{Software---Practice and +Experience} 19(7), July 1989.) + +@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. 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, though I think Paul Vojta has completely rewritten Xdvi's +support by now. That is, I tried to go with the flow in each program, +rather than changing the program's calling sequences to conform to +common routines. + +Then, as bugs inevitably appeared, I found I was fixing the same thing +three times (Web2c and fontutils were always sharing code, since I +maintained 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 that 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. + + +@include install.texi +@include hier.texi +@include unixtex.texi +@include bugs.texi + + +@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. + +@menu +* Searching overview:: Basic scheme for searching. +* Path sources:: Where search paths can be defined. +* Path expansion:: Special constructs in search paths. +* 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. This +avoids possibly-expensive processing of path specifications that are +never needed on a particular run. (Unless the search explicitly +requested all matches.) + +@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. + +@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 can come from many sources. In the order in which +Kpathsea uses them: + +@enumerate +@item +@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{%} and continue to the end of the line. + +@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 must 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. + +@item If @samp{.@var{progname}} is present, 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}. This allows different flavors of @TeX{} to +have different search paths, for example. + +@item +@cindex right-hand side of variable assignments +@var{value} may contain any characters except @samp{%} and @samp{@@}. +(These restrictions are only necessary because of the processing done on +@file{texmf.cnf} at build time, so you can stick those characters in +after installation if you have to.) 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). A @samp{;} in +@var{value} is translated to @samp{:} if running under Unix; this is +useful to write a single @file{texmf.cnf} which can be used under both +Unix and NT. + +@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. +Although this format has obvious similarities 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. But there seemed little +advantage to doing 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. + +@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 DOS 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 in stead of the comma. The last +example could have been written @samp{x@{A:B@}@{1:2@}y}. + + +@flindex expand.c +Brace expansion is implemented in the source file +@file{kpathsea/expand.c}. It is a modification of the Bash sources, and +is thus covered by the GNU General Public License, rather than the +Library General Public License that covers the rest of Kpathsea. + + +@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 can find a way to @emph{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 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 +each 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}. This can be helpful to adapt +to ``8.3'' filename conventions in source files. + +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} +@vindex TEXMFDBS + +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); most sites have +only one hierarchy. Kpathsea looks for @file{ls-R} files along the +@code{TEXMFDBS} path, so that should presumably match the list of +hierarchies. + +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 La@TeX{} +package), @file{ls-R} will be automatically updated. + +@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 La@TeX{} 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 +Because the database may be out-of-date for a particular run, if a file +is not found in the database, by default Kpathsea goes ahead and +searches the disk. If a particular path element begins with @samp{!!}, +however, @emph{only} the database will be searched for that element, +never the disk. If the database does not exist, nothing will be +searched. Because this can surprise users (``I see the font +@file{foo.tfm} when I do an @code{ls}; why can't Dvips find it?''), it +is not in any of the default search paths. + + +@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. +* Standard options:: --help and --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). + +@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. +@example +gf: gf +pk: pk +bitmap font +afm: .afm +base: .base +bib: .bib +bst: .bst +cnf: .cnf +ls-R: ls-R +fmt: .fmt +map: .map +mem: .mem +mf: .mf +mfpool: .pool +mft: .mft +mp: .mp +mppool: .pool +MetaPost support +ocp: .ocp +ofm: .ofm .tfm +opl: .opl +otp: .otp +ovf: .ovf +ovp: .ovp +graphic/figure: .eps .epsi +tex: .tex +TeX system documentation +texpool: .pool +TeX system sources +PostScript header/font: .pro +Troff fonts +tfm: .tfm +type1 fonts: .pfa .pfb +vf: .vf +dvips config +ist: .ist +truetype fonts: .ttf .ttc +type42 fonts +web2c files +other text files +other binary files +misc fonts +web: .web +cweb: .w .web +enc: .enc +cmap: .cmap +sfd: .sfd +opentype fonts +pdftex config +lig files: .lig +texmfscripts +@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}. +The only values that make sense for @var{filetype} are @samp{pk}, +@samp{mf}, @samp{tex}, and @samp{tfm}. By default, all are off in +Kpsewhich. @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. 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 +@file{texmf-dist/scripts/pkg2/} to match 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 additional features not strictly related to path +lookup: + +@itemize @bullet +@item +@opindex --debug=@var{num} +@samp{--debug=@var{num}} sets the debugging options to @var{num}. +@xref{Debugging}. + +@item +@opindex --var-value=@var{variable} +@samp{--var-value=@var{variable}} outputs the value of @var{variable}, +expanding @samp{$} (@pxref{Variable expansion} and @samp{~} (@pxref{Tilde +expansion}) constructs, but not performing other expansions. + +@item +@opindex --expand-braces=@var{string} +@samp{--expand-braces=@var{string}} outputs the variable and brace +expansion of @var{string}. @xref{Path expansion}. + +@item +@opindex --expand-var=@var{string} +@samp{--expand-var=@var{string}} outputs the variable and tilde +expansion of @var{string}. For example, the @samp{mktex@dots{}} +scripts run @samp{kpsewhich --expand-var='$TEXMF'} to find the root of +the @TeX{} system hierarchy. @xref{Path expansion}. + +@item +@opindex --expand-path=@var{string} +@samp{--expand-path=@var{string}} outputs 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}, next. + +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} in the previous section. + +@item +@opindex --show-path=@var{name} +@samp{--show-path=@var{name}} shows 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. + +@end itemize + + +@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. + +@item +@opindex --version +@samp{--version} prints the Kpathsea version number and exits. +@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 (like all libraries) 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 supposedly 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 filenames, not file contents---if a GF +file is 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. +@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. + +@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 bst +@flindex .bst +@vindex BSTINPUTS +(Bib@TeX{} style file, @pxref{Basic BibTeX style files,, Basic Bib@TeX{} +style files, web2c, Web2c}) +@code{BSTINPUTS}; +suffix @samp{.bst}. + +@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 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 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 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 tree) +@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}, +@samp{.ttc}. + +@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 kpse_find_file +This algorithm is implemented in the routine @code{kpse_find_file} in +@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 kpse_find_glyph_format +This is implemented in @code{kpse_find_glyph_format} 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 @samp{%} and continue to the end of the line. +@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 circle fonts equivalent and includes +automatically generated maps for most PostScript fonts available from +various font suppliers. + +@example +circle10 lcircle10 +circle10 lcirc10 +lcircle10 circle10 +lcircle10 lcirc10 +lcirc10 circle10 +lcirc10 lcircle10 +@dots{} +include adobe.map +include apple.map +include bitstrea.map +@dots{} +@end example + +Fontmaps are implemented in the file @file{kpathsea/fontmap.c}. +The Fontname distribution has much more information on font naming +(@pxref{Introduction,,, 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} +@vindex kpse_fallback_font +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 assigning to the global variable +@code{kpse_fallback_font} or calling @code{kpse_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 Programming +@chapter Programming + +This chapter is for programmers who wish to use Kpathsea. +@xref{Introduction}, for the conditions under which you may do so. + +@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 I've modified to use Kpathsea (@pxref{Introduction}). Of +those, Dviljk is probably the simplest, and hence a good place to start. +Xdvik adds VF support and the complication of X resources. Dvipsk adds +the complication of its own config files. Web2c is source code I also +maintain, so it uses Kpathsea rather straightforwardly, but is of course +complicated by the Web to C translation. Finally, Kpsewhich is a small +utility program whose sole purpose is to exercise the main +path-searching functionality. + +@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 kpse_set_program_name +@vindex argv[0] +Call @code{kpse_set_program_name} with @code{argv[0]} as the first +argument; the second argument is a string or @code{NULL}. The second +argument is used by Kpathsea as the program name for the +@code{.@var{program}} feature of config files (@pxref{Config files}). +If the second argument is @code{NULL}, the value of the first argument +is used. This function must be called before any other use of the +Kpathsea library. + +@vindex program_invocation_name +@vindex program_invocation_short_name +@vindex kpse_program_name +@cindex error message macros +@code{kpse_set_program_name} always sets the global variables +@code{program_invocation_name} and @code{program_invocation_short_name}. +These variables are used in the error message macros defined in +@file{kpathsea/lib.h}. It sets the global 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 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 +@findex kpse_set_progname +@vindex argv[0] +The @code{kpse_set_progname} is deprecated. A call to +@code{kpse_set_progname} with @code{argv[0]} is equivalent to a call of +@code{kpse_set_program_name} with first argument @code{argv[0]} and +second argument @code{NULL}. The function is deprecated because it +cannot ensure that the @code{.@var{program}} feature of config files +will always work (@pxref{Config files}). + +@item +@vindex kpathsea_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{kpathsea_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 kpse_init_prog +@flindex proginit.h +Call @code{kpse_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 kpse_find_* +@findex kpse_find_file +The routine to actually find a file of type @var{format} is +@code{kpse_find_@var{format}}, defined in @file{tex-file.h}. These are +macros that expand to a call to @file{kpse_find_file}. You can call, +say, @code{kpse_find_tfm} after doing only the first 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 routines are @code{kpse_find_pk}, +@code{kpse_find_gf} and @code{kpse_find_glyph}, defined in +@file{tex-glyph.h}. These return 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 kpse_open_file +To actually open a file, not just return a filename, call +@code{kpse_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. + +@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 for +configuring your software if you use Kpathsea; I strongly recommend +using Autoconf regardless. It is available from +@url{ftp://prep.ai.mit.edu/pub/gnu/}. + + +@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 special formats, @samp{kpse_program_text_format} and +@samp{kpse_program_binary_format} exist, which 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{kpse_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 kpse_var_value +@flindex variable.h +@vindex shell_escape@r{, example for code} +To retrieve a value @var{var} from config files, the best way is to call +@code{kpse_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 variable expansion in the context of a search path (as +opposed to simply retrieving a value) is @code{kpse_var_expand}, also +declared in @file{kpathsea/variable.h}. It's generally only necessary +to set the search path structure components as explained in the previous +section, rather than using this yourself. + +@findex kpse_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{kpse_cnf_get} (declared in @file{kpathsea/cnf.h}) +with the string @var{var}. + +No initialization calls are needed. + + +@node Index +@unnumbered Index + +@printindex cp + +@bye diff --git a/Build/source/texk/kpathsea/doc/unixtex.ftp b/Build/source/texk/kpathsea/doc/unixtex.ftp new file mode 100644 index 00000000000..d0c6322141c --- /dev/null +++ b/Build/source/texk/kpathsea/doc/unixtex.ftp @@ -0,0 +1,151 @@ +`unixtex.ftp': Obtaining TeX +============================ + +This is `ftp://ftp.tug.org/tex/unixtex.ftp', last updated 26 December +2003. Also available as `http://www.tug.org/unixtex.ftp'. The IP +address is currently `[130.225.2.178]'. It is also in Kpathsea source +distributions as `etc/unixtex.ftp' (although the network version is +usually newer). Mail <tex-k@mail.tug.org> with comments or questions. + + Following are general instructions for Unix or other sites who wish to +acquire the Web2c distribution, (plain) TeX, LaTeX (2e), BibTeX, +Metafont, MetaPost, DVI processors for the X window system, PostScript, +the PCL language in the HP LaserJet, and related programs. They are +oriented towards building from the original sources, though some +information on alternative packages is included in the last section. +See also `http://www.tug.org/web2c/', the Web2c and Kpathsea home page. + + Please note that the Web2c distribution is a bare-bones distribution +in source form, and building a complete installation from it is a +non-trivial matter. For most uses, it is a better idea to install a +distribution with pre-packaged binaries for your platform. The +principal example of such a distribution is TeX Live +(`http://www.tug.org/texlive/'), which is based on the Web2c sources. + + Please consider joining the TeX Users Group (TUG) or another user +group of your choice to help support the maintenance and development of +the programs you retrieve. See `http://www.tug.org/join.html' for +information and the membership registration form, and +`http://www.tug.org/usergroups.html' for a listing of all user groups. + + For actual installation instructions after obtaining the necessary +sources, see *Note Installation::. A copy is in the distribution file +`kpathsea/INSTALL'. + +Electronic distribution +----------------------- + +In many places we refer to CTAN:. This is _both_ a host name and a +directory name. Here are the primary locations: + + `ftp://ctan.tug.org/tex-archive/' (Vermont, USA) + `ftp://ftp.dante.de/tex-archive/' (Germany) + `ftp://ftp.tex.ac.uk/tex-archive/' (England) + +CTAN has many mirrors worldwide; see the top-level file +`README.mirrors' from one of the sites above or see +`http://www.tug.org/CTAN.sites'. + + You can also access CTAN via the World Wide Web, electronic mail, or +NFS. The same `README.mirrors' file explains how. + + You will need to retrieve some or all of the following archives, +depending on your needs (don't forget to set binary mode for file +transfers): + +`CTAN:/systems/web2c/web.tar.gz' + The original WEB source files, written primarily by Don Knuth. + Required unless you already have this `web' version. (The WEB + sources change irregularly with respect to Web2c itself.) Unpacks + into `web2c-VERSION'. + +`CTAN:/systems/web2c/web2c.tar.gz' + The Web2c system. Required. Also unpacks into `web2c-VERSION'. + +`CTAN:/systems/web2c/web2c-etex.tar.gz' + Additions to the Web2c system for building e-TeX. Optional. + Unpacks into `web2c-VERSION'. + +`CTAN:/systems/web2c/etexlib.tar.gz' + Additions to the texmf tree needed to build e-TeX. Optional. + Unpacks into `texmf/'. + +`CTAN:/systems/web2c/etexdoc.tar.gz' + Documentation for e-TeX as an addition to the texmf tree. + Optional. Unpacks into `texmf/'. + +`CTAN:/systems/web2c/web2c-omega.tar.gz' + Additions to the Web2c system for building Omega. Optional. + Unpacks into `web2c-VERSION'. + +`CTAN:/systems/web2c/omegalib.tar.gz' + Additions to the texmf tree needed to build Omega. Optional. + Unpacks into `texmf/'. + +`CTAN:/systems/web2c/omegadoc.tar.gz' + Documentation for Omega as an addition to the texmf tree. + Optional. Unpacks into `texmf/'. + +`CTAN:/systems/web2c/web2c-pdftex.tar.gz' + Additions to the Web2c system for building pdfTeX. Optional. + Unpacks into `web2c-VERSION'. + +`CTAN:/systems/web2c/pdftexlib.tar.gz' + Additions to the texmf tree needed to build pdfTeX. Optional. + Unpacks into `texmf/'. + +`CTAN:/dviware/xdvik/xdvik.tar.gz' + X window system DVI previewer. Unpacks into `xdvik-VERSION'. + Optional. + + Additional drivers, macro files, and other support are needed to build +a working system. These are available in teTeX. + + All that said, the originating host for the software above is +`ftp.tug.org'. You can retrieve these distributions (but not much +else) from the `tex/' directory on that host. + +CD-ROM distribution +------------------- + +Numerous organizations distribute various TeX CD-ROM's (and DVD's): + + * Virtually all the TeX user groups collaborate to produce the `TeX + Live' distribution once a year; see `http://www.tug.org/texlive/' + for more information. + + * The Free Software Foundation's `Source Code CD-ROM' contains the + minimal TeX source distribution described in the previous section + (i.e., enough to print GNU documentation); email <gnu@gnu.org>. + + * Most Linux distributions include some TeX package based on Web2c; + see the Linux documentation file `Distribution-HOWTO' for a + comparison of Linux distributions, available (for example) via + `http://www.linux.org'. + + If you know of additional TeX distributions to add to this list, +please inform <tex-k@mail.tug.org>. + +Other TeX packages +------------------ + +Many other TeX implementations are available in `CTAN:/systems', +including ready-to-run distributions for Unix, Amiga, Acorn, VMS, +Macintosh, DOS, and Windows (in various forms). Although Web2c has +support in the source code for many operating systems, and in fact some +of the other distributions are based on it, it's unlikely to work as +distributed on anything but Unix. (Please contribute improvements!) + + The principal user-oriented Unix distribution based on Web2c is the +teTeX distribution. It includes complete sources, and runs on all +modern Unix variants, including Linux. It contains many TeX-related +programs besides those in the core Web2c. + + The host labrea.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 build your TeX library tree ab initio, +it is more reliable and less work to retrieve these files as part of +the above packages. In any case, labrea is not the canonical source for +anything except what was created by Stanford TeX project, so do not +rely on all the files available at that ftp site being up-to-date. + diff --git a/Build/source/texk/kpathsea/doc/unixtex.texi b/Build/source/texk/kpathsea/doc/unixtex.texi new file mode 100644 index 00000000000..19cf159f465 --- /dev/null +++ b/Build/source/texk/kpathsea/doc/unixtex.texi @@ -0,0 +1,286 @@ +@ifclear version +@defcodeindex fl +@defcodeindex op +@end ifclear + +@node unixtex.ftp +@section @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://ftp.tug.org/tex/unixtex.ftp}, last updated 26 December +2003. Also available as @uref{http://www.tug.org/unixtex.ftp}. The +IP address is currently @code{[130.225.2.178]}. It is also in +Kpathsea source distributions as @file{etc/unixtex.ftp} (although the +network version is usually newer). Mail @email{tex-k@@mail.tug.org} +with comments or questions. + +Following are general instructions for Unix or other sites who wish to +acquire the Web2c distribution, (plain) @TeX{}, La@TeX{} (2e), +Bib@TeX{}, Metafont, MetaPost, DVI processors for the X window system, +PostScript, the PCL language in the HP LaserJet, and related programs. +They are oriented towards building from the original sources, though +some information on alternative packages is included in the last +section. See also @uref{http://www.tug.org/web2c/}, the Web2c and +Kpathsea home page. + +Please note that the Web2c distribution is a bare-bones distribution +in source form, and building a complete installation from it is a +non-trivial matter. For most uses, it is a better idea to install a +distribution with pre-packaged binaries for your platform. The +principal example of such a distribution is @TeX{} Live +(@uref{http://www.tug.org/texlive/}), which is based on the +Web2c sources. + +Please consider joining the @TeX{} Users Group (TUG) or another user +group of your choice to help support the maintenance and development +of the programs you retrieve. See @uref{http://www.tug.org/join.html} +for information and the membership registration form, and +@uref{http://www.tug.org/usergroups.html} for a listing of all user groups. + +For actual installation instructions after obtaining the necessary +sources, see @ref{Installation}. A copy is in the distribution file +@file{kpathsea/INSTALL}. + +@menu +* Electronic distribution:: CTAN and so forth. +* CD-ROM distribution:: +* Other TeX packages:: +@end menu + +@c * Tape distribution:: +@c used to be in this menu. + +@node Electronic distribution +@subsection Electronic distribution + +@cindex ftp retrieval +@cindex obtaining Web2c by ftp +@cindex distributions, via ftp + +@cindex CTAN, defined +@cindex backbone of CTAN +In many places we refer to @var{CTAN:}. This is @emph{both} a host name +and a directory name. Here are the primary locations: + +@example +@uref{ftp://ctan.tug.org/tex-archive/} @r{(Vermont, USA)} +@uref{ftp://ftp.dante.de/tex-archive/} @r{(Germany)} +@uref{ftp://ftp.tex.ac.uk/tex-archive/} @r{(England)} +@end example + +@noindent +@flindex README.mirrors +@flindex CTAN.sites +@cindex mirrors, FTP +CTAN has many mirrors worldwide; see the top-level file +@file{README.mirrors} from one of the sites above or see +@uref{http://www.tug.org/CTAN.sites}. + +@cindex World Wide Web CTAN access +@cindex email CTAN access +@cindex NFS CTAN access +You can also access CTAN via the World Wide Web, electronic +mail, or NFS. The same @file{README.mirrors} file explains how. + +@cindex binary mode, for file transfers +You will need to retrieve some or all of the following archives, +depending on your needs (don't forget to set binary mode for file +transfers): + +@table @asis +@item @file{@var{CTAN:}/systems/web2c/web.tar.gz} +@cindex Knuth, Donald E., original author +The original WEB source files, written primarily by Don Knuth. Required +unless you already have this @file{web} version. (The WEB sources +change irregularly with respect to Web2c itself.) Unpacks into +@file{web2c-@var{version}}. + +@item @file{@var{CTAN:}/systems/web2c/web2c.tar.gz} +The Web2c system. Required. Also unpacks into +@file{web2c-@var{version}}. + +@item @file{@var{CTAN:}/systems/web2c/web2c-etex.tar.gz} +Additions to the Web2c system for building e-@TeX{}. Optional. Unpacks +into @file{web2c-@var{version}}. + +@item @file{@var{CTAN:}/systems/web2c/etexlib.tar.gz} +Additions to the texmf tree needed to build e-@TeX{}. Optional. +Unpacks into @file{texmf/}. + +@item @file{@var{CTAN:}/systems/web2c/etexdoc.tar.gz} +Documentation for e-@TeX{} as an addition to the texmf tree. Optional. +Unpacks into @file{texmf/}. + +@item @file{@var{CTAN:}/systems/web2c/web2c-omega.tar.gz} +Additions to the Web2c system for building Omega. Optional. Unpacks +into @file{web2c-@var{version}}. + +@item @file{@var{CTAN:}/systems/web2c/omegalib.tar.gz} +Additions to the texmf tree needed to build Omega. Optional. Unpacks +into @file{texmf/}. + +@item @file{@var{CTAN:}/systems/web2c/omegadoc.tar.gz} +Documentation for Omega as an addition to the texmf tree. Optional. +Unpacks into @file{texmf/}. + +@item @file{@var{CTAN:}/systems/web2c/web2c-pdftex.tar.gz} +Additions to the Web2c system for building pdf@TeX{}. Optional. +Unpacks into @file{web2c-@var{version}}. + +@item @file{@var{CTAN:}/systems/web2c/pdftexlib.tar.gz} +Additions to the texmf tree needed to build pdf@TeX{}. Optional. +Unpacks into @file{texmf/}. + +@item @file{@var{CTAN:}/dviware/xdvik/xdvik.tar.gz} +X window system DVI previewer. Unpacks into @file{xdvik-@var{version}}. +Optional. +@end table + +Additional drivers, macro files, and other support are needed to build +a working system. These are available in te@TeX{}. + +All that said, the originating host for the software above is +@file{ftp.tug.org}. You can retrieve these distributions (but not much +else) from the @file{tex/} directory on that host. + + +@node CD-ROM distribution +@subsection CD-ROM distribution + +@cindex CD-ROM distributions +@cindex obtaining Web2c on CD-ROM +@cindex distributions, on CD-ROM + +Numerous organizations distribute various @TeX{} CD-ROM's (and DVD's): + +@itemize @bullet +@item +@cindex @TeX{} Live CD-ROM +Virtually all the @TeX{} user groups collaborate to produce the +@cite{@TeX{} Live} distribution once a year; see +@uref{http://www.tug.org/texlive/} for more information. + +@item +@cindex Free Software Foundation +@cindex FSF Source Code CD-ROM +The Free Software Foundation's @cite{Source Code CD-ROM} contains the +minimal @TeX{} source distribution described in the previous section +(i.e., enough to print GNU documentation); email +@email{gnu@@gnu.org}. + +@c Commented out: the information is outdated in way or another. + +@c @item +@c The Gateway@! CD-ROM set contains a runnable NetBSD/Amiga distribution +@c and sources; see @url{http://www.netbsd.org/Sites/cdroms.html}. + +@c @item +@c The InfoMagic CD-ROM is a copy of CTAN (see previous section); see +@c @url{http://www.infomagic.com}. + +@c @item +@c @cindex 4all@TeX{} Live CD-ROM +@c @cindex NTG +@c NTG (Dutch-speaking @TeX{} user group) produced the 4all@TeX{} CD-ROM; +@c email @email{ntg@@nic.surfnet.nl}, or see +@c @url{http://www.ntg.nl/4allcd/}. This is a runnable system. + +@c @item +@c @cindex Prime Time @TeX{}cetera CD-ROM +@c The Prime Time @TeX{}cetera CD-ROM is also a copy of CTAN; email +@c @email{ptf@@ctcl.com} or see @url{http://www.ptf.com/ptf/}. + +@c @item +@c @cindex Walnut Creek @TeX{} CD-ROM +@c Walnut Creek's @TeX{} CD-ROM is also a copy of CTAN; email +@c @email{info@@cdrom.com} or see +@c @url{http://www.cdrom.com:/titles/tex.html}. + +@item +@cindex Linux, using Web2c +Most Linux distributions include some @TeX{} package based on +Web2c; see the Linux documentation file @samp{Distribution-HOWTO} for a +comparison of Linux distributions, available (for example) via +@uref{http://www.linux.org}. +@end itemize + +If you know of additional @TeX{} distributions to add to this +list, please inform @email{tex-k@@mail.tug.org}. + +@ignore + +@node Tape distribution +@subsection Tape distribution + +@cindex tape distribution +@cindex obtaining @TeX{} on tape +@cindex distributions, on tape + +@cindex Northwest Computing Support Center +@flindex unixtex@@u.washington.edu +@cindex support organization +You can obtain a complete @TeX{} distribution, including Web2c, on tape. +Contact: +@display +Pierre MacKay / Denny Hall, Mail Stop DH-10 / Department of Classics +University of Washington / Seattle, WA 98195 / USA +phone: 206-543-2268; email: @email{unixtex@@u.washington.edu} +@end display + +At this writing, the distribution is available in @code{tar} format on +4@dmn{mm} DAT cartridges, and the +cost is US$210. Make checks payable to the University of Washington, +drawn on a U.S. bank. Purchase orders are acceptable, but they carry an +extra charge of $10 to pay for invoice processing. Overseas sites, +please add $20 for shipment via air parcel post, or $30 for shipment via +courier. + +@end ignore + +@node Other TeX packages +@subsection Other @TeX{} packages + +@cindex other @TeX{} distributions +@cindex @TeX{} distributions besides Web2c + +@cindex Amiga @TeX{} implementations +@cindex Acorn @TeX{} implementations +@cindex VMS @TeX{} implementations +@cindex Macintosh @TeX{} implementations +@cindex DOS @TeX{} implementations +@cindex Windows @TeX{} implementations +Many other @TeX{} implementations are available in +@file{@var{CTAN:}/systems}, including ready-to-run distributions for +Unix, Amiga, Acorn, VMS, Macintosh, DOS, and Windows (in various forms). +Although Web2c has support in the source code for many operating +systems, and in fact some of the other distributions are based on it, +it's unlikely to work as distributed on anything but Unix. (Please +contribute improvements!) + +@cindex te@TeX{} +@cindex precompiled Unix binaries +The principal user-oriented Unix distribution based on Web2c is the +te@TeX{} distribution. It includes complete sources, and runs on +all modern Unix variants, including Linux. It contains many +@TeX{}-related programs besides those in the core Web2c. + +@flindex labrea.stanford.edu +@cindex Knuth, Donald E., archive of programs by +The host @t{labrea.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 build your @TeX{} +library tree ab initio, it is more reliable and less work to retrieve +these files as part of the above packages. In any case, @t{labrea} is +not the canonical source for anything except what was created by +Stanford @TeX{} project, so do not rely on all the files available at +that ftp site being up-to-date. |