diff options
author | Karl Berry <karl@freefriends.org> | 2021-02-25 19:22:25 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-02-25 19:22:25 +0000 |
commit | ad547a6b5986815fda458221149728d9d9ab1d87 (patch) | |
tree | 16296910eb3eca724371474ea9aea3994dc69614 /Build/source/texk/web2c/doc | |
parent | 947b43de3dd21d58ccc2ffadefc4441ea1c2a813 (diff) |
restore Build,TODO from r57911
git-svn-id: svn://tug.org/texlive/trunk@57915 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/web2c/doc')
-rw-r--r-- | Build/source/texk/web2c/doc/Makefile.am | 8 | ||||
-rw-r--r-- | Build/source/texk/web2c/doc/Makefile.in | 906 | ||||
-rw-r--r-- | Build/source/texk/web2c/doc/README | 7 | ||||
-rw-r--r-- | Build/source/texk/web2c/doc/install.texi | 288 | ||||
-rw-r--r-- | Build/source/texk/web2c/doc/ref.txi | 118 | ||||
-rw-r--r-- | Build/source/texk/web2c/doc/web2c.info | 4587 | ||||
-rw-r--r-- | Build/source/texk/web2c/doc/web2c.texi | 4353 |
7 files changed, 10267 insertions, 0 deletions
diff --git a/Build/source/texk/web2c/doc/Makefile.am b/Build/source/texk/web2c/doc/Makefile.am new file mode 100644 index 00000000000..2688e595443 --- /dev/null +++ b/Build/source/texk/web2c/doc/Makefile.am @@ -0,0 +1,8 @@ +## Makefile.am for the TeX Live subdirectory texk/web2c/doc/ +## +## Copyright (C) 2009 Peter Breitenlohner <tex-live@tug.org> +## You may freely use, modify and/or distribute this file. +## +info_TEXINFOS = web2c.texi +web2c_TEXINFOS = install.texi ref.txi + diff --git a/Build/source/texk/web2c/doc/Makefile.in b/Build/source/texk/web2c/doc/Makefile.in new file mode 100644 index 00000000000..f343ffa6b91 --- /dev/null +++ b/Build/source/texk/web2c/doc/Makefile.in @@ -0,0 +1,906 @@ +# Makefile.in generated by automake 1.16.3 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2020 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/web2c-disable.m4 \ + $(top_srcdir)/../../m4/ax_cxx_compile_stdcxx.m4 \ + $(top_srcdir)/../../m4/kpse-asm.m4 \ + $(top_srcdir)/../../m4/kpse-cairo-flags.m4 \ + $(top_srcdir)/../../m4/kpse-common.m4 \ + $(top_srcdir)/../../m4/kpse-cross.m4 \ + $(top_srcdir)/../../m4/kpse-cxx-hack.m4 \ + $(top_srcdir)/../../m4/kpse-fontconfig-flags.m4 \ + $(top_srcdir)/../../m4/kpse-freetype2-flags.m4 \ + $(top_srcdir)/../../m4/kpse-gmp-flags.m4 \ + $(top_srcdir)/../../m4/kpse-graphite2-flags.m4 \ + $(top_srcdir)/../../m4/kpse-harfbuzz-flags.m4 \ + $(top_srcdir)/../../m4/kpse-icu-flags.m4 \ + $(top_srcdir)/../../m4/kpse-kpathsea-flags.m4 \ + $(top_srcdir)/../../m4/kpse-lex.m4 \ + $(top_srcdir)/../../m4/kpse-lib-version.m4 \ + $(top_srcdir)/../../m4/kpse-libpng-flags.m4 \ + $(top_srcdir)/../../m4/kpse-lt-hack.m4 \ + $(top_srcdir)/../../m4/kpse-lua52-flags.m4 \ + $(top_srcdir)/../../m4/kpse-lua53-flags.m4 \ + $(top_srcdir)/../../m4/kpse-luajit-flags.m4 \ + $(top_srcdir)/../../m4/kpse-macos-framework.m4 \ + $(top_srcdir)/../../m4/kpse-mpfr-flags.m4 \ + $(top_srcdir)/../../m4/kpse-pixman-flags.m4 \ + $(top_srcdir)/../../m4/kpse-pplib-flags.m4 \ + $(top_srcdir)/../../m4/kpse-ptexenc-flags.m4 \ + $(top_srcdir)/../../m4/kpse-socket-libs.m4 \ + $(top_srcdir)/../../m4/kpse-teckit-flags.m4 \ + $(top_srcdir)/../../m4/kpse-warnings.m4 \ + $(top_srcdir)/../../m4/kpse-web2c.m4 \ + $(top_srcdir)/../../m4/kpse-win32.m4 \ + $(top_srcdir)/../../m4/kpse-xpdf-flags.m4 \ + $(top_srcdir)/../../m4/kpse-zlib-flags.m4 \ + $(top_srcdir)/../../m4/kpse-zziplib-flags.m4 \ + $(top_srcdir)/../../m4/libtool.m4 \ + $(top_srcdir)/../../m4/ltoptions.m4 \ + $(top_srcdir)/../../m4/ltsugar.m4 \ + $(top_srcdir)/../../m4/ltversion.m4 \ + $(top_srcdir)/../../m4/lt~obsolete.m4 \ + $(top_srcdir)/../../version.ac $(top_srcdir)/ac/web2c.ac \ + $(top_srcdir)/synctexdir/ac/synctex.ac \ + $(top_srcdir)/synctexdir/synctex_parser_api_level.txt \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/w2c/c-auto.h \ + $(top_builddir)/ff-config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +AM_V_DVIPS = $(am__v_DVIPS_@AM_V@) +am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@) +am__v_DVIPS_0 = @echo " DVIPS " $@; +am__v_DVIPS_1 = +AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@) +am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@) +am__v_MAKEINFO_0 = @echo " MAKEINFO" $@; +am__v_MAKEINFO_1 = +AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@) +am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@) +am__v_INFOHTML_0 = @echo " INFOHTML" $@; +am__v_INFOHTML_1 = +AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@) +am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@) +am__v_TEXI2DVI_0 = @echo " TEXI2DVI" $@; +am__v_TEXI2DVI_1 = +AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@) +am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@) +am__v_TEXI2PDF_0 = @echo " TEXI2PDF" $@; +am__v_TEXI2PDF_1 = +AM_V_texinfo = $(am__v_texinfo_@AM_V@) +am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@) +am__v_texinfo_0 = -q +am__v_texinfo_1 = +AM_V_texidevnull = $(am__v_texidevnull_@AM_V@) +am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@) +am__v_texidevnull_0 = > /dev/null +am__v_texidevnull_1 = +INFO_DEPS = $(srcdir)/web2c.info +TEXINFO_TEX = $(top_srcdir)/../../build-aux/texinfo.tex +am__TEXINFO_TEX_DIR = $(top_srcdir)/../../build-aux +DVIS = web2c.dvi +PDFS = web2c.pdf +PSS = web2c.ps +HTMLS = web2c.html +TEXINFOS = web2c.texi +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__installdirs = "$(DESTDIR)$(infodir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(srcdir)/Makefile.in \ + $(top_srcdir)/../../build-aux/texinfo.tex $(web2c_TEXINFOS) \ + README +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +AR = @AR@ +AS = @AS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CAIRO_DEPEND = @CAIRO_DEPEND@ +CAIRO_INCLUDES = @CAIRO_INCLUDES@ +CAIRO_LIBS = @CAIRO_LIBS@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CTANGLE = @CTANGLE@ +CTANGLEBOOT = @CTANGLEBOOT@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CXXLD = @CXXLD@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +FONTCONFIG_INCLUDES = @FONTCONFIG_INCLUDES@ +FONTCONFIG_LIBS = @FONTCONFIG_LIBS@ +FREETYPE2_DEPEND = @FREETYPE2_DEPEND@ +FREETYPE2_INCLUDES = @FREETYPE2_INCLUDES@ +FREETYPE2_LIBS = @FREETYPE2_LIBS@ +FT2_CONFIG = @FT2_CONFIG@ +GMP_DEPEND = @GMP_DEPEND@ +GMP_INCLUDES = @GMP_INCLUDES@ +GMP_LIBS = @GMP_LIBS@ +GRAPHITE2_DEPEND = @GRAPHITE2_DEPEND@ +GRAPHITE2_INCLUDES = @GRAPHITE2_INCLUDES@ +GRAPHITE2_LIBS = @GRAPHITE2_LIBS@ +GREP = @GREP@ +HARFBUZZ_DEPEND = @HARFBUZZ_DEPEND@ +HARFBUZZ_INCLUDES = @HARFBUZZ_INCLUDES@ +HARFBUZZ_LIBS = @HARFBUZZ_LIBS@ +HAVE_CXX11 = @HAVE_CXX11@ +ICU_CONFIG = @ICU_CONFIG@ +ICU_DEPEND = @ICU_DEPEND@ +ICU_INCLUDES = @ICU_INCLUDES@ +ICU_LIBS = @ICU_LIBS@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KPATHSEA_DEPEND = @KPATHSEA_DEPEND@ +KPATHSEA_INCLUDES = @KPATHSEA_INCLUDES@ +KPATHSEA_LIBS = @KPATHSEA_LIBS@ +KPATHSEA_PATHS_H = @KPATHSEA_PATHS_H@ +KPSEWHICH = @KPSEWHICH@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LEX = @LEX@ +LEXLIB = @LEXLIB@ +LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@ +LIBOBJS = @LIBOBJS@ +LIBPNG_DEPEND = @LIBPNG_DEPEND@ +LIBPNG_INCLUDES = @LIBPNG_INCLUDES@ +LIBPNG_LIBS = @LIBPNG_LIBS@ +LIBS = @LIBS@ +LIBSYNCTEX = @LIBSYNCTEX@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +LTLIBSYNCTEX = @LTLIBSYNCTEX@ +LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@ +LUA52_DEFINES = @LUA52_DEFINES@ +LUA52_DEPEND = @LUA52_DEPEND@ +LUA52_INCLUDES = @LUA52_INCLUDES@ +LUA52_LIBS = @LUA52_LIBS@ +LUA53_DEFINES = @LUA53_DEFINES@ +LUA53_DEPEND = @LUA53_DEPEND@ +LUA53_INCLUDES = @LUA53_INCLUDES@ +LUA53_LIBS = @LUA53_LIBS@ +LUAJIT_DEFINES = @LUAJIT_DEFINES@ +LUAJIT_DEPEND = @LUAJIT_DEPEND@ +LUAJIT_INCLUDES = @LUAJIT_INCLUDES@ +LUAJIT_LDEXTRA = @LUAJIT_LDEXTRA@ +LUAJIT_LIBS = @LUAJIT_LIBS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +MPFR_DEPEND = @MPFR_DEPEND@ +MPFR_INCLUDES = @MPFR_INCLUDES@ +MPFR_LIBS = @MPFR_LIBS@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJCXX = @OBJCXX@ +OBJCXXDEPMODE = @OBJCXXDEPMODE@ +OBJCXXFLAGS = @OBJCXXFLAGS@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTANGLE = @OTANGLE@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PIXMAN_DEPEND = @PIXMAN_DEPEND@ +PIXMAN_INCLUDES = @PIXMAN_INCLUDES@ +PIXMAN_LIBS = @PIXMAN_LIBS@ +PKG_CONFIG = @PKG_CONFIG@ +PPLIB_DEPEND = @PPLIB_DEPEND@ +PPLIB_INCLUDES = @PPLIB_INCLUDES@ +PPLIB_LIBS = @PPLIB_LIBS@ +PTEXENC_DEPEND = @PTEXENC_DEPEND@ +PTEXENC_INCLUDES = @PTEXENC_INCLUDES@ +PTEXENC_LIBS = @PTEXENC_LIBS@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +SYNCTEXVERSION = @SYNCTEXVERSION@ +SYNCTEX_LT_VERSINFO = @SYNCTEX_LT_VERSINFO@ +TANGLE = @TANGLE@ +TANGLEBOOT = @TANGLEBOOT@ +TECKIT_DEPEND = @TECKIT_DEPEND@ +TECKIT_INCLUDES = @TECKIT_INCLUDES@ +TECKIT_LIBS = @TECKIT_LIBS@ +TIE = @TIE@ +VERSION = @VERSION@ +WARNING_CFLAGS = @WARNING_CFLAGS@ +WARNING_CXXFLAGS = @WARNING_CXXFLAGS@ +WARNING_OBJCXXFLAGS = @WARNING_OBJCXXFLAGS@ +WEB2CVERSION = @WEB2CVERSION@ +XMKMF = @XMKMF@ +XPDF_DEPEND = @XPDF_DEPEND@ +XPDF_INCLUDES = @XPDF_INCLUDES@ +XPDF_LIBS = @XPDF_LIBS@ +X_CFLAGS = @X_CFLAGS@ +X_EXTRA_LIBS = @X_EXTRA_LIBS@ +X_LIBS = @X_LIBS@ +X_PRE_LIBS = @X_PRE_LIBS@ +YACC = @YACC@ +YFLAGS = @YFLAGS@ +ZLIB_DEPEND = @ZLIB_DEPEND@ +ZLIB_INCLUDES = @ZLIB_INCLUDES@ +ZLIB_LIBS = @ZLIB_LIBS@ +ZZIPLIB_DEPEND = @ZZIPLIB_DEPEND@ +ZZIPLIB_INCLUDES = @ZZIPLIB_INCLUDES@ +ZZIPLIB_LIBS = @ZZIPLIB_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +ac_ct_OBJCXX = @ac_ct_OBJCXX@ +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@ +ipc_socketlibs = @ipc_socketlibs@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +lua_socketlibs = @lua_socketlibs@ +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@ +subdirs = @subdirs@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +wlibs = @wlibs@ +x_ext_lib = @x_ext_lib@ +x_tool_libs = @x_tool_libs@ +info_TEXINFOS = web2c.texi +web2c_TEXINFOS = install.texi ref.txi +all: all-am + +.SUFFIXES: +.SUFFIXES: .dvi .html .info .pdf .ps .texi +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign doc/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs + +.texi.info: + $(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && $(am__cd) $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + $(am__cd) $(srcdir); \ + else \ + rc=$$?; \ + $(am__cd) $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + $(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \ + $< + +.texi.pdf: + $(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \ + $< + +.texi.html: + $(AM_V_MAKEINFO)rm -rf $(@:.html=.htp) + $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@ && mv $(@:.html=.htp) $@; \ + else \ + rm -rf $(@:.html=.htp); exit 1; \ + fi +$(srcdir)/web2c.info: web2c.texi $(web2c_TEXINFOS) +web2c.dvi: web2c.texi $(web2c_TEXINFOS) +web2c.pdf: web2c.texi $(web2c_TEXINFOS) +web2c.html: web2c.texi $(web2c_TEXINFOS) +.dvi.ps: + $(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) $(AM_V_texinfo) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f "$(distdir)/$$relfile" || \ + cp -p $$file "$(distdir)/$$relfile"; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf web2c.t2d web2c.t2p + +clean-aminfo: + -test -z "web2c.dvi web2c.pdf web2c.ps web2c.html" \ + || rm -rf web2c.dvi web2c.pdf web2c.ps web2c.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) distdir-am + +distdir-am: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) +installdirs: + for dir in "$(DESTDIR)$(infodir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +html: html-am + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + $(am__strip_dir) \ + d2=$$d$$p; \ + if test -d "$$d2"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ + else \ + list2="$$list2 $$d2"; \ + fi; \ + done; \ + test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done; } +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \ + fi; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + echo "$$ifile"; \ + else : ; fi; \ + done; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done + @$(POST_INSTALL) + @if $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \ + mostlyclean-libtool + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-aminfo clean-generic \ + clean-libtool cscopelist-am ctags-am dist-info distclean \ + distclean-generic distclean-libtool distdir dvi dvi-am html \ + html-am info info-am install install-am install-data \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-pdf install-pdf-am \ + install-ps install-ps-am install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-aminfo maintainer-clean-generic mostlyclean \ + mostlyclean-aminfo mostlyclean-generic mostlyclean-libtool pdf \ + pdf-am ps ps-am tags-am uninstall uninstall-am \ + uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.PRECIOUS: Makefile + + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/Build/source/texk/web2c/doc/README b/Build/source/texk/web2c/doc/README new file mode 100644 index 00000000000..782585c019f --- /dev/null +++ b/Build/source/texk/web2c/doc/README @@ -0,0 +1,7 @@ +This directory contains the Texinfo manual for Web2c, which includes +nodes for all the TeX system programs in the distribution. + +The man pages are no longer supported, and are no longer in the distribution. +I do not wish to take the time to maintain the same documentation in two +source formats. If you want to volunteer to keep the man pages in sync +with the Texinfo manual, let me know. diff --git a/Build/source/texk/web2c/doc/install.texi b/Build/source/texk/web2c/doc/install.texi new file mode 100644 index 00000000000..ac3329a83dc --- /dev/null +++ b/Build/source/texk/web2c/doc/install.texi @@ -0,0 +1,288 @@ +@ifclear version +@defcodeindex cm +@defcodeindex fl +@defcodeindex op +@end ifclear + +@node Installation +@chapter Installation + +@cindex configuration +@cindex compilation +@cindex installation + +@ifset version +(A copy of this chapter is in the distribution file @file{web2c/INSTALL}.) +@end ifset + +Installing Web2c is mostly the same as installing any other +Kpathsea-using program. Therefore, for the basic steps involved, +see @ref{Installation,,, kpathsea, Kpathsea}. (A copy is in the file +@file{kpathsea/INSTALL}.) + +One peculiarity to Web2c is that the source distribution comes in two +files: @file{web.tar.gz} and @file{web2c.tar.gz}. You must retrieve and +unpack them both. (We have two because the former archive contains the +very large and seldom-changing original WEB source files.) +@xref{unixtex.ftp,,, kpathsea, Kpathsea}. + +@pindex mpost@r{, reason for name change} +Another peculiarity is the MetaPost program. Although it has been +installed previously as @code{mp}, as of Web2c 7.0 the installed name is +now @code{mpost}, to avoid conflict with the @code{mp} program that does +prettyprinting. This approach was recommended by the MetaPost author, +John Hobby. If you as the @TeX{} administrator wish to make it +available under its shorter name as well, you will have to set up a link +or some such yourself. And of course individual users can do the same. + +For solutions to common installation problems and information on how to +report a bug, see the file @file{kpathsea/BUGS} (@pxref{Bugs,,, +kpathsea, Kpathsea}). See also the Web2c home page, +@url{http://www.tug.org/web2c}. + +Points worth repeating: + +@itemize @bullet +@item +@cindex directory structure +@cindex basic fonts and macros +@cindex fonts, basic +@cindex macros, basic +Before starting the standard compilation and installation you must +install the basic fonts, macros, and other library files. +@xref{Installation,,,kpathsea, Kpathsea}. + +@item +If you do not wish to use the standard file locations, see @ref{Changing +search paths,,, kpathsea, Kpathsea}. + +@item +Some Web2c features are enabled or disabled at @code{configure} time, +as described in the first section below. + +@end itemize + +@menu +* configure options:: Especially --with and --enable. +* Compile-time options:: Unusual -D's. +* Additional targets:: Breaking down the task. +* Triptrap:: Running the torture tests. +@end menu + + +@node configure options +@section @code{configure} options + +@cindex configuration, compile-time +@cindex compile-time options +@pindex configure --with/--enable @r{options} +This section gives pointers to descriptions of the @samp{--with} and +@samp{--enable} @code{configure} arguments that Web2c accepts. Some are +specific to Web2c, others are generic to all Kpathsea-using programs. + +For a list of all the options @code{configure} accepts, run +@samp{configure --help}. The generic options are listed first, and the +package-specific options come last. + +For a description of the generic options (which mainly allow you to +specify installation directories) and basic @code{configure} usage, +see @ref{Invoking configure,, Running @code{configure} scripts, autoconf, +Autoconf}, a copy is in the file @file{kpathsea/CONFIGURE}. + +@table @samp +@item --disable-dump-share +Do not make fmt/base/mem files sharable across different endian +architectures. @xref{Hardware and memory dumps}. + +@item --without-maketexmf-default +@itemx --without-maketexpk-default +@itemx --without-maketextfm-default +@itemx --with-maketextex-default +Enable or disable the dynamic generation programs. @xref{mktex +configuration,,, kpathsea, Kpathsea}. The defaults are the inverse of +the options, i.e., everything is enabled except @code{mktextex}. + +@item --enable-shared +Build Kpathsea as a shared library. @xref{Shared library,,, kpathsea, +Kpathsea}. + +@item --with-editor=@var{cmd} +Change the default editor invoked by the @samp{e} interactive command. +@xref{Editor invocation}. + +@item --with-epsfwin +@itemx --with-hp2627win +@itemx --with-mftalkwin +@itemx --with-nextwin +@itemx --with-regiswin +@itemx --with-suntoolswin +@itemx --with-tektronixwin +@itemx --with-unitermwin +@itemx --with-x +@itemx --with-x-toolkit=KIT +@itemx --with-x11win +@itemx --with-x11 +Define Metafont graphics support; by default, no graphics support is +enabled. @xref{Online Metafont graphics}. + +@item --x-includes=@var{dir} +@itemx --x-libraries=@var{dir} +Define the locations of the X11 include files and libraries; by default, +@code{configure} does its best to guess). @xref{Optional Features,,, +autoconf, Autoconf}. A copy is in @file{kpathsea/CONFIGURE}. +@end table + + +@node Compile-time options +@section Compile-time options + +@cindex compile-time options +@cindex @samp{#define} options +@opindex -D @r{compiler options} +In addition to the @code{configure} options listed in the previous +section, there are a few things that can be affected at compile-time +with C definitions, rather than with @code{configure}. Using any of +these is unusual. + +To specify extra compiler flags (@samp{-D@var{name}} in this case), the +simplest thing to do is: +@example +make XCFLAGS="@var{ccoptions}" +@end example +@noindent You can also set the @code{CFLAGS} environment variable before +running @code{configure}. @xref{configure environment,,, kpathsea, Kpathsea}. + +Anyway, here are the possibilities: + +@table @samp +@item -DFIXPT +@itemx -DNO_MF_ASM +@vindex FIXPT +@cindex fixed-point arithmetic +@cindex floating-point arithmetic +@cindex assembly language routines +@cindex fraction routines +Use the original WEB fixed-point routines for Metafont and MetaPost +arithmetic calculations regarding fractions. By default, +assembly-language routines are used on x86 hardware with GNU C (unless +@samp{NO_MF_ASM} is defined), and floating-point routines are used +otherwise. + +@item -DIPC_DEBUG +@vindex IPC_DEBUG +Report on various interprocess communication activities. @xref{IPC and +TeX,, IPC and @TeX{}}. +@end table + + +@node Additional targets +@section Additional targets + +@cindex additional Make targets +@cindex targets, additional Make +@cindex Make targets, additional + +Web2c has several Make targets besides the standard ones. You can invoke +these either in the top level directory of the source distribution (the +one containing @file{kpathsea/} and @file{web2c/}), or in the +@file{web2c/} directory. + +@table @samp +@item c-sources +@cmindex c-sources @r{Makefile target} +@cindex non-Unix system, compiling on +Make only the C files, translated from the Web sources, presumably +because you want to take them to a non-Unix machine. + +@item formats +@itemx install-formats +@cmindex formats @r{Make target} +@cmindex install-formats @r{Make target} +Make or install all the memory dumps (@pxref{Memory dumps}). By +default, the standard plain formats plus @file{latex.fmt} are made. You +can add other formats by redefining the @code{fmts}, @code{bases}, and +@code{mems} variables. See the top of @file{web2c/Makefile} for the +possibilities. + +@item fmts +@itemx install-fmts +@cmindex fmts @r{Make target} +@cmindex install-fmts @r{Make target} +Make or install the @TeX{} @file{.fmt} files. @xref{Initial TeX}. + +@item bases +@itemx install-bases +@cmindex bases @r{Make target} +@cmindex install-bases @r{Make target} + +Make or install the Metafont @file{.base} files. @xref{Initial Metafont}. + +@item mems +@itemx install-mems +@cmindex mems @r{Make target} +@cmindex install-mems @r{Make target} +Make or install the MetaPost @file{.mem} files. @xref{Initial MetaPost}. + +@item triptrap +@itemx trip +@itemx trap +@itemx mptrap +@cmindex triptrap @r{Make target} +@findex trip @r{Make target} +@findex trap @r{Make target} +@findex mptrap @r{Make target} +To run the torture tests for @TeX{}, Metafont, and MetaPost +(respectively). See the next section. + +@end table + + +@node Triptrap +@section Trip, trap, and mptrap: Torture tests + +@cindex Gruff, Billy Goat +@cindex trip test +@cindex trap test +@cindex mptrap test +@cindex torture tests + +@flindex tripman.tex +@flindex trapman.tex +@flindex mptrap.readme +To validate your @TeX{}, Metafont, and MetaPost executables, run +@samp{make triptrap}. This runs the trip, trap, and mptrap ``torture +tests''. See the files @file{triptrap/tripman.tex}, +@file{triptrap/trapman.tex}, and @file{triptrap/mptrap.readme} for +detailed information and background on the tests. + +The differences between your executables' behavior and the standard +values will show up on your terminal. The usual differences (these are +all acceptable) are: + +@itemize @bullet +@item string usage and table sizes; +@item glue set ratios; +@item @samp{down4}, @samp{right4}, and @samp{y4} commands in DVItype output; +@item dates and times. +@end itemize + +@noindent Any other differences are trouble. The most common culprit in +the past has been compiler bugs, especially when optimizing. +@xref{TeX or Metafont failing,, @TeX{} or Metafont failing, kpathsea, +Kpathsea}. + +The files @file{trip.diffs}, @file{mftrap.diffs}, and +@file{mptrap.diffs} in the @file{triptrap} directory show the standard +diffs against the original output. If you diff your diffs against these +files, you should come up clean. For example +@example +make trip >&mytrip.diffs +diff triptrap/trip.diffs mytrip.diffs +@end example + +To run the tests separately, use the targets @code{trip}, @code{trap}, +and @code{mptrap}. + +To run simple tests for all the programs as well as the torture tests, +run @samp{make check}. You can compare the output to the distributed +file @file{tests/check.log} if you like. diff --git a/Build/source/texk/web2c/doc/ref.txi b/Build/source/texk/web2c/doc/ref.txi new file mode 100644 index 00000000000..7c2dc6bc876 --- /dev/null +++ b/Build/source/texk/web2c/doc/ref.txi @@ -0,0 +1,118 @@ +@c begin{thebibliography}{Knu86d} + +@item [Bil87] +Neenie Billawala. +Write-white printing engines and tuning fonts with Metafont. +@cite{TUGboat}, 8(1):29--32, April 1987. +@url{https://tug.org/TUGboat/tb08-1/tb17billawala.pdf}. + +@item [Hob89] +John D. Hobby. +A Metafont-like system with PS output. +@cite{TUGboat}, 10(4):505--512, December 1989. +@url{https://tug.org/metapost}. + +@item [Hob92] +John D. Hobby. +A User's Manual for MetaPost. +Technical Report CSTR-162, AT&T Bell Laboratories, 1992. + +@item [Hob93] +John D. Hobby. +Drawing Graphs with MetaPost. +Technical Report CSTR-164, AT&T Bell Laboratories, 1993. + +@item [HS91] +Samuel P. Harbison and Guy L. Steele Jr. +@cite{C---A Reference Manual}. +Prentice-Hall, Upper Saddle River, NJ 07458, USA, third edition, 1991. +An authoritative reference to the C programming language, and a good + companion to Kernighan and Ritchie. + +@item [KL93] +Donald E. Knuth and Silvio Levy. +@cite{The CWEB System of Structured Documentation, Version 3.0}. +Addison-Wesley, Reading, MA, USA, 1993. +@url{https://ctan.org/pkg/cweb}. + +@item [Knu84] +Donald E. Knuth. +A torture test for @TeX{}. +Report No. STAN-CS-84-1027, Stanford University, Department of Computer + Science, 1984. + +@item [Knu86a] +Donald E. Knuth. +A Torture Test for METAFONT. +Report No. STAN-CS-86-1095, Stanford University, Department of Computer + Science, 1986. + +@item [Knu86b] +Donald E. Knuth. +@cite{The @TeX{}book}, volume A of @cite{Computers and Typesetting}. +Addison-Wesley, Reading, MA, USA, 1986. + +@item [Knu86c] +Donald E. Knuth. +@cite{@TeX{}: The Program}, volume B of @cite{Computers and Typesetting}. +Addison-Wesley, Reading, MA, USA, 1986. + +@item [Knu86d] +Donald E. Knuth. +@cite{The METAFONTbook}, volume C of @cite{Computers and Typesetting}. +Addison-Wesley, Reading, MA, USA, 1986. + +@item [Knu86e] +Donald E. Knuth. +@cite{METAFONT: The Program}, volume D of @cite{Computers and + Typesetting}. +Addison-Wesley, Reading, MA, USA, 1986. + +@item [Knu86f] +Donald E. Knuth. +@cite{Computer Modern Typefaces}, volume E of @cite{Computers and + Typesetting}. +Addison-Wesley, Reading, MA, USA, 1986. + +@item [Knu89] +Donald E. Knuth. +The errors of @TeX{}. +@cite{Software---Practice and Experience}, 19(7):607--681, July + 1989. +This is an updated version of Knuth:1988:ET. + +@item [Knu90] +Donald Knuth. +Virtual Fonts: More Fun for Grand Wizards. +@cite{TUGboat}, 11(1):13--23, April 1990. +@url{https://tug.org/TUGboat/tb11-1/tb27knut.pdf}. + +@item [Knu92] +Donald E. Knuth. +@cite{Literate Programming}. +CSLI Lecture Notes Number 27. Stanford University Center for the Study of + Language and Information, Stanford, CA, USA, 1992. + +@item [Lam94] +Leslie Lamport. +@cite{@LaTeX{}: A Document Preparation System: User's Guide and Reference + Manual}. +Addison-Wesley, Reading, MA, USA, second edition, 1994. +Reprinted with corrections, 1996. + +@item [Lia83] +Franklin Mark Liang. +Word hy-phen-a-tion by com-pu-ter. +Technical Report STAN-CS-83-977, Stanford University, August 1983. +@url{https://tug.org/docs/liang/liang-thesis.pdf}. + +@item [Mac91] +Pierre A. MacKay. +Looking at the pixels: Quality control for 300 dpi laser printer fonts, + especially Metafonts. +In Robert A. Morris and Jacques Andre, editors, @cite{Raster Imaging and + Digital Typography II---Papers from the second RIDT meeting, held in + Boston, Oct. 14--16, 1991}, pages 205--215, New York, 1991. Cambridge + University Press. + +@c end{thebibliography} diff --git a/Build/source/texk/web2c/doc/web2c.info b/Build/source/texk/web2c/doc/web2c.info new file mode 100644 index 00000000000..f287a96a42c --- /dev/null +++ b/Build/source/texk/web2c/doc/web2c.info @@ -0,0 +1,4587 @@ +This is web2c.info, produced by makeinfo version 6.7 from web2c.texi. + +This file documents the installation and use of the programs in Web2c, +an implementation of Donald Knuth's TeX system. + + Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, +2005, 2007, 2008, 2009, 2010-2021 Karl Berry & Olaf Weber. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation +INFO-DIR-SECTION TeX +START-INFO-DIR-ENTRY +* Web2c: (web2c). TeX, Metafont, and companion programs. +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* bibtex: (web2c)bibtex invocation. Maintaining bibliographies. +* dvicopy: (web2c)dvicopy invocation. Virtual font expansion +* dvitomp: (web2c)dvitomp invocation. DVI to MPX (MetaPost pictures). +* dvitype: (web2c)dvitype invocation. DVI to human-readable text. +* gftodvi: (web2c)gftodvi invocation. Generic font proofsheets. +* gftopk: (web2c)gftopk invocation. Generic to packed fonts. +* gftype: (web2c)gftype invocation. GF to human-readable text. +* mf: (web2c)mf invocation. Creating typeface families. +* mft: (web2c)mft invocation. Prettyprinting Metafont source. +* mltex: (web2c)MLTeX. Multi-lingual TeX. +* mpost: (web2c)mpost invocation. Generating PostScript. +* patgen: (web2c)patgen invocation. Creating hyphenation patterns. +* pktogf: (web2c)pktogf invocation. Packed to generic fonts. +* pktype: (web2c)pktype invocation. PK to human-readable text. +* pltotf: (web2c)pltotf invocation. Property list to TFM. +* pooltype: (web2c)pooltype invocation. Display WEB pool files. +* tangle: (web2c)tangle invocation. WEB to Pascal. +* tex: (web2c)tex invocation. Typesetting. +* tftopl: (web2c)tftopl invocation. TFM -> property list. +* vftovp: (web2c)vftovp invocation. Virtual font -> virtual pl. +* vptovf: (web2c)vptovf invocation. Virtual pl -> virtual font. +* weave: (web2c)weave invocation. WEB to TeX. +END-INFO-DIR-ENTRY + + +File: web2c.info, Node: Top, Next: Introduction, Up: (dir) + +Web2c +***** + +This document describes how to install and use the programs in the Web2c +implementation of the TeX system, especially for Unix systems. It +corresponds to Web2c version 2021, released in February 2021. + +* Menu: + +* Introduction:: A brief introduction. +* Installation:: How to compile and install Web2c. +* Commonalities:: Option syntax, standard options, memory dumps. +* Three programs:: TeX, Metafont, MetaPost have much in common. +* TeX:: Typesetting. +* Metafont:: Typeface design. +* MetaPost:: Technical illustrations. +* BibTeX:: Reusable bibliographies. +* WEB:: Literate programming. +* DVI utilities:: DVI expansion. +* Font utilities:: Font format conversion. +* Legalisms:: Blah blah blah. +* References:: Books and such. +* Index:: General index. + + +File: web2c.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top + +1 Introduction +************** + +This manual corresponds to version 2021 of Web2c, released in February +2021. + + "Web2c" is the name of a TeX implementation, originally for Unix, but +now also running under various operating systems. By "TeX +implementation", we mean all of the standard programs developed by the +Stanford TeX project directed by Donald E. Knuth: Metafont, DVItype, +GFtoDVI, BibTeX, Tangle, etc., as well as TeX itself. Other programs +are also included: DVIcopy, written by Peter Breitenlohner, MetaPost and +its utilities (derived from Metafont), by John Hobby, etc. + + General strategy: Web2c works, as its name implies, by translating +the WEB source in which TeX is written into C source code. Its output +is not self-contained, however; it makes extensive use of many macros +and functions in a library (the 'web2c/lib' directory in the sources). +Therefore, it will not work without change on an arbitrary WEB program. + + Availability: All of Web2c is freely available--"free" both in the +sense of no cost (free ice cream) and of having the source code to +modify and/or redistribute (free speech). *Note +(kpathsea)unixtex.ftp::, for the practical details of how to obtain +Web2c. + + Different parts of the Web2c distribution have different licensing +terms, however, reflecting the different circumstances of their +creation; consult each source file for exact details. The main +practical implication for redistributors of Web2c is that most of the +executables are covered by the GNU General Public License or GNU Lesser +General Public License, and therefore anyone who gets a binary +distribution must also be able to get the sources, as explained by the +terms of the GPL (<https://gnu.org/licenses/>. The GPL covers the Web2c +executables, including 'tex', because the Free Software Foundation +sponsored the initial development of the Kpathsea library that Web2c +uses. The basic source files from Stanford, however, have their own +copyright terms or are in the public domain, and are not covered by the +GPL. + + History: Tomas Rokicki originated the TeX-to-C system in 1987, +working from the first change files for TeX under Unix, which were done +primarily by Howard Trickey and Pavel Curtis. Tim Morgan then took over +development and maintenance for a number of years; the name changed to +Web-to-C somewhere in there. In 1990, Karl Berry became the maintainer. +He made many changes to the original sources, and started using the +shorter name Web2c. In 1997, Olaf Weber took over, and then in 2006, +Karl started taking care of it again. No significant development or +changes have been needed for many years. Dozens of other people have +contributed; their names are listed in the 'ChangeLog' files. + + Other acknowledgements by Karl: The University of Massachusetts at +Boston (particularly Rick Martin and Bob Morris) provided computers and +ftp access to me for many years. Richard Stallman at the Free Software +Foundation employed me while I wrote the original path searching library +(for the GNU font utilities). (rms also gave us Emacs, GDB, and GCC, +without which I cannot imagine developing Web2c.) And, of course, TeX +would not exist in the first place without Donald E. Knuth. + + Further reading: *Note References::. + + +File: web2c.info, Node: Installation, Next: Commonalities, Prev: Introduction, Up: Top + +2 Installation +************** + +(A copy of this chapter is in the distribution file 'web2c/INSTALL'.) + + Installing Web2c is mostly the same as installing any other +Kpathsea-using program. Therefore, for the basic steps involved, see +*note (kpathsea)Installation::. (A copy is in the file +'kpathsea/INSTALL'.) + + One peculiarity to Web2c is that the source distribution comes in two +files: 'web.tar.gz' and 'web2c.tar.gz'. You must retrieve and unpack +them both. (We have two because the former archive contains the very +large and seldom-changing original WEB source files.) *Note +(kpathsea)unixtex.ftp::. + + Another peculiarity is the MetaPost program. Although it has been +installed previously as 'mp', as of Web2c 7.0 the installed name is now +'mpost', to avoid conflict with the 'mp' program that does +prettyprinting. This approach was recommended by the MetaPost author, +John Hobby. If you as the TeX administrator wish to make it available +under its shorter name as well, you will have to set up a link or some +such yourself. And of course individual users can do the same. + + For solutions to common installation problems and information on how +to report a bug, see the file 'kpathsea/BUGS' (*note (kpathsea)Bugs::). +See also the Web2c home page, <http://www.tug.org/web2c>. + + Points worth repeating: + + * Before starting the standard compilation and installation you must + install the basic fonts, macros, and other library files. *Note + (kpathsea)Installation::. + + * If you do not wish to use the standard file locations, see *note + (kpathsea)Changing search paths::. + + * Some Web2c features are enabled or disabled at 'configure' time, as + described in the first section below. + +* Menu: + +* configure options:: Especially -with and -enable. +* Compile-time options:: Unusual -D's. +* Additional targets:: Breaking down the task. +* Triptrap:: Running the torture tests. + + +File: web2c.info, Node: configure options, Next: Compile-time options, Up: Installation + +2.1 'configure' options +======================= + +This section gives pointers to descriptions of the '--with' and +'--enable' 'configure' arguments that Web2c accepts. Some are specific +to Web2c, others are generic to all Kpathsea-using programs. + + For a list of all the options 'configure' accepts, run 'configure +--help'. The generic options are listed first, and the package-specific +options come last. + + For a description of the generic options (which mainly allow you to +specify installation directories) and basic 'configure' usage, see *note +Running 'configure' scripts: (autoconf)Invoking configure, a copy is in +the file 'kpathsea/CONFIGURE'. + +'--disable-dump-share' + Do not make fmt/base/mem files sharable across different endian + architectures. *Note Hardware and memory dumps::. + +'--without-maketexmf-default' +'--without-maketexpk-default' +'--without-maketextfm-default' +'--with-maketextex-default' + Enable or disable the dynamic generation programs. *Note + (kpathsea)mktex configuration::. The defaults are the inverse of + the options, i.e., everything is enabled except 'mktextex'. + +'--enable-shared' + Build Kpathsea as a shared library. *Note (kpathsea)Shared + library::. + +'--with-editor=CMD' + Change the default editor invoked by the 'e' interactive command. + *Note Editor invocation::. + +'--with-epsfwin' +'--with-hp2627win' +'--with-mftalkwin' +'--with-nextwin' +'--with-regiswin' +'--with-suntoolswin' +'--with-tektronixwin' +'--with-unitermwin' +'--with-x' +'--with-x-toolkit=KIT' +'--with-x11win' +'--with-x11' + Define Metafont graphics support; by default, no graphics support + is enabled. *Note Online Metafont graphics::. + +'--x-includes=DIR' +'--x-libraries=DIR' + Define the locations of the X11 include files and libraries; by + default, 'configure' does its best to guess). *Note + (autoconf)Optional Features::. A copy is in 'kpathsea/CONFIGURE'. + + +File: web2c.info, Node: Compile-time options, Next: Additional targets, Prev: configure options, Up: Installation + +2.2 Compile-time options +======================== + +In addition to the 'configure' options listed in the previous section, +there are a few things that can be affected at compile-time with C +definitions, rather than with 'configure'. Using any of these is +unusual. + + To specify extra compiler flags ('-DNAME' in this case), the simplest +thing to do is: + make XCFLAGS="CCOPTIONS" +You can also set the 'CFLAGS' environment variable before running +'configure'. *Note (kpathsea)configure environment::. + + Anyway, here are the possibilities: + +'-DFIXPT' +'-DNO_MF_ASM' + Use the original WEB fixed-point routines for Metafont and MetaPost + arithmetic calculations regarding fractions. By default, + assembly-language routines are used on x86 hardware with GNU C + (unless 'NO_MF_ASM' is defined), and floating-point routines are + used otherwise. + +'-DIPC_DEBUG' + Report on various interprocess communication activities. *Note IPC + and TeX: IPC and TeX. + + +File: web2c.info, Node: Additional targets, Next: Triptrap, Prev: Compile-time options, Up: Installation + +2.3 Additional targets +====================== + +Web2c has several Make targets besides the standard ones. You can +invoke these either in the top level directory of the source +distribution (the one containing 'kpathsea/' and 'web2c/'), or in the +'web2c/' directory. + +'c-sources' + Make only the C files, translated from the Web sources, presumably + because you want to take them to a non-Unix machine. + +'formats' +'install-formats' + Make or install all the memory dumps (*note Memory dumps::). By + default, the standard plain formats plus 'latex.fmt' are made. You + can add other formats by redefining the 'fmts', 'bases', and 'mems' + variables. See the top of 'web2c/Makefile' for the possibilities. + +'fmts' +'install-fmts' + Make or install the TeX '.fmt' files. *Note Initial TeX::. + +'bases' +'install-bases' + + Make or install the Metafont '.base' files. *Note Initial + Metafont::. + +'mems' +'install-mems' + Make or install the MetaPost '.mem' files. *Note Initial + MetaPost::. + +'triptrap' +'trip' +'trap' +'mptrap' + To run the torture tests for TeX, Metafont, and MetaPost + (respectively). See the next section. + + +File: web2c.info, Node: Triptrap, Prev: Additional targets, Up: Installation + +2.4 Trip, trap, and mptrap: Torture tests +========================================= + +To validate your TeX, Metafont, and MetaPost executables, run 'make +triptrap'. This runs the trip, trap, and mptrap "torture tests". See +the files 'triptrap/tripman.tex', 'triptrap/trapman.tex', and +'triptrap/mptrap.readme' for detailed information and background on the +tests. + + The differences between your executables' behavior and the standard +values will show up on your terminal. The usual differences (these are +all acceptable) are: + + * string usage and table sizes; + * glue set ratios; + * 'down4', 'right4', and 'y4' commands in DVItype output; + * dates and times. + +Any other differences are trouble. The most common culprit in the past +has been compiler bugs, especially when optimizing. *Note TeX or +Metafont failing: (kpathsea)TeX or Metafont failing. + + The files 'trip.diffs', 'mftrap.diffs', and 'mptrap.diffs' in the +'triptrap' directory show the standard diffs against the original +output. If you diff your diffs against these files, you should come up +clean. For example + make trip >&mytrip.diffs + diff triptrap/trip.diffs mytrip.diffs + + To run the tests separately, use the targets 'trip', 'trap', and +'mptrap'. + + To run simple tests for all the programs as well as the torture +tests, run 'make check'. You can compare the output to the distributed +file 'tests/check.log' if you like. + + +File: web2c.info, Node: Commonalities, Next: Three programs, Prev: Installation, Up: Top + +3 Commonalities +*************** + +Many aspects of the TeX system are the same among more than one program, +so we describe those pieces together, here. + +* Menu: + +* Option conventions:: - or -, = or ' ' for values. +* Common options:: -help -version -verbose, and TeX/MF/MP options. +* Path searching:: Features of the common path searching library. +* Output file location:: TEXMFOUTPUT allows output in places other than '.'. + + +File: web2c.info, Node: Option conventions, Next: Common options, Up: Commonalities + +3.1 Option conventions +====================== + +To provide a clean and consistent behavior, we chose to have all these +programs use the GNU function 'getopt_long_only' to parse command lines. +However, we do use in a restricted mode, where all the options have to +come before the rest of the arguments. + + As a result, you can: + * use '-' or '--' to start an option name; + + * use any unambiguous abbreviation for an option name; + + * separate option names and values with either '=' or one or more + spaces; + + * use filenames that would otherwise look like options by putting + them after an option '--'. + + By convention, non-option arguments, if specified, generally define +the name of an input file, as documented for each program. + + If a particular option with a value is given more than once, it is +the last value that counts. + + For example, the following command line specifies the options 'foo', +'bar', and 'verbose'; gives the value 'baz' to the 'abc' option, and the +value 'xyz' to the 'quux' option; and specifies the filename '-myfile-'. + + -foo --bar -verb -abc=baz -quux karl --quux xyz -- -myfile- + + +File: web2c.info, Node: Common options, Next: Path searching, Prev: Option conventions, Up: Commonalities + +3.2 Common options +================== + +All of these programs accept the standard GNU '--help' and '--version' +options, and several programs accept '--verbose'. Rather than writing +identical descriptions for every program, they are described here. + +'--help' + Print a usage message listing basic usage and all available options + to standard output, then exit successfully. + +'--verbose' + Print progress reports to standard output. + +'--version' + Print the version number to standard output, then exit + successfully. + + TeX, Metafont, and MetaPost have a number of additional options in +common: + +'-cnf-line=STR' + Parse STR as if it were a line in the 'texmf.cnf' configuration + file, overriding all other settings. *Note (kpathsea)Path + searching options::. + +'-file-line-error' +'-no-file-line-error' + Change (or do not change) the way error messages are printed. The + alternate style looks like error messages from many compilers and + is easier to parse for some editors that invoke TeX. This option + used to be called '-file-line-error-style'. + +'-fmt=DUMPNAME' +'-base=DUMPNAME' +'-mem=DUMPNAME' + Use DUMPNAME instead of the program name or a '%&' line to + determine the name of the memory dump file read ('fmt' for TeX, + 'base' for Metafont, 'mem' for MetaPost). *Note Memory dumps::. + Also sets the program name to DUMPNAME if no '-progname' option was + given. + +'-halt-on-error' + Stop processing and exit when an error occurs, as opposed to the + normal process of trying to recover and continue. + +'-ini' + Enable the "initial" form of the program (*note Initial and + virgin::). This is implicitly set if the program name is 'initex' + resp. 'inimf'. + +'-interaction=STRING' + Set the interaction mode from the command line. The STRING must be + one of 'batchmode', 'nonstopmode', 'scrollmode', or + 'errorstopmode'. + +'-jobname=STRING' + Set the job name to STRING, instead of deriving it from the name of + the input file. + +'-kpathsea-debug=NUMBER' + Set path searching debugging flags according to the bits of NUMBER + (*note (kpathsea)Debugging::). You can also specify this in + 'KPATHSEA_DEBUG' environment variable (for all Web2c programs). + (The command line value overrides.) The most useful value is '-1', + to get all available output. + +'-output-directory=DIRNAME' + Specify the directory DIRNAME to which output files are written. + Also look for input files in DIRNAME first, before looking along + the normal search path. *Note Output file location::. + +'-parse-first-line' +'-no-parse-first-line' + Check or disable checking whether the first line of the main input + file starts with '%&', and parse it if it does. This line can be + used specify the format and/or a TCX file. + +'-progname=STRING' + Set program (and memory dump) name to STRING. This may affect the + search paths and other values used (*note (kpathsea)Config + files::). Using this option is equivalent to making a link named + STRING to the binary and then invoking the binary under that name. + *Note Memory dumps::. + +'-recorder' + Enable the filename recorder. This makes the program save a list + of the opened files into a file with (by default) extension '.fls'. + For Aleph, this option is always on, and the file has extension + '.ofl'. + + Ordinarily, the '.fls' file is written to the same location as the + '.log' file, for example, respecting '-output-directory' if it is + given (*note Output file location::). However, if TeX processing + is done on the command line (or in response to the '**' prompt), + the '.fls' might be written to the current directory, or include an + integer (the current pid), as in 'texput1234.fls'. You can use + '-jobname' to explicitly set the basename. + +'-translate-file=TCXFILE' + Use TCXFILE to define which characters are printable and + translations between the internal and external character sets. + Moreover, TCXFILE can be explicitly declared in the first line of + the main input file '%& -translate-file=TCXFILE'. This is the + recommended method for portability reasons. *Note TCX files::. + +'-8bit' + This option specifies that by default all characters should be + considered printable. If '-translate-file' was given as well, then + the TCX file may mark characters as non-printable. This is a no-op + in engines natively supporting Unicode. + + +File: web2c.info, Node: Path searching, Next: Output file location, Prev: Common options, Up: Commonalities + +3.3 Path searching +================== + +All of the Web2c programs, including TeX, which do path searching use +the Kpathsea routines to do so. The precise names of the environment +and configuration file variables which get searched for particular file +formatted are therefore documented in the Kpathsea manual (*note +(kpathsea)Supported file formats::). Reading 'texmf.cnf' (*note +(kpathsea)Config files::), invoking 'mktex...' scripts (*note +(kpathsea)mktex scripts::), and so on are all handled by Kpathsea. + + The programs which read fonts make use of another Kpathsea feature: +'texfonts.map', which allows arbitrary aliases for the actual names of +font files; for example, 'Times-Roman' for 'ptmr8r.tfm'. The +distributed (and installed by default) 'texfonts.map' includes aliases +for many widely available PostScript fonts by their PostScript names. + + +File: web2c.info, Node: Output file location, Prev: Path searching, Up: Commonalities + +3.4 Output file location +======================== + +All the programs generally follow the usual convention for output files. +Namely, they are placed in the directory current when the program is +run, regardless of any input file location; or, in a few cases, output +is to standard output. + + For example, if you run 'tex /tmp/foo', for example, the output will +be in './foo.dvi' and './foo.log', not '/tmp/foo.dvi' and +'/tmp/foo.log'. + + You can use the '-output-directory' option to cause all output files +that would normally be written in the current directory to be written in +the specified directory instead. *Note Common options::. + + If the current directory is not writable, and '-output-directory' is +not specified, the main programs (TeX, Metafont, MetaPost, and BibTeX) +make an exception: if the config file or environment variable value +'TEXMFOUTPUT' is set (it is not by default), output files are written to +the directory specified. + + 'TEXMFOUTPUT' is also checked for input files, as TeX often generates +files that need to be subsequently read; for input, no suffixes (such as +'.tex') are added by default and no exhaustive path searching is done, +the input name is simply checked as given. + + +File: web2c.info, Node: Three programs, Next: TeX, Prev: Commonalities, Up: Top + +4 Three programs: Metafont, MetaPost, and TeX +********************************************* + +TeX, Metafont, and MetaPost have a number of features in common. +Besides the ones here, command-line options and other commonalities are +described in the previous section. + +* Menu: + +* Runtime options:: The 'texmf.cnf' configuration file. +* Initial and virgin:: Making memory dumps vs. production runs. +* Memory dumps:: .fmt/.base files for fast startup. +* Editor invocation:: The 'e' response at errors. +* \input filenames:: Filename delimiters and Kpathsea expansion. + + +File: web2c.info, Node: Runtime options, Next: Initial and virgin, Up: Three programs + +4.1 Runtime options +=================== + +Besides the configure- and compile-time options described in the +installation section (*note Installation::), you can control a number of +parameters in the 'texmf.cnf' runtime file read by Kpathsea (*note +(kpathsea)Config files::). + + The main purpose of 'texmf.cnf' is to specify search paths, but array +sizes and other options are also set there. Most are rather obscure. +Here are a few of the more interesting values: + +'main_memory' + Total words of memory available, for TeX, Metafont, and MetaPost. + Must remake the format file after changing. + +'extra_mem_bot' + Extra space for "large" TeX data structures (default 0): boxes, + glue, breakpoints, et al. If you use PiCTeX, you may well want to + set this. + +'expand_depth' + Limit on recursive expansion calls before TeX aborts (default + 10000). If a TeX program does an unterminated recursive expansion, + TeX will dutifully expand macros until the system's runtime stack + overflows, typically with a segmentation fault (SIGSEGV). This + parameter was introduced to minimize the chance of that unpleasant + (though not dangerous) crash, instead allowing TeX to quit with a + more informative message. + + The crash can still happen, though, if the system has an + exceptionally small memory allocation for its stack. There is no + quantitative way to determine the limit, and it does not seem worth + implementing system-dependent heuristics to guess at the number, + since it's highly improbable that any real TeX code will ever need + more than 10000 recursive expansions (it has never happened). For + the same reason, using the libsigsegv library + (<https://gnu.org/s/libsigsegv>) does not seem worth the effort. + +'texmf_casefold_search' + *Note (kpathsea)Casefolding search::. + + Ideally all arrays would be dynamically expanded as necessary, so the +only limiting factor would be the amount of swap space available, or +some configurable limit much larger than can currently be supported. + + Unfortunately, implementing this is extremely difficult, as the fixed +size of arrays is assumed in many places throughout the source code. +These runtime limits are a practical compromise between the compile-time +limits in previous versions, and truly dynamic arrays. (On the other +hand, the Web2c BibTeX implementation does do true dynamic reallocation +of some arrays.) + + Nowadays there is rarely a reason to modify the values. But if you +do wish to modify 'texmf.cnf', in TeX Live the best approach is to put +your changes, and only your changes at the top of the TL installation +tree. That is, if the system 'texmf.cnf' is installed in +'/some/path/to/texlive/YYYY/texmf-dist/web2c/texmf.cnf' is put your +custom settings in '/some/path/to/texlive/YYY/texmf.cnf', where YYYY is +the year of installation (if you use that subdirectory; it's the +default). That way, unrelated changes to the system 'texmf.cnf' can +happen with normal updates, without affecting your local values. + + +File: web2c.info, Node: Initial and virgin, Next: Memory dumps, Prev: Runtime options, Up: Three programs + +4.2 Initial and virgin +====================== + +The TeX and Metafont programs each have two main variants, called +"initial" and "virgin". MetaPost no longer makes this distinction. + + The initial form is enabled if: + 1. the '-ini' option was specified; or + 2. the program name is 'initex' resp. 'inimf'; or + 3. the first line of the main input file is '%&ini'; +otherwise, the virgin form is used. + + The "virgin" form is the one generally invoked for production use. +The first thing it does is read a memory dump (*note Determining the +memory dump to use::), and then proceeds on with the main job. + + The "initial" form is generally used only to create memory dumps (see +the next section). It starts up more slowly than the virgin form, +because it must do lengthy initializations that are encapsulated in the +memory dump file. + + +File: web2c.info, Node: Memory dumps, Next: Editor invocation, Prev: Initial and virgin, Up: Three programs + +4.3 Memory dumps +================ + +In typical use, TeX and Metafont require a large number of macros to be +predefined; therefore, they support "memory dump" files, which can be +read much more efficiently than ordinary source code. + +* Menu: + +* Creating memory dumps:: +* Determining the memory dump to use:: +* Hardware and memory dumps:: + + +File: web2c.info, Node: Creating memory dumps, Next: Determining the memory dump to use, Up: Memory dumps + +4.3.1 Creating memory dumps +--------------------------- + +The programs all create memory dumps in slightly idiosyncratic (thought +substantially similar) way, so we describe the details in separate +sections (references below). The basic idea is to run the initial +version of the program (*note Initial and virgin::), read the source +file to define the macros, and then execute the '\dump' primitive. + + Also, each program uses a different filename extension for its memory +dumps, since although they are completely analogous they are not +interchangeable (TeX cannot read a Metafont memory dump, for example). + + Here is a list of filename extensions with references to examples of +creating memory dumps: + +TeX + ('.fmt') *Note Initial TeX: Initial TeX. + +Metafont + ('.base') *Note Initial Metafont::. + + When making memory dumps, the programs read environment variables and +configuration files for path searching and other values as usual. If +you are making a new installation and have environment variables +pointing to an old one, for example, you will probably run into +difficulties. + + +File: web2c.info, Node: Determining the memory dump to use, Next: Hardware and memory dumps, Prev: Creating memory dumps, Up: Memory dumps + +4.3.2 Determining the memory dump to use +---------------------------------------- + +The virgin form (*note Initial and virgin::) of each program always +reads a memory dump before processing normal source input. All three +programs determine the memory dump to use in the same way: + + 1. If the first non-option command-line argument begins with '&', the + program uses the remainder of that argument as the memory dump + name. For example, running 'tex \&super' reads 'super.fmt'. (The + backslash protects the '&' against interpretation by the shell.) + + 2. If the '-fmt' resp. '-base' option is specified, its value is used. + + 3. If the '-progname' option is specified, its value is used. + + 4. If the first line of the main input file (which must be specified + on the command line, not in response to '**') is '%&DUMP', and DUMP + is an existing memory dump of the appropriate type, DUMP is used. + + The first line of the main input file can also specify which + character translation file is to be used: + '%&-translate-file=TCXFILE' (*note TCX files::). + + These two roles can be combined: '%&DUMP -translate-file=TCXFILE'. + If this is done, the name of the dump must be given first. + + 5. Otherwise, the program uses the program invocation name, most + commonly 'tex' resp. 'mf'. For example, if 'latex' is a link to + 'tex', and the user runs 'latex foo', 'latex.fmt' will be used. + + +File: web2c.info, Node: Hardware and memory dumps, Prev: Determining the memory dump to use, Up: Memory dumps + +4.3.3 Hardware and memory dumps +------------------------------- + +By default, memory dump files are generally sharable between +architectures of different types; specifically, on machines of different +endianness (*note (libc)Byte order::). (This is a feature of the Web2c +implementation, and is not true of all TeX implementations.) If you +specify '--disable-dump-share' to 'configure', however, memory dumps +will be endian-dependent. + + The reason to do this is speed. To achieve endian-independence, the +reading of memory dumps on LittleEndian architectures, such as PC's and +DEC architectures, is somewhat slowed (all the multibyte values have to +be swapped). Usually, this is not noticeable, and the advantage of +being able to share memory dumps across all platforms at a site far +outweighs the speed loss. But if you're installing Web2c for use on +LittleEndian machines only, perhaps on a PC being used only by you, you +may wish to get maximum speed. + + TeXnically, even without '--disable-dump-share', sharing of '.fmt' +files cannot be guaranteed to work. Floating-point values are always +written in native format, and hence will generally not be readable +across platforms. Fortunately, TeX uses floating point only to +represent glue ratios, and all common formats (plain, LaTeX, AMSTeX, +...) do not do any glue setting at '.fmt'-creation time. Metafont does +not use floating point in any dumped value at all. + + Incidentally, different memory dump files will never compare equal +byte-for-byte, because the program always dumps the current date and +time. So don't be alarmed by just a few bytes difference. + + If you don't know what endianness your machine is, and you're +curious, here is a little C program to tell you. (The 'configure' +script contains a similar program.) This is from the book 'C: A +Reference Manual', by Samuel P. Harbison and Guy L. Steele Jr. (*note +References::). + + main () + { + /* Are we little or big endian? From Harbison&Steele. */ + union + { + long l; + char c[sizeof (long)]; + } u; + u.l = 1; + if (u.c[0] == 1) + printf ("LittleEndian\n"); + else if (u.c[sizeof (long) - 1] == 1) + printf ("BigEndian\n"); + else + printf ("unknownEndian"); + + exit (u.c[sizeof (long) - 1] == 1); + } + + +File: web2c.info, Node: Editor invocation, Next: \input filenames, Prev: Memory dumps, Up: Three programs + +4.4 Editor invocation +===================== + +TeX, Metafont, and MetaPost all (by default) stop and ask for user +intervention at an error. If the input came from a file, and the user +responds with 'e' or 'E', the program invokes an editor. + + Specifying '--with-editor=CMD' to 'configure' sets the default editor +command string to CMD. The environment variables/configuration values +'TEXEDIT', 'MFEDIT', and 'MPEDIT' (respectively) override this. If +'--with-editor' is not specified, the default is 'vi +%d %s' on Unix, +and an invocation of the TeXworks editor on Windows. (See 'texmf.cnf' +for the precise values.) + + In this string, '%d' is replaced by the line number of the error, and +'%s' is replaced by the name of the current input file. + + +File: web2c.info, Node: \input filenames, Prev: Editor invocation, Up: Three programs + +4.5 '\input' filenames +====================== + +TeX, Metafont, and MetaPost source programs can all read other source +files with the '\input' (TeX) and 'input' (MF and MP) primitives: + \input NAME % in TeX + + The file NAME can always be terminated with whitespace; for Metafont +and MetaPost, the statement terminator ';' also works. (LaTeX and other +macro packages provide other interfaces to '\input' that allow different +notation; here we are concerned only with the primitive operation.) + + As (allowed) extensions to standard TeX, Web2c also supports +specifying the filename in double quotes ('"some name"') and in braces +('{"some name"}'), which is convenient for filenames containing spaces +or other special characters, as described in the sections below. + + In all cases, space tokens are ignored after the filename is read. + + Also, double quote ('"') characters are ignored within the filename; +there is no way to read files whose names contain a '"'. + + However, for maximal portability of your document across systems, use +only the characters 'a'-'z', '0'-'9', and at most one '.'. Do not use +anything but simple filenames, since directory separators vary among +systems; instead, add the necessary directories to the appropriate +search path. + +* Menu: + +* Quotes: \input quoted filename. \input "some name" +* Braces: \input braced filename. \input {some name} +* Caveats: \input filename caveats. Tokenization, nulls, Kpathsea expansion. + + +File: web2c.info, Node: \input quoted filename, Next: \input braced filename, Up: \input filenames + +4.5.1 '\input' quoted filename: '\input "some name"' +---------------------------------------------------- + +As of Web2c version 7.5.3 (2004), double-quote characters can be used to +include spaces or other special characters. In typical use, the '"' +characters surround the entire filename: + \input "filename with spaces" + + Technically, the quote characters can be used inside the name, and +can enclose any characters, as in: + \input filename" "with" "spaces + + One more point. In LaTeX, the quotes are needed inside the braces of +its '\input' macro, thus: + \input{a b} % fails + \input{"a b"} % ok + + There is no way to quote the quote character. + + +File: web2c.info, Node: \input braced filename, Next: \input filename caveats, Prev: \input quoted filename, Up: \input filenames + +4.5.2 '\input' braced filename: '\input{some name}' +--------------------------------------------------- + +As of Web2c 2020, '\input' filenames in TeX engines (this does not apply +in Metafont and MetaPost) can also be specified within a TeX group, +typically curly braces. For example: + \input{filename with spaces} + + As always with TeX, the brace characters are not hardwired; what +counts is the category code: the first token after the '\input' must be +of catcode 1 (begin group), and it is matched with the next character of +catcode 2 (end group). + + Within the group-delimited filename, braces are treated as normal +characters. + + As with all forms of filenames, following spaces are ignored (after +the end group), and double quote ('"') characters are ignored within the +filename. + + +File: web2c.info, Node: \input filename caveats, Prev: \input braced filename, Up: \input filenames + +4.5.3 '\input' filename caveats +------------------------------- + +The quoting mechanisms just described come into play _after_ TeX has +tokenized and expanded the input. So, multiple spaces and tabs will +generally be seen as a single space, active characters such as '~' are +expanded first (generally causing an error), and so on. More examples +below. + + On the other hand, various C library routines and Unix itself use the +null byte (character code zero, ASCII NUL) to terminate strings. So +filenames in Web2c cannot contain nulls, even though TeX itself does not +treat NUL specially. + + Finally, the present Web2c implementation does '~' and '$' expansion +on NAME, unlike Knuth's original implementation. Thus: + \input ~jsmith/$foo.bar + will dereference the environment variable or Kpathsea config file +value 'foo' and read that file, extended with '.bar', in user 'jsmith''s +home directory. You can also use braces in the variable expansion, as +in '${foo}bar', if you want to follow the variable name with a letter, +numeral, or '_'. + + (So another way to get a program to read a filename containing +whitespace is to define an environment variable and dereference it.) + + In all the common TeX formats (plain TeX, LaTeX, ConTeXt, AMSTeX, +...), the characters '~' and '$' have special category codes, so to +actually use these in a document you have to change their catcodes or +use '\string'. + + +File: web2c.info, Node: TeX, Next: Metafont, Prev: Three programs, Up: Top + +5 TeX: Typesetting +****************** + +TeX is a typesetting system: it was especially designed to handle +complex mathematics, as well as most ordinary text typesetting. + + TeX is a batch language, like C or Pascal, and not an interactive +"word processor": you compile a TeX input file into a corresponding +device-independent (DVI) file (and then translate the DVI file to the +commands for a particular output device). This approach has both +considerable disadvantages and considerable advantages. For a complete +description of the TeX language, see 'The TeXbook' (*note References::). +Many other books on TeX, introductory and otherwise, are available. + +* Menu: + +* tex invocation:: Invoking TeX. +* Initial TeX:: Making format files. +* Formats:: Major TeX macro packages. +* Languages and hyphenation:: TeX supports many human languages. +* Shell escapes:: Running subprograms from TeX. +* IPC and TeX:: DVI output to a socket. +* TeX extensions:: Additional engines with additional features. + + +File: web2c.info, Node: tex invocation, Next: Initial TeX, Up: TeX + +5.1 'tex' invocation +==================== + +TeX (usually invoked as 'tex') formats the given text and commands, and +outputs a corresponding device-independent representation of the typeset +document. This section merely describes the options available in the +Web2c implementation. For a complete description of the TeX typesetting +language, see 'The TeXbook' (*note References::). + + TeX, Metafont, and MetaPost process the command line (described here) +and determine their memory dump (fmt) file in the same way (*note Memory +dumps::). Synopses: + + tex [OPTION]... [TEXNAME[.tex]] [TEX-COMMANDS] + tex [OPTION]... \FIRST-LINE + tex [OPTION]... &FMT ARGS + + TeX searches the usual places for the main input file TEXNAME (*note +(kpathsea)Supported file formats::), extending TEXNAME with '.tex' if +necessary. To see all the relevant paths, set the environment variable +'KPATHSEA_DEBUG' to '-1' before running the program. + + After TEXNAME is read, TeX processes any remaining TEX-COMMANDS on +the command line as regular TeX input. Also, if the first non-option +argument begins with a TeX escape character (usually '\'), TeX processes +all non-option command-line arguments as a line of regular TeX input. + + If no arguments or options are specified, TeX prompts for an input +file name with '**'. + + TeX writes the main DVI output to the file 'BASETEXNAME.dvi', where +BASETEXNAME is the basename of TEXNAME, or 'texput' if no input file was +specified. A DVI file is a device-independent binary representation of +your TeX document. The idea is that after running TeX, you translate +the DVI file using a separate program to the commands for a particular +output device, such as a PostScript printer (*note Introduction: +(dvips)Top.) or an X Window System display (see xdvi(1)). + + TeX also reads TFM files for any fonts you load in your document with +the '\font' primitive. By default, it runs an external program named +'mktextfm' to create any nonexistent TFM files. You can disable this at +configure-time or runtime (*note (kpathsea)mktex configuration::). This +is enabled mostly for the sake of the EC fonts, which can be generated +at any size. + + TeX can write output files, via the '\openout' primitive; this opens +a security hole vulnerable to Trojan horse attack: an unwitting user +could run a TeX program that overwrites, say, '~/.rhosts'. (MetaPost +has a 'write' primitive with similar implications). To alleviate this +and similar problems the functions 'kpathsea_out_name_ok' and +'kpathsea_in_name_ok' from the Kpathse library (*note (kpathsea)Calling +sequence::) are used to determine if a given filename is acceptable to +be opened for output or input, depending on the setting of the +configuration variables 'openout_any' and 'openin_any': 'a' (for "any", +the default for 'openin_any'), 'r' (for "restricted"), or 'p' (for +"paranoid", the default for 'openout_any'). + + In any case, all '\openout' filenames are recorded in the log file, +except those opened on the first line of input, which is processed when +the log file has not yet been opened. + + The program accepts the following options, as well as the standard +'-help' and '-version' (*note Common options::): +'-enc' +'-[no]-file-line-error' +'-fmt=FMTNAME' +'-halt-on-error' +'-ini' +'-interaction=STRING' +'-ipc' +'-ipc-start' +'-jobname=STRING' +'-kpathsea-debug=NUMBER' +'-[no]parse-first-line' +'-output-directory' +'-progname=STRING' +'-recorder' +'-translate-file=TCXFILE' +'-8bit' + These options are common to TeX, Metafont, and MetaPost. *Note + Common options::. + +'-enc' + Enable encTeX extensions, such as '\mubyte'. This can be used to + support the Unicode UTF-8 input encoding, although using an engine + with native Unicode support is more common nowadays. + <http://www.olsak.net/enctex.html>. + +'-ipc' +'-ipc-start' + With either option, TeX writes its DVI output to a socket as well + as to the usual '.dvi' file. With '-ipc-start', TeX also opens a + server program at the other end to read the output. *Note IPC and + TeX: IPC and TeX. + + These options are available only if the '--enable-ipc' option was + specified to 'configure' during installation of Web2c. + +'-mktex=FILETYPE' +'-no-mktex=FILETYPE' + Turn on or off the 'mktex' script associated with FILETYPE. For + TeX proper, FILETYPE can only be 'tex' and 'tfm', but for pdfTeX + and luaTeX, it can also be 'pk'. + +'-mltex' + If we are 'INITEX' (*note Initial and virgin::), enable MLTeX + extensions such as '\charsubdef'. Implicitly set if the program + name is 'mltex'. *Note MLTeX: MLTeX. + +'-output-comment=STRING' + Use STRING as the DVI file comment. Ordinarily, this comment + records the date and time of the TeX run, but if you are doing + regression testing, you may not want the DVI file to have this + spurious difference. This is also taken from the environment + variable and config file value 'output_comment'. + +'-shell-escape' +'-no-shell-escape' +'-shell-restricted' + Enable, or disable, or enable with restrictions the + '\write18{SHELL-COMMAND}' feature for external executing shell + commands. *Note Shell escapes::. + +'-enable-write18' +'-disable-write18' + Synonyms for '-shell-escape' and '-no-shell-escape', for + compatibility with MiKTeX. (MiKTeX also accepts both pairs of + options.) *Note Shell escapes::. + +'-src-specials' +'-src-specials=STRING' + This option makes TeX output specific source information using + '\special' commands in the DVI file. These '\special' track the + current file name and line number. + + Using the first form of this option, the '\special' commands are + inserted automatically. + + In the second form of the option, STRING is a comma separated list + of the following values: 'cr', 'display', 'hbox', 'math', 'par', + 'parend', 'vbox'. You can use this list to specify where you want + TeX to output such commands. For example, '-src-specials=cr,math' + will output source information every line and every math formula. + + These commands can be used with the appropriate DVI viewer and text + editor to switch from the current position in the editor to the + same position in the viewer and back from the viewer to the editor. + + This option works by inserting '\special' commands into the token + stream, and thus in principle these additional tokens can be + recovered or seen by the tricky-enough macros. If you run across a + case, let us know, because this counts as a bug. However, such + bugs are very hard to fix, requiring significant changes to TeX, so + please don't count on it. + + Redefining '\special' will not affect the functioning of this + option. The commands inserted into the token stream are hard-coded + to always use the '\special' primitive. + + TeX does not pass the trip test when this option is enabled. + + +File: web2c.info, Node: Initial TeX, Next: Formats, Prev: tex invocation, Up: TeX + +5.2 Initial TeX +=============== + +The "initial" form of TeX is invoked by 'tex -ini'. It does lengthy +initializations avoided by the "virgin" ('vir') form, so as to be +capable of dumping '.fmt' files (*note Memory dumps::). For a detailed +comparison of virgin and initial forms, *note Initial and virgin::. + + For a list of options and other information, *note tex invocation::. + + Unlike Metafont and MetaPost, many format files are commonly used +with TeX. The standard one implementing the features described in the +'TeXbook' is 'plain.fmt', also known as 'tex.fmt' (again, *note Memory +dumps::). It is created by default during installation, but you can +also do so by hand if necessary (e.g., if an update to 'plain.tex' is +issued): + tex -ini '\input plain \dump' +(The quotes prevent interpretation of the backslashes from the shell.) +Then install the resulting 'plain.fmt' in '$(fmtdir)' +('/usr/local/share/texmf/web2c' by default), and link 'tex.fmt' to it. + + The necessary invocation for generating a format file differs for +each format, so instructions that come with the format should explain. +The top-level 'web2c' Makefile has targets for making most common +formats: plain latex amstex texinfo eplain. *Note Formats::, for more +details on TeX formats. + + +File: web2c.info, Node: Formats, Next: Languages and hyphenation, Prev: Initial TeX, Up: TeX + +5.3 Formats +=========== + +TeX "formats" are large collections of macros, often dumped into a +'.fmt' file (*note Memory dumps::) by 'tex -ini' (*note Initial TeX::). +A number of formats are in reasonably widespread use, and the Web2c +Makefile has targets to make the versions current at the time of +release. You can change which formats are automatically built by +setting the 'fmts' Make variable; by default, only the 'plain' and +'latex' formats are made. + + Nowadays, the formats are generally installed and updated as part of +a larger TeX distribution, such as TeX Live (<https://tug.org/texlive>). + +latex + The most widely used format. The current release is named + 'LaTeX2e'; new versions are released approximately every six + months, with patches issued as needed. The old release was called + 'LaTeX 2.09', and is no longer maintained or supported. LaTeX + attempts to provide generic markup instructions, such as + "emphasize", instead of specific typesetting instructions, such as + "use the 10pt Computer Modern italic font". The LaTeX home page: + <https://www.latex-project.org>. + +context + ConTeXt is an independent macro package which has a basic document + structuring approach similar to LaTeX. It also supports creating + interactive PDF files and has integrated MetaPost support, among + many other interesting features. The ConTeXt home page: + <http://www.pragma-ade.com>. + +amstex + The official typesetting system of the American Mathematical + Society. Like LaTeX, it encourages generic markup commands. The + AMS also provides many LaTeX packages for authors who prefer LaTeX. + Taken together, they are used to produce nearly all AMS + publications, e.g., 'Mathematical Reviews'. The AMSTeX home page: + <https://www.ams.org/tex>. + +texinfo + The documentation system developed and maintained by the Free + Software Foundation for their software manuals. It can be + automatically converted into plain text, a machine-readable on-line + format called 'info', HTML, etc. The Texinfo home page: + <https://www.gnu.org/software/texinfo>. + +eplain + The "expanded plain" format provides various common features (e.g., + symbolic cross-referencing, tables of contents, indexing, citations + using BibTeX), for those authors who prefer to handle their own + high-level formatting. The Eplain home page: + <https://tug.org/eplain>. + +slitex + An obsolete LaTeX 2.09 format for making slides. It is replaced by + the 'slides' document class, although the 'beamer' package is the + most commonly method for making slides nowadays. The Beamer page + on CTAN: <https://ctan.org/pkg/beamer>. + + +File: web2c.info, Node: Languages and hyphenation, Next: Shell escapes, Prev: Formats, Up: TeX + +5.4 Languages and hyphenation +============================= + +TeX supports most natural languages. See also *note TeX extensions: TeX +extensions. + +* Menu: + +* MLTeX:: Multi-lingual TeX. +* TCX files:: Support for different character sets & fonts. +* patgen invocation:: Creating hyphenation patterns. + + +File: web2c.info, Node: MLTeX, Next: TCX files, Up: Languages and hyphenation + +5.4.1 MLTeX: Multi-lingual TeX +------------------------------ + +Multi-lingual TeX ('mltex') is an extension of TeX originally written by +Michael Ferguson and now updated and maintained by Bernd Raichle. With +the advent of Unicode, it has become obsolete, though it is still +supported in Web2c in the event of bugs or compilation bugs. + + MLTeX allows the use of non-existing glyphs in a font by declaring +glyph substitutions. These are restricted to substitutions of an +accented character glyph, which need not be defined in the current font, +by its appropriate '\accent' construction using a base and accent +character glyph, which do have to exist in the current font. This +substitution is automatically done behind the scenes, if necessary, and +thus MLTeX additionally supports hyphenation of words containing an +accented character glyph for fonts missing this glyph (e.g., Computer +Modern). Standard TeX suppresses hyphenation in this case. + + MLTeX works at '.fmt'-creation time: the basic idea is to specify the +'-mltex' option to TeX when you '\dump' a format. Then, when you +subsequently invoke TeX and read that '.fmt' file, the MLTeX features +described below will be enabled. + + Generally, you use special macro files to create an MLTeX '.fmt' +file. + + The sections below describe the two new primitives that MLTeX +defines. Aside from these, MLTeX is completely compatible with standard +TeX. + +* Menu: + +* \charsubdef:: Character substitution definitions. +* \tracingcharsubdef:: Tracing substitutions. + + +File: web2c.info, Node: \charsubdef, Next: \tracingcharsubdef, Up: MLTeX + +5.4.1.1 '\charsubdef': Character substitutions +.............................................. + +The most important primitive MLTeX adds is '\charsubdef', used in a way +reminiscent of '\chardef': + \charsubdef COMPOSITE [=] ACCENT BASE + + Each of COMPOSITE, ACCENT, and BASE are font glyph numbers, expressed +in the usual TeX syntax: `\e symbolically, '145 for octal, "65 for hex, +101 for decimal. + + MLTeX's '\charsubdef' declares how to construct an accented character +glyph (not necessarily existing in the current font) using two character +glyphs (that do exist). Thus it defines whether a character glyph code, +either typed as a single character or using the '\char' primitive, will +be mapped to a font glyph or to an '\accent' glyph construction. + + For example, if you assume glyph code 138 (decimal) for an +e-circumflex and you are using the Computer Modern fonts, which have the +circumflex accent in position 18 and lowercase 'e' in the usual ASCII +position 101 decimal, you would use '\charsubdef' as follows: + + \charsubdef 138 = 18 101 + + For the plain TeX format to make use of this substitution, you have +to redefine the circumflex accent macro '\^' in such a way that if its +argument is character 'e' the expansion '\char138 ' is used instead of +'\accent18 e'. Similar '\charsubdef' declaration and macro +redefinitions have to be done for all other accented characters. + + To disable a previous '\charsubdef C', redefine C as a pair of zeros. +For example: + \charsubdef '321 = 0 0 % disable N tilde +(Octal '321 is the ISO Latin-1 value for the Spanish N tilde.) + + '\charsubdef' commands should only be given once. Although in +principle you can use '\charsubdef' at any time, the result is +unspecified. If '\charsubdef' declarations are changed, usually either +incorrect character dimensions will be used or MLTeX will output missing +character warnings. (The substitution of a '\charsubdef' is used by TeX +when appending the character node to the current horizontal list, to +compute the width of a horizontal box when the box gets packed, and when +building the '\accent' construction at '\shipout'-time. In summary, the +substitution is accessed often, so changing it is not desirable, nor +generally useful.) + + +File: web2c.info, Node: \tracingcharsubdef, Prev: \charsubdef, Up: MLTeX + +5.4.1.2 '\tracingcharsubdef': Substitution diagnostics +...................................................... + +To help diagnose problems with '\charsubdef', MLTeX provides a new +primitive parameter, '\tracingcharsubdef'. If positive, every use of +'\charsubdef' will be reported. This can help track down when a +character is redefined. + + In addition, if the TeX parameter '\tracinglostchars' is 100 or more, +the character substitutions actually performed at '\shipout'-time will +be recorded. + + +File: web2c.info, Node: TCX files, Next: patgen invocation, Prev: MLTeX, Up: Languages and hyphenation + +5.4.2 TCX files: Character translations +--------------------------------------- + +TCX (TeX character translation) files help TeX support direct input of +8-bit international characters if fonts containing those characters are +being used. Specifically, they map an input (keyboard) character code +to the internal TeX character code (a superset of ASCII). + + Of the various proposals for handling more than one input encoding, +TCX files were chosen because they follow Knuth's original ideas for the +use of the 'xchr' and 'xord' tables. He ventured that these would be +changed in the WEB source in order to adjust the actual version to a +given environment. It turns out, however, that recompiling the WEB +sources is not as simple a task as Knuth may have imagined; therefore, +TCX files, providing the possibility of changing of the conversion +tables on on-the-fly, have been implemented instead. + + This approach limits the portability of TeX documents, as some +implementations do not support it (or use a different method for +input-internal reencoding). It may also be problematic to determine the +encoding to use for a TeX document of unknown provenance; in the worst +case, failure to do so correctly may result in subtle errors in the +typeset output. But we feel the benefits outweigh these disadvantages. + + This is entirely independent of the MLTeX extension (*note MLTeX::): +whereas a TCX file defines how an input keyboard character is mapped to +TeX's internal code, MLTeX defines substitutions for a non-existing +character glyph in a font with a '\accent' construction made out of two +separate character glyphs. TCX files involve no new primitives; it is +not possible to specify that an input (keyboard) character maps to more +than one character. + + Information on specifying TCX files: + + * The best way to specify a TCX file is to list it explicitly in the + first line of the main document: + %& -translate-file=TCXFILE + + * You can also specify a TCX file to be used on a particular TeX run + with the command-line option '-translate-file=TCXFILE'. + + * TCX files are searched for along the 'WEB2C' path. + + * Initial TeX (*note Initial TeX: Initial TeX.) ignores TCX files. + + The Web2c distribution comes with a number of TCX files. Two +important ones are 'il1-t1.tcx' and 'il2-t1.tcx', which support ISO +Latin 1 and ISO Latin 2, respectively, with Cork-encoded fonts +(a.k.a. the LaTeX T1 encoding). TCX files for Czech, Polish, and Slovak +are also provided. + + One other notable TCX file is 'empty.tcx', which is, well, empty. +Its purpose is to reset Web2C's behavior to the default (only visible +ASCII being printable, as described below) when a format was dumped with +another TCX being active--which is in fact the case for everything but +plain TeX in the TeX Live and other distributions. Thus: + + latex somefile8.tex + => terminal etc. output with 8-bit chars + latex --translate-file=empty.tcx somefile8.tex + => terminal etc. output with ^^ notation + + Syntax of TCX files: + 1. Line-oriented. Blank lines are ignored. + + 2. Whitespace is ignored except as a separator. + + 3. Comments start with '%' and continue to the end of the line. + + 4. Otherwise, a line consists of one or two character codes, + optionally followed by 0 or 1. The last number indicates whether + DEST is considered printable. + SRC [DEST [PRNT]] + + 5. Each character code may be specified in octal with a leading '0', + hexadecimal with a leading '0x', or decimal otherwise. Values must + be between 0 and 255, inclusive (decimal). + + 6. If the DEST code is not specified, it is taken to be the same as + SRC. + + 7. If the same SRC code is specified more than once, it is the last + definition that counts. + + Finally, here's what happens: when TeX sees an input character with +code SRC, it 1) changes SRC to DEST; and 2) makes the DEST code +"printable", i.e., printed as-is in diagnostics and the log file rather +than in '^^' notation. + + By default, no characters are translated, and character codes between +32 and 126 inclusive (decimal) are printable. + + Specifying translations for the printable ASCII characters (codes +32-127) will yield unpredictable results. Additionally you shouldn't +make the following characters printable: '^^I' (TAB), '^^J' (line feed), +'^^M' (carriage return), and '^^?' (delete), since TeX uses them in +various ways. + + Thus, the idea is to specify the input (keyboard) character code for +SRC, and the output (font) character code for DEST. + + By default, only the printable ASCII characters are considered +printable by TeX. If you specify the '-8bit' option, all characters are +considered printable by default. If you specify both the '-8bit' option +and a TCX file, then the TCX can set specific characters to be +non-printable. + + Both the specified TCX encoding and whether characters are printable +are saved in the dump files (like 'tex.fmt'). So by giving these +options in combination with '-ini', you control the defaults seen by +anyone who uses the resulting dump file. + + When loading a dump, if the '-8bit' option was given, then all +characters become printable by default. + + When loading a dump, if a TCX file was specified, then the TCX data +from the dump is ignored and the data from the file used instead. + + +File: web2c.info, Node: patgen invocation, Prev: TCX files, Up: Languages and hyphenation + +5.4.3 Patgen: Creating hyphenation patterns +------------------------------------------- + +Patgen creates hyphenation patterns from dictionary files for use with +TeX. Synopsis: + + patgen DICTIONARY PATTERNS OUTPUT TRANSLATE + + Each argument is a filename. No path searching is done. The output +is written to the file OUTPUT. + + In addition, Patgen prompts interactively for other values. + + For more information, see 'Word hy-phen-a-tion by com-puter' by Frank +Liang (*note References::), and also the 'patgen.web' source file. + + The only options are '-help' and '-version' (*note Common options::). + + +File: web2c.info, Node: Shell escapes, Next: IPC and TeX, Prev: Languages and hyphenation, Up: TeX + +5.5 Shell escapes +================= + +TeX can execute "shell escapes", that is, arbitrary shell commands. +Although tremendously useful, this also has obvious security +implications. Therefore, as of TeX Live 2009, a "restricted" mode for +shell escapes is the default mode of operation, which allows executing +only certain commands, as specified in the 'texmf.cnf' configuration +file. + + * Unrestricted shell escapes are allowed if the option + '--shell-escape' is specified, or if the environment variable or + config file value 'shell_escape' is set to 't' or 'y' and '1'. + + * Restricted shell escapes are allowed if 'shell_escape' is set to + 'p'. This is the default. + + * Shell escapes are completely disabled if '--no-shell-escape' is + specified, or if 'shell_escape' is set to anything else. + + When enabled, the TeX construct to execute a system command is +'\write18{SHELL-COMMAND}'; for example: + + \write18{echo "hello, world"} + + From TeX's point of view, this is a normal '\write' command, and is +therefore subject to the usual TeX expansions. Also, the system call +either happens during the '\output' routine or right away, according to +the absence or presence of the '\immediate' prefix, as usual for +'\write'. + + The SHELL-COMMAND string is passed to the command shell (via the C +library function 'system'). The output of SHELL-COMMAND is not diverted +anywhere, so it will not appear in the log file, or anywhere but the +terminal output. The exit status of the system call is also not +available to TeX. + + In unrestricted mode, the argument is simply passed straight to +'system' unaltered. + + In restricted mode, ASCII double quote characters (") should always +be used in the argument to '\write18' where quoting of arguments is +needed, as in the example above. This is to achieve some measure of +system independence. On Unix systems, these are replaced with single +quote (') characters to avoid insecure further expansion. Care is also +taken on Windows to avoid additional expansions (from, e.g., `...`). +Mismatched quotation marks in the command string result in a diagnostic +message in the log file; no execution is performed. + + After quotation processing, if the first word (delimited by a space +or tab) of the command is in the list specified by the +'shell_escape_commands' configuration value, the command is executed. +Otherwise it is not. In any case, a message is written to the log file. + + The 'shell_escape_commands' value is a comma-separated list of words. +Whitespace is significant, and typically should not be present. The +default definition in 'texmf.cnf' looks like this, but with more +commands included: + + shell_escape_commands = bibtex,kpsewhich,repstopdf,... + + pdfTeX and luaTeX support reading (via '\input' and '\openin') and +writing (via '\openout') from pipes if the first character is '|'. The +following command is then treated exactly the same as the argument to +'\write18'. In these engines, the primitive variable '\pdfshellescape' +is set to 0 if shell escapes are disabled, 1 if they are enabled, and 2 +if they are enabled with restrictions. + + The purpose of this feature is to make it possible for TeX documents +to perform useful external actions in the common case of an individual +user running a known document on his or her own machine. In such +environments as CGI scripts or wikis where the input has to be +considered untrustworthy, shell escapes should be completely disabled. + + +File: web2c.info, Node: IPC and TeX, Next: TeX extensions, Prev: Shell escapes, Up: TeX + +5.6 IPC and TeX +=============== + +(If anyone uses this feature and needs documentation, write +<tex-k@tug.org>.) + + This functionality is available only if the '--enable-ipc' option was +specified to 'configure' during installation of Web2c (*note +Installation::). + + If you define 'IPC_DEBUG' before compilation (e.g., with 'make +XCFLAGS=-DIPC_DEBUG'), TeX will print messages to standard error about +its socket operations. This may be helpful if you are, well, debugging. + + +File: web2c.info, Node: TeX extensions, Prev: IPC and TeX, Up: TeX + +5.7 Extended TeX engines +======================== + +The base TeX program has been extended in many ways. Here's a partial +list. + +e-TeX + Adds many new primitives, including right-to-left typesetting and + more registers. Now frozen. More info: + <https://ctan.org/pkg/etex>. + +Aleph + This adds Unicode support, right-to-left typesetting, and more. + Omega was the original program. Aleph is an updated version with a + variety of bug fixes, and includes e-TeX. Aleph is not actively + maintained. More info: <https://ctan.org/pkg/aleph>, + <https://ctan.org/pkg/omega>. + +pdfTeX + Can produce PDF as well as DVI files. It also incorporates the + e-TeX extensions, new primitives for hypertext and + micro-typography, reading/writing from pipes, and much more. In + TeX Live, the command 'etex' invokes pdfTeX to make all these + additions available with DVI output. Home page: + <http://pdftex.org>. + +LuaTeX + Embeds the Lua programming language (<http://lua.org>) and opens up + the TeX typesetting engine to control from Lua, starting from the + pdfTeX capabilities as a base. Also natively supports UTF-8 input, + the OpenType and TrueType font formats, and use of system fonts. + Home page: <http://luatex.org>. + +XeTeX + Combines support for Unicode input, the OpenType and TrueType font + formats, and use of system fonts with the capabilities of pdfTeX, + with the exception of the font expansion part of micro-typography. + Home page: <https://tug.org/xetex>. + +pTeX +upTeX + With additional support for Japanese; pTeX was the original engine, + and upTeX has native Unicode support and thus is more useful for + Chinese and Korean. More info: <https://ctan.org/pkg/ptex>, + <https://ctan.org/pkg/uptex>. + +epTeX +eupTeX + Further extends pTeX and upTeX with the e-TeX extensions. More + info: <https://ctan.org/pkg/eptex>, <https://ctan.org/pkg/euptex>. + + +File: web2c.info, Node: Metafont, Next: MetaPost, Prev: TeX, Up: Top + +6 Metafont: Creating typeface families +************************************** + +Metafont is a system for producing shapes; it was designed for producing +complete typeface families, but it can also produce geometric designs, +dingbats, etc. And it has considerable mathematical and +equation-solving capabilities which can be useful entirely on their own. + + Metafont is a batch language, like C or Pascal: you compile a +Metafont program into a corresponding font, rather than interactively +drawing lines or curves. This approach has both considerable +disadvantages (people unfamiliar with conventional programming languages +will be unlikely to find it usable) and considerable advantages (you can +make your design intentions specific and parameterizable). For a +complete description of the Metafont language, see 'The METAFONTbook' +(*note References::). + +* Menu: + +* mf invocation:: Invoking Metafont. +* Initial Metafont:: Making bases. +* Modes:: Device definitions for Metafont. +* Online Metafont graphics:: Seeing MF output online. +* gftodvi invocation:: Making proofsheets for fonts. +* mft invocation:: Prettyprinting Metafont sources. + + +File: web2c.info, Node: mf invocation, Next: Initial Metafont, Up: Metafont + +6.1 'mf' invocation +=================== + +Metafont (usually invoked as 'mf') reads character definitions specified +in the Metafont programming language, and outputs the corresponding +font. This section merely describes the options available in the Web2c +implementation. For a complete description of the Metafont language, +see 'The Metafontbook' (*note References::). + + Metafont processes its command line and determines its memory dump +(base) file in a way exactly analogous to MetaPost and TeX (*note tex +invocation::, and *note Memory dumps::). Synopses: + + mf [OPTION]... [MFNAME[.mf]] [MF-COMMANDS] + mf [OPTION]... \FIRST-LINE + mf [OPTION]... &BASE ARGS + + Most commonly, a Metafont invocation looks like this: + mf '\mode:=MODE; mag:=MAGNIFICATION; input MFNAME' +(The single quotes avoid unwanted interpretation by the shell.) + + Metafont searches the usual places for the main input file MFNAME +(*note (kpathsea)Supported file formats::), extending MFNAME with '.mf' +if necessary. To see all the relevant paths, set the environment +variable 'KPATHSEA_DEBUG' to '-1' before running the program. By +default, Metafont runs an external program named 'mktexmf' to create any +nonexistent Metafont source files you input. You can disable this at +configure-time or runtime (*note (kpathsea)mktex configuration::). This +is mostly for the sake of the EC fonts, which can be generated at any +size. + + Metafont writes the main GF output to the file 'BASEMFNAME.NNNgf', +where NNN is the font resolution in pixels per inch, and BASEMFNAME is +the basename of MFNAME, or 'mfput' if no input file was specified. A GF +file contains bitmaps of the actual character shapes. Usually GF files +are converted immediately to PK files with GFtoPK (*note gftopk +invocation::), since PK files contain equivalent information, but are +more compact. (Metafont output in GF format rather than PK for only +historical reasons.) + + Metafont also usually writes a metric file in TFM format to +'BASEMFNAME.tfm'. A TFM file contains character dimensions, kerns, and +ligatures, and spacing parameters. TeX reads only this .tfm file, not +the GF file. + + The MODE in the example command above is a name referring to a device +definition (*note Modes::); for example, 'localfont' or 'ljfour'. These +device definitions must generally be precompiled into the base file. If +you leave this out, the default is 'proof' mode, as stated in 'The +Metafontbook', in which Metafont outputs at a resolution of 2602dpi; +this is usually not what you want. The remedy is simply to assign a +different mode--'localfont', for example. + + The MAGNIFICATION assignment in the example command above is a +magnification factor; for example, if the device is 600dpi and you +specify 'mag:=2', Metafont will produce output at 1200dpi. Very often, +the MAGNIFICATION is an expression such as 'magstep(.5)', corresponding +to a TeX "magstep", which are factors of 1.2 * sqrt(2). + + After running Metafont, you can use the font in a TeX document as +usual. For example: + \font\myfont = newfont + \myfont Now I am typesetting in my new font (minimum hamburgers). + + The program accepts the following options, as well as the standard +'-help' and '-version' (*note Common options::): +'-[no]-file-line-error' +'-fmt=FMTNAME' +'-halt-on-error' +'-ini' +'-interaction=STRING' +'-jobname=STRING' +'-kpathsea-debug=NUMBER' +'-[no]parse-first-line' +'-output-directory' +'-progname=STRING' +'-recorder' +'-translate-file=TCXFILE' +'-8bit' + These options are common to TeX, Metafont, and MetaPost. *Note + Common options::. + +'-mktex=FILETYPE' +'-no-mktex=FILETYPE' + Turn on or off the 'mktex' script associated with FILETYPE. The + only value that makes sense for FILETYPE is 'mf'. + + +File: web2c.info, Node: Initial Metafont, Next: Modes, Prev: mf invocation, Up: Metafont + +6.2 Initial Metafont +==================== + +'inimf' is the "initial" form of Metafont, which does lengthy +initializations avoided by the "virgin" ('vir') form, so as to be +capable of dumping '.base' files (*note Memory dumps::). For a detailed +comparison of virgin and initial forms, see *note Initial and virgin::. + + For a list of options and other information, see *note mf +invocation::. + + The only memory dump file commonly used with Metafont is the default +'plain.base', also known as 'mf.base' (again, *note Memory dumps::). It +is created by default during installation, but you can also do so by +hand if necessary (e.g., if a Metafont update is issued): + mf -ini '\input plain; input modes; dump' +(The quotes prevent interpretation of the backslashes from the shell.) +Then install the resulting 'plain.base' in '$(basedir)' +('/usr/local/share/texmf/web2c' by default), and link 'mf.base' to it. + + For an explanation of the additional 'modes.mf' file, see *note +Modes::. This file has no counterpart in TeX or MetaPost. + + In the past, it was sometimes useful to create a base file +'cmmf.base' (a.k.a. 'cm.base'), with the Computer Modern macros also +included in the base file. Nowadays, however, the additional time +required to read 'cmbase.mf' is exceedingly small, usually not enough to +be worth the administrative hassle of updating the 'cmmf.base' file when +you install a new version of 'modes.mf'. People actually working on a +typeface may still find it worthwhile to create their own base file, of +course. + + +File: web2c.info, Node: Modes, Next: Online Metafont graphics, Prev: Initial Metafont, Up: Metafont + +6.3 Modes: Device definitions for Metafont +========================================== + +Running Metafont and creating Metafont base files requires information +that TeX and MetaPost do not: "mode" definitions which specify device +characteristics, so Metafont can properly rasterize the shapes. + + When making a base file, a file containing modes for +locally-available devices should be input after 'plain.mf'. One +commonly used file is <ftp://ftp.tug.org/tex/modes.mf>; it includes all +known definitions. + + If, however, for some reason you have decreased the memory available +in your Metafont, you may need to copy 'modes.mf' and remove the +definitions irrelevant to you (probably most of them) instead of using +it directly. (Or, if you're a Metafont hacker, maybe you can suggest a +way to redefine 'mode_def' and/or 'mode_setup'; right now, the amount of +memory used is approximately four times the total length of the +'mode_def' names, and that's a lot.) + + If you have a device not included in 'modes.mf', please see comments +in that file for how to create the new definition, and please send the +definition to <tex-fonts@math.utah.edu> to get it included in the next +release of 'modes.mf'. + + Usually, when you run Metafont you must supply the name of a mode +that was dumped in the base file. But you can also define the mode +characteristics dynamically, by invoking Metafont with an assignment to +'smode' instead of 'mode', like this: + mf '\smode:="newmode.mf"; mag:=MAGNIFICATION; input MFNAME' +This is most useful when you are working on the definition of a new +mode. + + The MAGNIFICATION and MFNAME arguments are explained in *note mf +invocation::. In the file 'newmode.mf', you should have the following +(with no 'mode_def' or 'enddef'), if you are using 'modes.mf' +conventions: + mode_param (pixels_per_inch, DPI); + mode_param (blacker, B); + mode_param (fillin, F); + mode_param (o_correction, O); + mode_common_setup_; +(Of course, you should use real numbers for DPI, B, F, and O.) + + For more information on the use of 'smode', or if you are not using +'modes.mf', see page 269 of 'The Metafontbook'. + + +File: web2c.info, Node: Online Metafont graphics, Next: gftodvi invocation, Prev: Modes, Up: Metafont + +6.4 Online Metafont graphics +============================ + +The Web2c implementation of Metafont can do online graphics with a +number of devices. (See the Metafont manual for more information about +how to draw on your screen.) By default, no graphics support is +enabled. + + Metafont examines the 'MFTERM' environment variable or config file +value at runtime, or the 'TERM' environment variable if 'MFTERM' is not +set, to determine the device support to use. Naturally, only the +devices for which support has been compiled in can be selected. + + Here is a table of the possibilities, showing the 'MFTERM' value and +the corresponding 'configure' option(s) in parentheses. + +'epsf' + ('--enable-epsfwin') Pseudo-window server for Encapsulated + PostScript (see 'web2c/window/epsf.c'). This device produces an + EPS file containing the graphics which would be displayed online on + other devices. The name of the EPS file defaults to metafont.eps + but can be changed by setting the MFEPSF environment variable to + the new filename. Contributed by Mathias Herberts. + +'hp2627' + ('--enable-hp2627win') HP2627a color graphics terminals. + +'mftalk' + ('--enable-mftalkwin') Generic window server (see + 'web2c/window/mftalk.c'). + +'next' + ('--enable-next') NeXT window system. This requires a separate + program, called 'DrawingServant', available separately. See the + 'web2c/window/next.c'. + +'regis' + ('--enable-regiswin') Regis terminals. + +'sun' + ('--enable-suntoolswin') The old Suntools (not any flavor of X) + window system. (You can get the even older SunWindows 'gfx' system + by using 'sun-gfx.c'.) + +'tek' + ('--enable-tektronixwin') Tektronix terminals. + +'uniterm' + ('--enable-unitermwin') Uniterm, Simon Poole's emulator of a smart + Tektronix 4014 terminal. This may work with regular Tektronix + terminals as well; it's faster than the driver + '--enable-tektronixwin' selects. + +'xterm' + '--with-x' The X window system (version 11). + + There are two variants of the X11 support, one that works with the + Xt toolkit, and another that works directly with Xlib. The Xt + support is more efficient and has more functionality, so it is the + default. If you must use the Xlib support, use 'configure --with-x + --with-kf-x-toolkit=no'. + + Specify '--disable-mf-nowin' in order not to build a separate + non-windows-capable Metafont executable 'mf-nowin' (or + 'mf-nowin.exe'). + + You cannot specify any of the usual X options (e.g., '-geometry') + on the Metafont command line, but you can specify X resources in + your '~/.Xdefaults' or '~/.Xresources' file. The class name is + 'Metafont'. If you're using the Xt support, all the usual X + toolkit resources are supported. If you're using the Xlib support, + only the 'geometry' resource is supported. + + You specify the X display to which Metafont connects in the + 'DISPLAY' environment variable, as usual. + + Writing support for a new device is straightforward. Aside from +defining the basic drawing routines that Metafont uses (see 'mf.web'), +you only have to add another entry to the tables on the last page of +'web2c/lib/texmfmp.c'. Or you can write an independent program and use +MFtalk (see 'web2c/window/mftalk.c'). + + +File: web2c.info, Node: gftodvi invocation, Next: mft invocation, Prev: Online Metafont graphics, Up: Metafont + +6.5 GFtoDVI: Character proofs of fonts +====================================== + +GFtoDVI makes "proof sheets" from a GF bitmap file as output by, for +example, Metafont (*note Metafont::). This is an indispensable aid for +font designers or Metafont hackers. Synopsis: + + gftodvi [OPTION]... GFNAME[gf] + + The font GFNAME is searched for in the usual places (*note +(kpathsea)Glyph lookup::). To see all the relevant paths, set the +environment variable 'KPATHSEA_DEBUG' to '-1' before running the +program. + + The suffix 'gf' is supplied if not already present. This suffix is +not an extension, no '.' precedes it; for instance, 'cmr10.600gf'. + + The output filename is the basename of GFNAME extended with '.dvi', +e.g., 'gftodvi /wherever/foo.600gf' creates './foo.dvi'. + + The characters from GFNAME appear one per page in the DVI output, +with labels, titles, and annotations, as specified in Appendix H +(Hardcopy Proofs) of 'The Metafontbook'. + + GFtoDVI uses several fonts besides GFNAME itself: + + * "gray font" (default 'gray'): for the pixels that actually make up + the character. Simply using black is not right, since then labels, + key points, and other information could not be shown. + + * "title font" (default 'cmr8'): for the header information at the + top of each output page. + + * "label font" (default 'cmtt10'): for the labels on key points of + the figure. + + * "slant font" (no default): for diagonal lines, which are otherwise + simulated using horizontal and vertical rules. + + To change the default fonts, you must use 'special' commands in your +Metafont source file, typically via commands like 'slantfont slantlj4'. +There is no default slant font since no one printer is suitable as a +default. You can make your own by copying one of the existing files, +such as '.../fonts/source/public/misc/slantlj4.mf' and then running 'mf' +on it. + + For testing purposes, you may it useful to run 'mf-nowin rtest' (hit +RETURN when it stops) to get a 'gf' file of a thorn glyph. Or use 'mf' +instead of 'mf-nowin' to have the glyph(s) displayed on the screen. +After that, 'gftodvi rtest.2602gf' should produce 'rtest.dvi', which you +process as usual. + + The program accepts the following option, as well as the standard +'-verbose', '-help', and '-version' (*note Common options::): + +'-overflow-label-offset=POINTS' + Typeset the so-called overflow labels, if any, POINTS TeX points + from the right edge of the character bounding box. The default is + a little over two inches (ten million scaled points, to be + precise). Overflow equations are used to locate coordinates when + their actual position is too crowded with other information. + + +File: web2c.info, Node: mft invocation, Prev: gftodvi invocation, Up: Metafont + +6.6 MFT: Prettyprinting Metafont source +======================================= + +MFT translates a Metafont program into a TeX document suitable for +typesetting, with the aid of TeX macros defined in the file +'mftmac.tex'. Synopsis: + + mft [OPTION]... MFNAME[.mf] + + MFT searches the usual places for MFNAME (*note (kpathsea)Supported +file formats::). To see all the relevant paths, set the environment +variable 'KPATHSEA_DEBUG' to '-1' before running the program. The +output goes to the basename of MFNAME extended with '.tex', e.g., 'mft +/wherever/foo.mf' creates './foo.tex'. + + Line breaks in the input are carried over into the output; moreover, +blank spaces at the beginning of a line are converted to quads of +indentation in the output. Thus, you have full control over the +indentation and line breaks. Each line of input is translated +independently of the others. + + Further control is allowed via Metafont comments: + * Metafont comments following a single '%' should be valid TeX input. + But Metafont material can be included within vertical bars in a + comment; this will be translated by MFT as if it were regular + Metafont code. For example, a comment like '% |x2r| is the tip of + the bowl' will be translated into the TeX '% $x_{2r}$ is the ...', + i.e., the 'x2r' is treated as an identifier. + + * '%%' indicates that the remainder of an input line should be copied + verbatim to the output. This is typically used to introduce + additional TeX material at the beginning or an MFT job, e.g. code + to modify the standard layout or the formatting macros defined in + 'mftmac.tex', or to add a line saying '%%\bye' at the end of the + job. (MFT doesn't add this automatically in order to allow + processing several files produces by MFT in the same TeX job.) + + * '%%% TOKEN1 OTHER-TOKENS' introduces a change in MFT's formatting + rules; all the OTHER-TOKENS will henceforth be translated according + to the current conventions for TOKEN1. The tokens must be symbolic + (i.e., not numeric or string tokens). For example, the input line + %%% addto fill draw filldraw + says to format the 'fill', 'draw', and 'filldraw' operations of + plain Metafont just like the primitive token 'addto', i.e., in + boldface type. Without such reformatting commands, MFT would treat + 'fill' like an ordinary tag or variable name. In fact, you need a + '%%%' command even to get parentheses to act like delimiters. + + * '%%%%' introduces an MFT comment, i.e., MFT ignores the remainder + of such a line. + + * Five or more '%' signs should not be used. + + (The above description was edited from 'mft.web', written by +D.E. Knuth.) + + The program accepts the following options, as well as the standard +'-help' and '-version' (*note Common options::): +'-change=CHFILE[.ch]' + Apply the change file CHFILE as with Tangle and Weave (*note + WEB::). + +'-style=MFTFILE[.mft]' + Read MFTFILE before anything else; a MFT style file typically + contains only MFT directives as described above. The default style + file is named 'plain.mft', which defines this properly for programs + using plain Metafont. The MFT files is searched along the + 'MFTINPUTS' path; see *note (kpathsea)Supported file formats::. + + Other examples of MFT style files are 'cmbase.mft', which defines + formatting rules for the macros defined in 'cm.base', and 'e.mft', + which was used in the production of Knuth's Volume E, 'Computer + Modern Typefaces'. + + Using an appropriate MFT style file, it is also possible to + configure MFT for typesetting MetaPost sources. However, MFT does + not search the usual places for MetaPost input files. + + If you use eight-bit characters in the input file, they are passed on +verbatim to the TeX output file; it is up to you to configure TeX to +print these properly. + + +File: web2c.info, Node: MetaPost, Next: BibTeX, Prev: Metafont, Up: Top + +7 MetaPost: Generating PostScript +********************************* + +MetaPost is a picture-drawing language similar to Metafont (*note +Metafont::), but instead of outputting bitmaps in a "font", it outputs +PostScript commands. It's primarily intended for creating technical +illustrations, but can also be used to create PostScript or OpenType +fonts (<https://ctan.org/pkg/metatype1>). + + MetaPost also provides for arbitrary integration of text and graphics +in a natural way, using any typesetter (TeX and Troff are both +supported) and a number of other subsidiary programs, described below. + +* Menu: + +* mpost invocation:: Invoking MetaPost. +* Initial MetaPost:: Making mems. +* dvitomp invocation:: DVI-to-MPX translation. + + +File: web2c.info, Node: mpost invocation, Next: Initial MetaPost, Up: MetaPost + +7.1 'mpost' invocation +====================== + +MetaPost (installed as 'mpost') reads a series of pictures specified in +the MetaPost programming language, and outputs corresponding PostScript +code. This section merely describes the options available in the Web2c +implementation. For a complete description of the MetaPost language, +see AT&T technical report CSTR-162, generally available in +'TEXMF/doc/metapost/', where TEXMF is the root of TeX directory +structure. The MetaPost home page: <https://tug.org/metapost>. + + Also, a standard MetaPost package for drawing graphs is documented in +AT&T technical report CSTR-164, available as the file 'mpgraph.ps', +generally stored alongside 'mpman.ps'. + + MetaPost processes its command line and determines its memory dump +(mem) file in a way analogous to Metafont and TeX (*note 'tex' +invocation: tex invocation, and *note Memory dumps::). Synopses: + + mpost [OPTION]... [MPNAME[.mp]] [MP-COMMANDS] + mpost [OPTION]... \FIRST-LINE + mpost [OPTION]... &MEM ARGS + + MetaPost searches the usual places for the main input file MPNAME +(*note (kpathsea)Supported file formats::), extending MPNAME with '.mp' +if necessary. To see all the relevant paths, set the environment +variable 'KPATHSEA_DEBUG' to '-1' before running the program. + + MetaPost writes its PostScript output to a series of files +'BASEMPNAME.NNN' (or perhaps 'BASEMPNAME.ps', very occasionally +'BASEMPNAME.tfm'), where NNN are the figure numbers specified in the +input, typically to the 'beginfig' macro, and BASEMPNAME is the basename +of MPNAME, or 'mpout' if no input file was specified. MetaPost uses the +'.ps' extension when the figure number is out of range, e.g., if you say +'beginfig(-1)'. + + You can use the output files as figures in a TeX document just as +with any other PostScript figures. For example, with this TeX command: + \special{psfile="FILENAME"} +or by using 'epsf.tex' (*note (dvips)EPSF macros::). + + The MetaPost construct + btex ... TEX-INPUT ... etex +generates a MetaPost picture expression corresponding to TEX-INPUT. + + The construct + verbatimtex ... TEX-INPUT ... etex +simply passes the TEX-INPUT through to TeX. For example, if you are +using LaTeX, your MetaPost input file must start with a 'verbatimtex' +block that gives the necessary '\documentclass' (or '\documentstyle') +'\begin{document}' command. You will also need to set the enviroment +variable 'TEX' to 'latex'. + + TEX-INPUT need not be specifically TeX input; it could also be Troff. +In that case, you will need the '-m pictures' Troff macro package +(unfortunately absent from many Troff implementations), or an equivalent +such as the '-m pspic' macros from GNU groff described in grops(1). + + Naturally, you must use fonts that are supported by the typesetter; +specifically, you'll probably want to use standard PostScript fonts with +Troff. And only the TeX system understands Computer Modern or other +Metafont fonts; you can also use PostScript fonts with TeX, of course. + + MetaPost-generated PostScript figures which do use Computer Modern +fonts for labels cannot be directly previewed or printed. Instead, you +must include them in a TeX document and run the resulting DVI file +through Dvips to arrange for the downloading of the required fonts +(*note (dvips)Fonts in figures::). To help with this, the MetaPost +distribution provides a small TeX file 'mproof.tex' which is typically +called as: + tex mproof MP-OUTPUT-FILES... ; dvips mproof -o +The resulting file 'mproof.ps' can then be printed or previewed. + + To generate EPSF files, set the internal MetaPost variable +'prologues' positive. To make the output files self-contained, use only +standard PostScript fonts. MetaPost reads the same 'psfonts.map' file +as Dvips, to determine PostScript fonts that need to be downloaded +(*note (dvips)psfonts.map::). + + It is posible for pdfTeX to read MetaPost output directly; this is in +contrast to general EPSF files, which have to be converted for use with +PDF output. The easiest way is to name the MetaPost output files with +the '.mps' extension. Then the LaTeX '\includegraphics' command, for +example, will be able to read them, even when outputting PDF. + + MetaPost can write output files, via the 'write' primitive; this +opens a security hole. *Note tex invocation::. + + The program accepts the following options, as well as the standard +'-help' and '-version' (*note Common options::): +'-[no]-file-line-error' +'-fmt=FMTNAME' +'-halt-on-error' +'-ini' +'-interaction=STRING' +'-jobname=STRING' +'-kpathsea-debug=NUMBER' +'-[no]parse-first-line' +'-output-directory' +'-progname=STRING' +'-recorder' +'-translate-file=TCXFILE' +'-8bit' + These options are common to TeX, Metafont, and MetaPost. *Note + Common options::. + +'-T' +'-troff' + Set the 'prologues' internal variable to '1'. + +'-tex=TEXPROGRAM' + When this option is given, the program TEXPROGRAM is used to + typeset the labels. + + +File: web2c.info, Node: Initial MetaPost, Next: dvitomp invocation, Prev: mpost invocation, Up: MetaPost + +7.2 Initial MetaPost +==================== + +As of MetaPost 1.504 (TeX Live 2011), MetaPost no longer dumps '.mem' +files (*note Memory dumps::) and does not distinguish virgin and initial +forms (*note Initial and virgin::). Instead, the "initial" file name is +read in its source form--that is, 'mpost.mp' when the program is invoked +as 'mpost'. + + For a list of options and other information, see *note mpost +invocation::. + + MetaPost provides a format with all the features of plain Metafont, +called 'mfplain'. You can use that in the same way; just run 'mfplain' +instead of 'mpost'. This lets you directly process Metafont source +files with MetaPost, producing character proofs (one file for each +character) similar to those produced with Metafont in proof mode and +GFtoDVI (*note gftodvi invocation::). + + +File: web2c.info, Node: dvitomp invocation, Prev: Initial MetaPost, Up: MetaPost + +7.3 DVItoMP: DVI to MPX conversion +================================== + +DVItoMP converts DVI files into low-level MetaPost commands in a +so-called MPX file. Synopsis: + + dvitomp DVIFILE[.dvi] [MPXFILE[.mpx]] + +If MPXFILE is not specified, the output goes to the basename of DVIFILE +extended with '.mpx', e.g., 'dvitomp /wherever/foo.dvi' creates +'./foo.mpx'. + + DVItoMP supports Dvips-style color specials, such as 'color push +NAME' and 'color pop', outputting them as 'withcolor' MetaPost commands. + + The only options are '-help' and '-version' (*note Common options::). + + +File: web2c.info, Node: BibTeX, Next: WEB, Prev: MetaPost, Up: Top + +8 BibTeX: Bibliographies +************************ + +BibTeX automates much of the job of typesetting bibliographies, and +makes bibliography entries reusable in many different contexts. + +* Menu: + +* bibtex invocation:: +* Basic BibTeX style files:: The standard and semi-standard styles. + + +File: web2c.info, Node: bibtex invocation, Next: Basic BibTeX style files, Up: BibTeX + +8.1 BibTeX invocation +===================== + +BibTeX creates a printable bibliography ('.bbl') file from references in +a '.aux' file, generally written by TeX or LaTeX. The '.bbl' file is +then incorporated on a subsequent run. The basic bibliographic +information comes from '.bib' files, and a BibTeX style ('.bst') file +controls the precise contents of the '.bbl' file. Synopsis: + + bibtex [OPTION]... AUXFILE[.aux] + +The output goes to the basename of AUXFILE extended with '.bbl'; for +example, 'bibtex /wherever/foo.aux' creates './foo.bbl'. BibTeX also +writes a log file to the basename of AUXFILE extended with '.blg'. + + The names of the '.bib' and '.bst' files are specified in the '.aux' +file as well, via the '\bibliography' and '\bibliographystyle' (La)TeX +macros. BibTeX searches for '.bib' files using the 'BIBINPUTS' and +'TEXBIB' paths, and for '.bst' files using 'BSTINPUTS' (*note +(kpathsea)Supported file formats::). It does no path searching for +'.aux' files. + + The program accepts the following options, as well as the standard +'-help' and '-version' (*note Common options::): +'-terse' + Suppress the program banner and progress reports normally output. + +'-min-crossrefs=N' + If at least N (2 by default) bibliography entries refer to another + entry E via their 'crossref' field, include E in the .bbl file, + even if it was not explicitly referenced in the .aux file. For + example, E might be a conference proceedings as a whole, with the + cross-referencing entries being individual articles published in + the proceedings. + + If you want to avoid these automatic inclusions altogether, make N + a sufficiently large number, and be sure to remove any previous + .aux and .bbl files. Otherwise the option may appear to have no + effect, since BibTeX will have added the citation for E to the + .aux, and nothing will remove it. + + See also: +'btxdoc.tex' + Basic LaTeXable documentation for general BibTeX users. + +'btxhak.tex' + LaTeXable documentation for style designers. + +'btxdoc.bib' + BibTeX database file for the two above documents. + +'xampl.bib' + Example database file with all the standard entry types. + +'<ftp://ftp.math.utah.edu/pub/tex/bib/>' + A very large '.bib' and '.bst' collection, including references for + all the standard TeX books and a complete bibliography for TUGboat. + + +File: web2c.info, Node: Basic BibTeX style files, Prev: bibtex invocation, Up: BibTeX + +8.2 Basic BibTeX style files +============================ + +Here are descriptions of the four standard and four semi-standard basic +BibTeX styles. 'CTAN:/biblio/bibtex' contains these and many more (for +CTAN info, *note (kpathsea)unixtex.ftp::). + +'plain' + Sorts entries alphabetically, with numeric labels. Generally + formatted according to van Leunen's 'A Handbook for Scholars'. The + other style files listed here are based on 'plain'. + +'abbrv' + First names, month names, and journal names are abbreviated. + +'acm' + Names are printed in small caps. + +'alpha' + Alphanumeric labels, e.g., 'Knu66'. + +'apalike' + No labels at all; instead, the year appears in parentheses after + the author. Use this in conjunction with 'apalike.tex' (plain TeX) + or 'apalike.sty' (LaTeX), which also changes the citations in the + text to be '(AUTHOR, YEAR)'. + +'ieeetr' + Numeric labels, entries in citation order, IEEE abbreviations, + article titles in quotes. + +'siam' + Numeric labels, alphabetic order, 'Math. Reviews' abbreviations, + names in small caps. + +'unsrt' + Lists entries in citation order, i.e., unsorted. + +'btxbst.doc' + The template file and documentation for the standard styles. + + +File: web2c.info, Node: WEB, Next: DVI utilities, Prev: BibTeX, Up: Top + +9 WEB: Literate programming +*************************** + +"WEB" languages allow you to write a single source file that can produce +both a compilable program and a well-formatted document describing the +program in as much detail as you wish to prepare. Writing in this kind +of dual-purpose language is called "literate programming". (The Usenet +newsgroup 'comp.programming.literate' is devoted to this subject.) + + WEB-like languages have been implemented with many pairs of base +languages: Cweb provides C and Troff (*note References::); CWEB provides +C and TeX ('CTAN:/web/c_cpp/cweb'); Spiderweb provides C, C++, Awk, Ada, +many others, and TeX ('CTAN:/web/spiderweb'); and, of course, the +original WEB provides Pascal and TeX, the implementation languages for +the original TeX, Metafont, MetaPost, and related programs to come from +the TeX project at Stanford. + + The original WEB language is documented in the file 'webman.tex', +which is included in the <ftp://ftp.tug.org/tex/lib.tar.gz> archive (and +available in many other places, of course). + +* Menu: + +* tangle invocation:: +* weave invocation:: +* pooltype invocation:: + + +File: web2c.info, Node: tangle invocation, Next: weave invocation, Up: WEB + +9.1 Tangle: Translate WEB to Pascal +=================================== + +Tangle creates a compilable Pascal program from a WEB source file (*note +WEB::). Synopsis: + + tangle [OPTION]... WEBFILE[.web] [CHANGEFILE[.ch]] + +The Pascal output is written to the basename of WEBFILE extended with +'.p'; for example, 'tangle /wherever/foo.web' creates './foo.p'. Tangle +applies CHANGEFILE to WEBFILE before writing the output; by default, +there is no change file. + + If the program makes use of the WEB string facility, Tangle writes +the string pool to the basename of WEBFILE extended with '.pool'. + + The Pascal output is packed into lines of 72 characters or less, with +the only concession to readability being the termination of lines at +semicolons when this can be done conveniently. + + The program accepts the following options, as well as the standard +'--help' and '--version' (*note Common options::): + +'-length=NUMBER' + The number of characters that are considered significant in an + identifier. Whether underline characters are counted depends on + the '-underline' option. The default value is 32, the original + tangle used 7, but this proved too restrictive for use by Web2c. + +'-lowercase' +'-mixedcase' +'-uppercase' + These options specify the case of identifiers in the output of + tangle. If '-uppercase' ('-lowercase') is specified, tangle will + convert all identfiers to uppercase (lowercase). The default is + '-mixedcase', which specifies that the case will not be changed. + +'-underline' + When this option is given, tangle does not strip underline + characters from identifiers. + +'-loose' +'-strict' + These options specify how strict tangle must be when checking + identifiers for equality. The default is '-loose', which means + that tangle will follow the rules set by the case-smashing and + underline options above. If '-strict' is set, then identifiers + will always be stripped of underlines and converted to uppercase + before checking whether they collide. + + +File: web2c.info, Node: weave invocation, Next: pooltype invocation, Prev: tangle invocation, Up: WEB + +9.2 Weave: Translate WEB to TeX +=============================== + +Weave creates a TeX document from a WEB source file (*note WEB::), +assuming various macros defined in 'webmac.tex'. It takes care of +typographic details such as page layout, indentation, and italicizing +identifiers. It also automatically gathers and outputs extensive +cross-reference information. Synopsis: + + weave [OPTION]... WEBFILE[.web] [CHANGEFILE[.ch]] + +The output is to the basename of WEBFILE extended with '.tex'; for +example, 'weave /wherever/foo.web' creates './foo.tex'. Weave applies +CHANGEFILE to WEBFILE before writing the output; by default, there is no +change file. + + The program accepts the following option, as well as the standard +'-verbose', '-help' and '-version' (*note Common options::): +'-x' + Omit the cross-reference information: the index, the list of WEB + module names, and the table of contents (an empty 'CONTENTS.tex' + file will still be written when the Weave output file is processed + by TeX using the default 'webmac.tex', though). + + Conventionally, WEB programmers should define the TeX '\title' macro +at the beginning of the source file. Also, to get output of only +changed modules, one can say '\let\maybe=\iffalse' (usually as the first +change in the change file). + + +File: web2c.info, Node: pooltype invocation, Prev: weave invocation, Up: WEB + +9.3 Pooltype: Display WEB pool files +==================================== + +Pooltype shows the so-called "string number" of each string in a WEB +pool file (*note WEB::), as output by Tangle (*note tangle +invocation::), including the first 256 strings corresponding to the +possible input characters. Pooltype primarily serves as an example of +WEB conventions to implementors of the TeX system. Synopsis: + + pooltype [OPTION]... POOLFILE[.pool] + +No path searching is done for POOLFILE. Output is to standard output. + + The only options are '--help' and '--version' (*note Common +options::). + + As an example of the output, here is the (edited) output for +'tex.pool': + 0: "^^@" + 1: "^^A" + ... + 255: "^^ff" + 256: "pool size" + ... + 1314: "Using character substitution: " + (23617 characters in all.) + + In Metafont and MetaPost, the first 256 characters are actually +represented as single bytes (i.e., themselves), not in the '^^' +notation. Consider Pooltype as showing the results after conversion for +output. + + +File: web2c.info, Node: DVI utilities, Next: Font utilities, Prev: WEB, Up: Top + +10 DVI utilities +**************** + +TeX outputs a file in "DVI" (DeVice Independent) format as a compact +representation of the original document. DVI files can be translated to +meet the requirements of a real physical device, such as PostScript +printers (*note Introduction: (dvips)Top.), PCL printers (see dvilj(1)), +and X displays (see xdvi(1)). In fact, DVI translators are available +for virtually all common devices: see 'CTAN:/dviware' (for CTAN info, +*note (kpathsea)unixtex.ftp::). + + For the precise definition of the DVI file format, see (for example) +the source file 'web2c/dvitype.web'. + + The DVI-processing programs in the Web2c distribution are not device +drivers; they perform generic utility functions. + +* Menu: + +* dvicopy invocation:: Expand virtual fonts. +* dvitype invocation:: DVI to human-readable text. + + +File: web2c.info, Node: dvicopy invocation, Next: dvitype invocation, Up: DVI utilities + +10.1 DVIcopy: Canonicalize virtual font references +================================================== + +DVIcopy reads a DVI file, expands any references to virtual fonts (*note +(dvips)Virtual fonts::) to base fonts, and writes the resulting DVI +file. Thus you can use virtual fonts even if your DVI processor does +not support them, by passing the documents through DVIcopy first. +Synopsis: + + dvicopy [OPTION]... [INDVI[.dvi] [OUTDVI[.dvi]]] + + DVIcopy reads standard input if INDVI is not specified, and writes +standard output if OUTDVI is not specified. + + The program accepts the following options, as well as the standard +'-help' and '-version' (*note Common options::): +'-magnification=INTEGER' + Override existing magnification in INDVI with INTEGER; 1000 + specifies no magnification. This is equivalent to setting TeX's + '\mag' parameter. + +'-max-pages=N' + Process N pages; default is one million. + +'-page-start=PAGE-SPEC' + Start at the first page matching PAGE-SPEC, which is one or more + (signed) integers separated by periods, corresponding to TeX's + '\count0...9' parameters at '\shipout' time; '*' matches anything. + Examples: '3', '1.*.-4'. + + +File: web2c.info, Node: dvitype invocation, Prev: dvicopy invocation, Up: DVI utilities + +10.2 DVItype: Plain text transliteration of DVI files +===================================================== + +DVItype translates a DeVice Independent (DVI) file (as output by TeX, +for example) to a plain text file that humans can read. It also serves +as a DVI-validating program, i.e., if DVItype can read a file, it's +correct. Synopsis: + + dvitype [OPTION]... DVIFILE[.dvi] + +DVItype does not read any bitmap files, but it does read TFM files for +fonts referenced in DVIFILE. The usual places are searched (*note +(kpathsea)Supported file formats::). To see all the relevant paths, set +the environment variable 'KPATHSEA_DEBUG' to '-1' before running the +program. + + Output goes to standard output. + + The program accepts the following options, as well as the standard +'-help' and '-version' (*note Common options::): +'-dpi=REAL' + Do pixel movement calculations at REAL pixels per inch; default + 300.0. + +'-magnification=INTEGER' + Override existing magnification in INDVI with INTEGER; 1000 + specifies no magnification. This is equivalent to setting TeX's + '\mag' parameter. + +'-max-pages=N' + Process N pages; default is one million. + +'-output-level=N' + Verbosity level of output, from 0 to 4 (default 4): + * 0: Global document information only. + * 1: Most DVI commands included, and typeset characters + summarized. + * 2: Character and movement commands explicitly included. + * 3: DVI stack and current position calculations included. + * 4: Same information as level 3, but DVItype does random + positioning in the file, reading the DVI postamble first. + +'-page-start=PAGE-SPEC' + Start at the first page matching PAGE-SPEC, which is one or more + (signed) integers separated by periods, corresponding to TeX's + '\count0...9' parameters at '\shipout' time; '*' matches anything. + Examples: '1', '5.*.-9'. + +'-show-opcodes' + Show numeric opcode values (in decimal) for DVI commands, in braces + after the command name. This can help in debugging DVI utilities. + We use decimal because in the DVI format documentation (in + 'dvitype.web', among others) the opcodes are shown in decimal. + +* Menu: + +* dvitype output example:: + + +File: web2c.info, Node: dvitype output example, Up: dvitype invocation + +10.2.1 DVItype output example +----------------------------- + +As an example of the output from DVItype (see section above), here is +its (abridged) translation of the 'story.dvi' resulting from running the +example in 'The TeXbook', with '-output-level=4' and '-show-opcodes' on. + + ... + Options selected: + Starting page = * + Maximum number of pages = 1000000 + Output level = 4 (the works) + Resolution = 300.00000000 pixels per inch + numerator/denominator=25400000/473628672 + magnification=1000; 0.00006334 pixels per DVI unit + ' TeX output 1992.05.17:0844' + Postamble starts at byte 564. + maxv=43725786, maxh=30785863, maxstackdepth=3, totalpages=1 + Font 33: cmsl10---loaded at size 655360 DVI units + Font 23: cmbx10---loaded at size 655360 DVI units + Font 0: cmr10---loaded at size 655360 DVI units + + 42: beginning of page 1 + 87: push {141} + level 0:(h=0,v=0,w=0,x=0,y=0,z=0,hh=0,vv=0) + 88: down3 -917504 {159} v:=0-917504=-917504, vv:=-58 + 92: pop {142} + ... + 104: putrule {137} height 26214, width 30785863 (2x1950 pixels) + 113: down3 5185936 {159} v:=655360+5185936=5841296, vv:=370 + 117: push {141} + level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) + 118: right4 12265425 {146} h:=0+12265425=12265425, hh:=777 + [ ] + 123: fntdef1 23 {243}: cmbx10 + 145: fntnum23 {194} current font is cmbx10 + 146: setchar65 h:=12265425+569796=12835221, hh:=813 + 147: w3 251220 {150} h:=12835221+251220=13086441, hh:=829 + 151: setchar83 h:=13086441+418700=13505141, hh:=856 + ... + 164: setchar82 h:=17448202+565245=18013447, hh:=1142 + 165: x0 -62805 {152} h:=18013447-62805=17950642, hh:=1138 + 166: setchar89 h:=17950642+569796=18520438, hh:=1174 + [A SHORT STORY] + 167: pop {142} + level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) + ... + 550: pop {142} + level 0:(h=0,v=42152922,w=0,x=0,y=0,z=0,hh=0,vv=2670) + 551: down3 1572864 {159} v:=42152922+1572864=43725786, vv:=2770 + 555: push {141} + level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) + 556: right4 15229091 {146} h:=0+15229091=15229091, hh:=965 + 561: setchar49 h:=15229091+327681=15556772, hh:=986 + [ 1] + 562: pop {142} + level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) + 563: eop {140} + + Explanation: + + * The DVItype options are recorded at the beginning, followed by + global information about the document, including fonts used. + + * Each DVI command is preceded by its byte position in the file + ('42:', '87:', ...), and (because of the '-show-opcodes') followed + by its decimal opcode value in braces ('{141}', '{142}', ...). + + * The 'level' lines record information about the DVI stack; 'h' and + 'v' define the current position in DVI units, while 'hh' and 'vv' + are the same in pixels. + + * Text sequences are summarized in brackets, as in '[A SHORT STORY]' + and the '[ 1]'. + + +File: web2c.info, Node: Font utilities, Next: Legalisms, Prev: DVI utilities, Up: Top + +11 Font utilities +***************** + +The Web2c programs described here convert between various TeX-related +font formats; the first section below briefly describes the formats. +GFtoPK is the only one that is routinely used, as Metafont outputs GF +format, but it's most efficient for device drivers to use PK. + + The precise definitions of the PK, GF, TFM, PL, VF, and VPL formats +mentioned below are in the source files that read them; 'pktype.web', +'gftype.web', 'tftopl.web', etc. + +* Menu: + +* Font file formats:: Explanations of GF, PK, TFM, VF, ... +* gftopk invocation:: GF -> PK (compact) +* pktogf invocation:: PK -> GF (expand). +* pktype invocation:: PK -> human-readable text. +* gftype invocation:: GF -> human-readable text. +* tftopl invocation:: TFM -> PL (for editing TFM). +* pltotf invocation:: PL -> TFM (make editing results usable). +* vftovp invocation:: VF -> VPL (tftopl for virtual fonts). +* vptovf invocation:: VPL -> VF (pltotf for virtual fonts). +* Font utilities available elsewhere:: Type 1, BDF, editors, etc. + + +File: web2c.info, Node: Font file formats, Next: gftopk invocation, Up: Font utilities + +11.1 Font file formats +====================== + +(For another perspective on this, *note (dvips)Font concepts::). + + Font files come in several varieties, with suffixes like: + .tfm .*pk .*gf .*pxl (obsolete) .pl .mf .vf .vpl +Each represents a file format. + + A TFM (TeX font metric) file is a compact binary file that contains +information about each character in a font, about combinations of +characters within that font, and about the font as a whole. The font +metric information contained in TFM files is device-independent units is +used by TeX to do typesetting. Unlike the bitmap (raster) fonts +described below, TFM font files contain no information about the shapes +of characters. They describe rectangular areas and combinations +thereof, but not what will eventually be printed in those areas. + + Since TeX does scaling calculations, one TFM file serves for all +magnifications of a given typeface. On the other hand, the best printed +results are obtained when magnified (or reduced fonts) are not produced +geometrically (as done by PostScript, for example) but rather optically, +with each size a separate design (as done with Computer Modern and the +EC fonts, for example); then a separate TFM file is needed for each +size. + + At any rate, TeX produces a DVI (DeVice Independent) file from your +source document. In order to print DVI files on real devices, you need +font files defining digitized character shapes and other data. Then +previewers and printer-driver programs can translate your DVI files into +something usable by your monitor or printer. Bitmap fonts come with +suffixes such as '.600pk' or '.600gf' or '.3000pxl', where the '600' is +the horizontal dots-per-inch resolution at which the font was produced, +and the 'pk' or 'gf' or 'pxl' indicates the font format. Outline fonts +in PostScript Type 1 format have suffixes such as '.pfa' or '.pfb'. + + Fonts in pk (packed) format are in the tightly packed raster format +that is pretty much the standard today. They take up less space than +fonts in the gf (generic font) format that Metafont generates, and far +less space than fonts in pxl format. Fonts in pxl format take up gross +amounts of disk space and permit only 128 characters. They are +obsolete. + + Font files with the '.pl' (property list) suffix are the plain text +(human-readable) analog of the binary '.tfm' files. The TFtoPL and +PLtoTF programs convert between the two formats (*note tftopl +invocation:: and *note pltotf invocation::). + + Font files with the '.mf' suffix are in Metafont source format. +These are the files used by Metafont to generate rastered fonts for +specific typefaces at specific magnifications for the specific +resolution and type of mapping used by your device. + + The suffix '.vf' identifies "virtual font" files, for which '.vpl' is +the human-readable analog. See *Note vftovp invocation::, and *note +vptovf invocation::. For further discussion of virtual fonts, see +'CTAN:/doc/virtual-fonts.knuth', 'CTAN:/help/virtualfonts.txt', and +*note (dvips)Virtual fonts::. + + (This section is based on documentation in the original Unix TeX +distribution by Pierre MacKay and Elizabeth Tachikawa.) + + +File: web2c.info, Node: gftopk invocation, Next: pktogf invocation, Prev: Font file formats, Up: Font utilities + +11.2 GFtoPK: Generic to packed font conversion +============================================== + +GFtoPK converts a generic font (GF) file output by, for example, +Metafont (*note mf invocation::) to a packed font (PK) file. PK files +are considerably smaller than the corresponding gf files, so they are +generally the bitmap font format of choice. Some DVI-processing +programs, notably Dvips, only support PK files and not GF files. +Synopsis: + + gftopk [OPTION]... GFNAME.DPI[gf] [PKFILE] + +The font GFNAME is searched for in the usual places (*note +(kpathsea)Glyph lookup::). To see all the relevant paths, set the +environment variable 'KPATHSEA_DEBUG' to '-1' before running the +program. + + The suffix 'gf' is supplied if not already present. This suffix is +not an extension; no '.' precedes it: for instance, 'cmr10.600gf'. + + If PKFILE is not specified, the output is written to the basename of +'GFNAME.DPIpk', e.g., 'gftopk /wherever/cmr10.600gf' creates +'./cmr10.600pk'. + + The only options are '--verbose', '--help', and '--version' (*note +Common options::). + + +File: web2c.info, Node: pktogf invocation, Next: pktype invocation, Prev: gftopk invocation, Up: Font utilities + +11.3 PKtoGF: Packed to generic font conversion +============================================== + +PKtoGF converts a packed font (PK) file to a generic font (GF) file. +Since PK format is much more compact than GF format, the most likely +reason to do this is to run GFtype (*note gftype invocation::) on the +result, so you can see the bitmap images. Also, a few old utility +programs do not support PK format. Synopsis: + + pktogf [OPTION]... PKNAME.DPI[pk] [GFFILE] + +The font PKNAME is searched for in the usual places (*note +(kpathsea)Glyph lookup::). To see all the relevant paths, set the +environment variable 'KPATHSEA_DEBUG' to '-1' before running the +program. + + The suffix 'pk' is supplied if not already present. This suffix is +not an extension; no '.' precedes it: for instance, 'cmr10.600pk'. + + If GFFILE is not specified, the output is written to the basename of +'PKNAME.DPIgf', e.g., 'pktogf /wherever/cmr10.600pk' creates +'./cmr10.600gf'. + + The only options are '--verbose', '--help', and '--version' (*note +Common options::). + + +File: web2c.info, Node: pktype invocation, Next: gftype invocation, Prev: pktogf invocation, Up: Font utilities + +11.4 PKtype: Plain text transliteration of packed fonts +======================================================= + +PKtype translates a packed font (PK) bitmap file (as output by GFtoPK, +for example) to a plain text file that humans can read. It also serves +as a PK-validating program, i.e., if PKtype can read a file, it's +correct. Synopsis: + + pktype PKNAME.DPI[pk] + + The font PKNAME is searched for in the usual places (*note +(kpathsea)Glyph lookup::). To see all the relevant paths, set the +environment variable 'KPATHSEA_DEBUG' to '-1' before running the +program. + + The suffix 'pk' is supplied if not already present. This suffix is +not an extension; no '.' precedes it: for instance, 'cmr10.600pk'. + + The translation is written to standard output. + + The only options are '-help' and '-version' (*note Common options::). + + As an example of the output, here is the (abridged) translation of +the letter 'K' in 'cmr10', as rendered at 600dpi with the mode 'ljfour' +from <modes.mf> (available from 'ftp://ftp.tug.org/tex/modes.mf'). + + 955: Flag byte = 184 Character = 75 Packet length = 174 + Dynamic packing variable = 11 + TFM width = 815562 dx = 4259840 + Height = 57 Width = 57 X-offset = -3 Y-offset = 56 + [2]23(16)17(8)9(25)11(13)7(27)7(16)7(28)4(18)7(28)2(20)7(27)... + ... + (14)9(24)12(5)[2]23(13)21 + +Explanation: + +'955' + The byte position in the file where this character starts. + +'Flag byte' +'Dynamic packing variable' + Related to the packing for this character; see the source code. + +'Character' + The character code, in decimal. + +'Packet length' + The total length of this character definition, in bytes. + +'TFM width' + The device-independent (TFM) width of this character. It is 2^24 + times the ratio of the true width to the font's design size. + +'dx' + The device-dependent width, in "scaled pixels", i.e., units of + horizontal pixels times 2^16. + +'Height' +'Width' + The bitmap height and width, in pixels. + +'X-offset' +'Y-offset' + Horizontal and vertical offset from the upper left pixel to the + reference (origin) pixel for this character, in pixels (right and + down are positive). The "reference pixel" is the pixel that + occupies the unit square in Metafont; the Metafont reference point + is the lower left hand corner of this pixel. Put another way, the + x-offset is the negative of the left side bearing; the right side + bearing is the horizontal escapement minus the bitmap width plus + the x-offset. + +'[2]23(16)...' + Finally, run lengths of black pixels alternate with parenthesized + run lengths of white pixels, and brackets indicate a repeated row. + + +File: web2c.info, Node: gftype invocation, Next: tftopl invocation, Prev: pktype invocation, Up: Font utilities + +11.5 GFtype: Plain text transliteration of generic fonts +======================================================== + +GFtype translates a generic font (GF) bitmap file (as output by +Metafont, for example) to a plain text file that humans can read. It +also serves as a GF-validating program, i.e., if GFtype can read a file, +it's correct. Synopsis: + + gftype [OPTION]... GFNAME.DPI[gf] + + The font GFNAME is searched for in the usual places (*note +(kpathsea)Glyph lookup::). To see all the relevant paths, set the +environment variable 'KPATHSEA_DEBUG' to '-1' before running the +program. + + The suffix 'gf' is supplied if not already present. This suffix is +not an extension; no '.' precedes it: for instance, 'cmr10.600gf'. + + The translation is written to standard output. + + The program accepts the following options, as well as the standard +'-help' and '-version' (*note Common options::): +'-images' + Show the characters' bitmaps using asterisks and spaces. + +'-mnemonics' + Translate all commands in the GF file. + + As an example of the output, here is the (abrdiged) translation of +the letter 'K' in 'cmr10', as rendered at 600dpi with the mode 'ljfour' +from 'modes.mf' (available from <ftp://ftp.tug.org/tex/modes.mf>), with +both '-mnemonics' and '-images' enabled. + + GFtype outputs the information about a character in two places: a +main definition and a one-line summary at the end. We show both. Here +is the main definition: + + 2033: beginning of char 75: 3<=m<=60 0<=n<=56 + (initially n=56) paint (0)24(12)20 + 2043: newrow 0 (n=55) paint 24(12)20 + 2047: newrow 0 (n=54) paint 24(12)20 + 2051: newrow 0 (n=53) paint 24(12)20 + 2055: newrow 7 (n=52) paint 10(21)13 + 2059: newrow 8 (n=51) paint 8(23)9 + ... + 2249: newrow 8 (n=5) paint 8(23)11 + 2253: newrow 7 (n=4) paint 10(22)12 + 2257: newrow 0 (n=3) paint 24(11)22 + 2261: newrow 0 (n=2) paint 24(11)22 + 2265: newrow 0 (n=1) paint 24(11)22 + 2269: newrow 0 (n=0) paint 24(11)22 + 2273: eoc + .<--This pixel's lower left corner is at (3,57) in METAFONT coordinates + ************************ ******************** + ************************ ******************** + ************************ ******************** + ************************ ******************** + ********** ************* + ******** ********* + ... + ******** *********** + ********** ************ + ************************ ********************** + ************************ ********************** + ************************ ********************** + ************************ ********************** + .<--This pixel's upper left corner is at (3,0) in METAFONT coordinates + +Explanation: + +'2033' +'2043' +'...' + The byte position in the file where each GF command starts. + +'beginning of char 75' + The character code, in decimal. + +'3<=m<=60 0<=n<=56' + The character's bitmap lies between 3 and 60 (inclusive) + horizontally, and between 0 and 56 (inclusive) vertically. (m is a + column position and n is a row position.) Thus, 3 is the left side + bearing. The right side bearing is the horizontal escapement + (given below) minus the maximum m. + +'(initially n=56) paint (0)24(12)20' + The first row of pixels: 0 white pixels, 24 black pixels, 12 white + pixels, etc. + +'newrow 0 (n=55) paint 24(12)20' + The second row of pixels, with zero leading white pixels on the + row. + +'eoc' + The end of the main character definition. + + Here is the GF postamble information that GFtype outputs at the end: + + Character 75: dx 4259840 (65), width 815562 (64.57289), loc 2033 + + Explanation: + +'dx' + The device-dependent width, in "scaled pixels", i.e., units of + horizontal pixels times 2^16. The '(65)' is simply the same number + rounded. If the vertical escapement is nonzero, it would appear + here as a 'dy' value. + +'width' + The device-independent (TFM) width of this character. It is 2^24 + times the ratio of the true width to the font's design size. The + '64.57289' is the same number converted to pixels. + +'loc' + The byte position in the file where this character starts. + + +File: web2c.info, Node: tftopl invocation, Next: pltotf invocation, Prev: gftype invocation, Up: Font utilities + +11.6 TFtoPL: TeX font metric to property list conversion +======================================================== + +TFtoPL translates a TeX font metric (TFM, *note (dvips)Metric files::) +file (as output by Metafont, for example) to "property list format" (a +list of parenthesized items describing the font) that humans can edit or +read. This program is mostly used by people debugging TeX +implementations, writing font utilities, etc. Synopsis: + + tftopl [OPTION]... TFMNAME[.tfm] [PLFILE[.pl]] + + The font TFMNAME (extended with '.tfm' if necessary) is searched for +in the usual places (*note (kpathsea)Supported file formats::). To see +all the relevant paths, set the environment variable 'KPATHSEA_DEBUG' to +'-1' before running the program. + + If PLFILE (which is extended with '.pl' if necessary) is not +specified, the property list file is written to standard output. The +property list file can be converted back to TFM format by the companion +program TFtoPL (see the next section). + + The program accepts the following option, as well as the standard +'-verbose', '-help' and '-version' (*note Common options::): +'-charcode-format=TYPE' + Output character codes in the PL file according to TYPE: either + 'octal' or 'ascii'. Default is 'ascii' for letters and digits, + octal for all other characters. Exception: if the font's coding + scheme starts with 'TeX math sy' or 'TeX math ex', all character + codes are output in octal. + + In 'ascii' format, character codes that correspond to graphic + characters, except for left and right parentheses, are output as a + 'C' followed by the single character: 'C K', for example. In octal + format, character codes are output as the letter 'O' followed by + octal digits, as in 'O 113' for 'K'. + + 'octal' format is useful for symbol and other non-alphabetic fonts, + where using ASCII characters for the character codes is merely + confusing. + + As an example of the output, here is the (abridged) property list +translation of 'cmr10.tfm': + + (FAMILY CMR) + (FACE O 352) + (CODINGSCHEME TEX TEXT) + (DESIGNSIZE R 10.0) + (COMMENT DESIGNSIZE IS IN POINTS) + (COMMENT OTHER SIZES ARE MULTIPLES OF DESIGNSIZE) + (CHECKSUM O 11374260171) + (FONTDIMEN + (SLANT R 0.0) + (SPACE R 0.333334) + (STRETCH R 0.166667) + (SHRINK R 0.111112) + (XHEIGHT R 0.430555) + (QUAD R 1.000003) + (EXTRASPACE R 0.111112) + ) + (LIGTABLE + ... + (LABEL C f) + (LIG C i O 14) + (LIG C f O 13) + (LIG C l O 15) + (KRN O 47 R 0.077779) + (KRN O 77 R 0.077779) + (KRN O 41 R 0.077779) + (KRN O 51 R 0.077779) + (KRN O 135 R 0.077779) + (STOP) + ... + ) + ... + (CHARACTER C f + (CHARWD R 0.305557) + (CHARHT R 0.694445) + (CHARIC R 0.077779) + (COMMENT + (LIG C i O 14) + (LIG C f O 13) + (LIG C l O 15) + (KRN O 47 R 0.077779) + (KRN O 77 R 0.077779) + ... + ) + ) + ... + + As you can see, the general format is a list of parenthesized +"properties", nested where necessary. + + * The first few items ('FAMILY', 'FACE', and so on) are the so-called + "headerbyte" information from Metafont, giving general information + about the font. + + * The 'FONTDIMEN' property defines the TeX '\fontdimen' values. + + * The 'LIGTABLE' property defines the ligature and kerning table. + 'LIG' properties define ligatures: in the example above, an 'f' (in + the 'LABEL') followed by an 'i' is a ligature, i.e., a typesetting + program like TeX replaces those two consecutive characters by the + character at position octal '014 in the current font--presumably + the 'fi' ligature. 'KRN' properties define kerns: if an 'f' is + followed by character octal '047 (an apostrophe), TeX inserts a + small amount of space between them: 0.077779 times the design size + the font was loaded at (about three-quarters of a printer's point + by default in this case, or .001 inches). + + * The 'CHARACTER' property defines the dimensions of a character: its + width, height, depth, and italic correction, also in design-size + units, as explained in the previous item. For our example 'f', the + depth is zero, so that property is omitted. TFtoPL also inserts + any kerns and ligatures for this character as a comment. + + +File: web2c.info, Node: pltotf invocation, Next: vftovp invocation, Prev: tftopl invocation, Up: Font utilities + +11.7 PLtoTF: Property list to TeX font metric conversion +======================================================== + +PLtoTF translates a property list file (as output by TFtoPL, for +example) to TeX font metric (TFM, *note (dvips)Metric files::) format. +It's much easier for both programs and humans to create the (plain text) +property list files and let PLtoTF take care of creating the binary TFM +equivalent than to output TFM files directly. Synopsis: + + pltotf [OPTION]... PLFILE[.pl] [TFMFILE[.tfm]] + + If TFMFILE (extended with '.tfm' if necessary) is not specified, the +TFM file is written to the basename of 'PLFILE.tfm', e.g., 'pltotf +/wherever/cmr10.pl' creates './cmr10.tfm'. (Since TFM files are binary, +writing to standard output by default is undesirable.) + + The only options are '-verbose', '-help', and '-version' (*note +Common options::). + + For an example of property list format, see the previous section. + + +File: web2c.info, Node: vftovp invocation, Next: vptovf invocation, Prev: pltotf invocation, Up: Font utilities + +11.8 VFtoVP: Virtual font to virtual property lists +=================================================== + +VFtoVP translates a virtual font metric (VF, *note (dvips)Virtual +fonts::) file and its accompanying TeX font metric (TFM, *note +(dvips)Metric files::) file (as output by VPtoVF, for example) to +"virtual property list format" (a list of parenthesized items describing +the virtual font) that humans can edit or read. This program is mostly +used by people debugging virtual font utilities. Synopsis: + + vftovp [OPTION]... VFNAME[.vf] [TFMNAME[.tfm] [VPLFILE[.vpl]]] + + The fonts VFNAME and TFMNAME (extended with '.vf' and '.tfm' if +necessary) are searched for in the usual places (*note +(kpathsea)Supported file formats::). To see all the relevant paths, set +the environment variable 'KPATHSEA_DEBUG' to '-1' before running the +program. If TFMNAME is not specified, VFNAME (without a trailing '.vf') +is used. + + If VPLFILE (extended with '.vpl' if necessary) is not specified, the +property list file is written to standard output. The property list +file can be converted back to VF and TFM format by the companion program +VFtoVP (see the next section). + + The program accepts the following option, as well as the standard +'-verbose', '-help' and '-version' (*note Common options::): +'-charcode-format=TYPE' + Output character codes in the PL file according to TYPE: either + 'octal' or 'ascii'. Default is 'ascii' for letters and digits, + octal for all other characters. Exception: if the font's coding + scheme starts with 'TeX math sy' or 'TeX math ex', all character + codes are output in octal. + + In 'ascii' format, character codes that correspond to graphic + characters, except for left and right parentheses, are output as a + 'C' followed by the single character: 'C K', for example. In octal + format, character codes are output as the letter 'O' followed by + octal digits, as in 'O 113' for 'K'. + + 'octal' format is useful for symbol and other non-alphabetic fonts, + where using ASCII characters for the character codes is merely + confusing. + + +File: web2c.info, Node: vptovf invocation, Next: Font utilities available elsewhere, Prev: vftovp invocation, Up: Font utilities + +11.9 VPtoVF: Virtual property lists to virtual font +=================================================== + +VPtoVF translates a virtual property list file (as output by VFtoVP, for +example) to virtual font (VF, *note (dvips)Virtual fonts::) and TeX font +metric (TFM, *note (dvips)Metric files::) files. It's much easier for +both programs and humans to create the (plain text) property list files +and let VPtoVF take care of creating the binary VF and TFM equivalents +than to output them directly. Synopsis: + + vptovf [OPTION]... VPLFILE[.vpl] [VFFILE[.vf] [TFMFILE[.tfm]]] + + If VFFILE (extended with '.vf' if necessary) is not specified, the VF +output is written to the basename of 'VPLFILE.vf'; similarly for +TFMFILE. For example, 'vptovf /wherever/ptmr.vpl' creates './ptmr.vf' +and './ptmr.tfm'. + + The only options are '-verbose', '-help', and '-version' (*note +Common options::). + + +File: web2c.info, Node: Font utilities available elsewhere, Prev: vptovf invocation, Up: Font utilities + +11.10 Font utilities available elsewhere +======================================== + +The Web2c complement of font utilities merely implements a few basic +conversions. Many other more sophisticated font utilities exist; most +are in 'CTAN:/fonts/utilities' (for CTAN info, *note +(kpathsea)unixtex.ftp::). Here are some of the most commonly-requested +items: + + * AFM (Adobe font metric) to TFM conversion: *note (dvips)Invoking + afm2tfm::, and 'CTAN:/fonts/utilities/afmtopl'. + + * BDF (the X bitmap format) conversion: + <ftp://ftp.tug.org/tex/bdf.tar.gz>. + + * Creating fonts using MetaPost: MetaType1. + <ftp://bop.eps.gda.pl/pub/metatype1>. This is used to create the + excellent Latin Modern font family ('CTAN:/fonts/lm'), which + extends Computer Modern to a vast repertoire of scripts. + + * Editing of bitmap fonts: Xbfe from the GNU font utilities mentioned + below; the X BDF-editing programs available from + <ftp://ftp.x.org/R5contrib/xfed.tar.Z> and + <ftp://ftp.x.org/R5contrib/xfedor.tar.Z>; and finally, if your + fonts have only 128 characters, you can use the old 'gftopxl', + 'pxtoch', and 'chtopx' programs from <ftp://ftp.tug.org/tex/web>. + + * Editing of outline fonts: FontForge, <fontforge.sourceforge.net>. + This is a very elaborate program with support for many outline + formats (Type 1, OpenType, TrueType, ...), and many advanced font + editing features. + + * PK bitmaps from PostScript outline fonts: gsftopk from the 'xdvi' + distribution. Alternatively, 'ps2pk', from + 'CTAN:/fonts/utilities/ps2pk'. + + * PostScript Type 1 font format conversion (i.e., between PFA and PFB + formats): <https://www.lcdf.org/type>. + + * Tracing bitmaps to fitted outlines: Autotrace + (<http://autotrace.sourceforge.net>), Potrace + (<http://potrace.sourceforge.net>). For Metafont fonts, either of + the two programs 'mftrace' (<http://www.xs4all.nl/~hanwen/mftrace>) + or 'textrace' (<http://textrace.sourceforge.net>) make the job + easier. + + * Virtual font creation: <https://ctan.org/pkg/fontinst>. + + +File: web2c.info, Node: Legalisms, Next: References, Prev: Font utilities, Up: Top + +Appendix A Legalisms +******************** + +In general, each file has its own copyright notice stating the copying +permissions for that file. Following is a summary. + + The Stanford TeX programs and Web2c system itself are in the public +domain (<https://tug.org/texlive/copying.html>). The sources may be +copied verbatim, or used as the starting point of new software under +different names; however, per the wishes of the authors, they should be +modified only through a '.ch' file, but this is in the nature of a +development request rather than a legal requirement. + + MLTeX, pdfTeX, LuaTeX, XeTeX, and all the other derived engines have +used various license terms for their additions to the base code, often +the GPL (see <https://www.gnu.org/licenses/#GPL> or (for example) the +file 'web2c/pdftexdir/COPYINGv2'. They also mostly make use of +additional libraries with their own (compatible) terms. Please see each +program's sources. + + The Kpathsea library is covered by the GNU Lesser General Public +License (*note (kpathsea)Introduction::). Therefore, the _binaries_ +resulting from a standard Web2c compilation are also covered by the +LGPL; so if you (re)distribute the binaries, you must also (offer to) +distribute the complete source that went into those binaries. See +<https://gnu.org/licenses/#LGPL> or the file +'kpathsea/COPYING.LESSERv2'. + + +File: web2c.info, Node: References, Next: Index, Prev: Legalisms, Up: Top + +Appendix B References +********************* + + 1. Kpathsea: *Note Introduction: (kpathsea)Top. + + 2. Dvips and Afm2tfm: *Note Introduction: (dvips)Top. + + 3. The TeX Users Group: <https://tug.org>. For an introduction to the + TeX system, see <https://tug.org/begin.html>. + + 4. TUGboat, the principal journal for the TeX world: + <https://tug.org/TUGboat>. + + 5. TeX and computer typesetting in general: + <ftp://ftp.math.utah.edu/pub/tex/bib/texbook1.bib>. + + 6. For a bibliography of formal articles and technical reports on the + TeX project, see the books 'TeX: The Program' or 'Metafont: The + Program' cited below. + + 7. [Bil87] Neenie Billawala. Write-white printing engines and tuning + fonts with Metafont. 'TUGboat', 8(1):29-32, April 1987. + <https://tug.org/TUGboat/tb08-1/tb17billawala.pdf>. + + 8. [Hob89] John D. Hobby. A Metafont-like system with PS output. + 'TUGboat', 10(4):505-512, December 1989. + <https://tug.org/metapost>. + + 9. [Hob92] John D. Hobby. A User's Manual for MetaPost. Technical + Report CSTR-162, AT&T Bell Laboratories, 1992. + + 10. [Hob93] John D. Hobby. Drawing Graphs with MetaPost. Technical + Report CSTR-164, AT&T Bell Laboratories, 1993. + + 11. [HS91] Samuel P. Harbison and Guy L. Steele Jr. 'C--A Reference + Manual'. Prentice-Hall, Upper Saddle River, NJ 07458, USA, third + edition, 1991. An authoritative reference to the C programming + language, and a good companion to Kernighan and Ritchie. + + 12. [KL93] Donald E. Knuth and Silvio Levy. 'The CWEB System of + Structured Documentation, Version 3.0'. Addison-Wesley, Reading, + MA, USA, 1993. <https://ctan.org/pkg/cweb>. + + 13. [Knu84] Donald E. Knuth. A torture test for TeX. Report No. + STAN-CS-84-1027, Stanford University, Department of Computer + Science, 1984. + + 14. [Knu86a] Donald E. Knuth. A Torture Test for METAFONT. Report No. + STAN-CS-86-1095, Stanford University, Department of Computer + Science, 1986. + + 15. [Knu86b] Donald E. Knuth. 'The TeXbook', volume A of 'Computers + and Typesetting'. Addison-Wesley, Reading, MA, USA, 1986. + + 16. [Knu86c] Donald E. Knuth. 'TeX: The Program', volume B of + 'Computers and Typesetting'. Addison-Wesley, Reading, MA, USA, + 1986. + + 17. [Knu86d] Donald E. Knuth. 'The METAFONTbook', volume C of + 'Computers and Typesetting'. Addison-Wesley, Reading, MA, USA, + 1986. + + 18. [Knu86e] Donald E. Knuth. 'METAFONT: The Program', volume D of + 'Computers and Typesetting'. Addison-Wesley, Reading, MA, USA, + 1986. + + 19. [Knu86f] Donald E. Knuth. 'Computer Modern Typefaces', volume E + of 'Computers and Typesetting'. Addison-Wesley, Reading, MA, USA, + 1986. + + 20. [Knu89] Donald E. Knuth. The errors of TeX. 'Software--Practice + and Experience', 19(7):607-681, July 1989. This is an updated + version of Knuth:1988:ET. + + 21. [Knu90] Donald Knuth. Virtual Fonts: More Fun for Grand Wizards. + 'TUGboat', 11(1):13-23, April 1990. + <https://tug.org/TUGboat/tb11-1/tb27knut.pdf>. + + 22. [Knu92] Donald E. Knuth. 'Literate Programming'. CSLI Lecture + Notes Number 27. Stanford University Center for the Study of + Language and Information, Stanford, CA, USA, 1992. + + 23. [Lam94] Leslie Lamport. 'LaTeX: A Document Preparation System: + User's Guide and Reference Manual'. Addison-Wesley, Reading, MA, + USA, second edition, 1994. Reprinted with corrections, 1996. + + 24. [Lia83] Franklin Mark Liang. Word hy-phen-a-tion by com-pu-ter. + Technical Report STAN-CS-83-977, Stanford University, August 1983. + <https://tug.org/docs/liang/liang-thesis.pdf>. + + 25. [Mac91] Pierre A. MacKay. Looking at the pixels: Quality control + for 300 dpi laser printer fonts, especially Metafonts. In Robert + A. Morris and Jacques Andre, editors, 'Raster Imaging and Digital + Typography II--Papers from the second RIDT meeting, held in Boston, + Oct. 14-16, 1991', pages 205-215, New York, 1991. Cambridge + University Press. + + +File: web2c.info, Node: Index, Prev: References, Up: Top + +Index +***** + + +* Menu: + +* " character, ignored in filenames: \input filenames. (line 22) +* #define options: Compile-time options. + (line 6) +* $ expansion in filenames: \input filename caveats. + (line 17) +* %& magic number: Determining the memory dump to use. + (line 19) +* - starting a filename: Option conventions. (line 19) +* - starts option names: Option conventions. (line 11) +* -- starts option names: Option conventions. (line 11) +* --disable-dump-share configure option: Hardware and memory dumps. + (line 6) +* --disable-mf-nowin: Online Metafont graphics. + (line 65) +* --enable-epsfwin: Online Metafont graphics. + (line 20) +* --enable-hp2627win: Online Metafont graphics. + (line 28) +* --enable-ipc configure option: tex invocation. (line 93) +* --enable-mftalkwin: Online Metafont graphics. + (line 31) +* --enable-next: Online Metafont graphics. + (line 35) +* --enable-regiswin: Online Metafont graphics. + (line 40) +* --enable-suntoolswin: Online Metafont graphics. + (line 43) +* --enable-tektronixwin: Online Metafont graphics. + (line 48) +* --enable-unitermwin: Online Metafont graphics. + (line 51) +* --help common option: Common options. (line 11) +* --verbose common option: Common options. (line 15) +* --version common option: Common options. (line 18) +* --with-editor=CMD: Editor invocation. (line 10) +* --with-mf-x-toolkit=KIT: Online Metafont graphics. + (line 59) +* --with-x: Online Metafont graphics. + (line 57) +* -8bit: Common options. (line 110) +* -base=BASE: Determining the memory dump to use. + (line 15) +* -base=DUMPNAME: Common options. (line 39) +* -change=CHFILE: mft invocation. (line 63) +* -charcode-format=TYPE: tftopl invocation. (line 27) +* -charcode-format=TYPE <1>: vftovp invocation. (line 30) +* -cnf-line: Common options. (line 25) +* -D compiler options: Compile-time options. + (line 6) +* -disable-write18: tex invocation. (line 128) +* -dpi=REAL: dvitype invocation. (line 24) +* -enable-write18: tex invocation. (line 127) +* -enc: tex invocation. (line 86) +* -file-line-error: Common options. (line 30) +* -file-line-error-style: Common options. (line 31) +* -fmt=DUMPNAME: Common options. (line 39) +* -fmt=FMT: Determining the memory dump to use. + (line 15) +* -geometry, supported with Xt: Online Metafont graphics. + (line 69) +* -halt-on-error: Common options. (line 46) +* -images: gftype invocation. (line 26) +* -ini: Common options. (line 50) +* -ini <1>: Initial and virgin. (line 10) +* -interaction=STRING: Common options. (line 55) +* -ipc: tex invocation. (line 93) +* -ipc-start: tex invocation. (line 93) +* -jobname=STRING: Common options. (line 60) +* -kpathsea-debug=NUMBER: Common options. (line 64) +* -length=NUMBER: tangle invocation. (line 27) +* -loose: tangle invocation. (line 46) +* -lowercase: tangle invocation. (line 35) +* -magnification=INTEGER: dvicopy invocation. (line 20) +* -magnification=INTEGER <1>: dvitype invocation. (line 28) +* -max-pages=N: dvicopy invocation. (line 25) +* -max-pages=N <1>: dvitype invocation. (line 33) +* -mem=DUMPNAME: Common options. (line 39) +* -min-crossrefs=N: bibtex invocation. (line 31) +* -mixedcase: tangle invocation. (line 35) +* -mktex=FILETYPE: tex invocation. (line 103) +* -mktex=FILETYPE <1>: mf invocation. (line 87) +* -mltex: tex invocation. (line 108) +* -mnemonics: gftype invocation. (line 29) +* -no-file-line-error: Common options. (line 31) +* -no-mktex=FILETYPE: tex invocation. (line 103) +* -no-mktex=FILETYPE <1>: mf invocation. (line 87) +* -no-parse-first-line: Common options. (line 77) +* -no-shell-escape: tex invocation. (line 121) +* -output-comment=STRING: tex invocation. (line 113) +* -output-directory: Common options. (line 71) +* -output-directory <1>: Output file location. + (line 15) +* -output-level=N: dvitype invocation. (line 36) +* -overflow-label-offset=POINTS: gftodvi invocation. (line 59) +* -page-start=PAGE-SPEC: dvicopy invocation. (line 28) +* -page-start=PAGE-SPEC <1>: dvitype invocation. (line 46) +* -parse-first-line: Common options. (line 76) +* -progname=STRING: Common options. (line 82) +* -progname=STRING <1>: Determining the memory dump to use. + (line 17) +* -recorder: Common options. (line 89) +* -shell-escape: tex invocation. (line 120) +* -shell-restricted: tex invocation. (line 122) +* -show-opcodes: dvitype invocation. (line 52) +* -strict: tangle invocation. (line 46) +* -style=MFTFILE: mft invocation. (line 67) +* -T: mpost invocation. (line 111) +* -terse: bibtex invocation. (line 28) +* -tex=TEXPROGRAM: mpost invocation. (line 114) +* -translate-file=TCXFILE: Common options. (line 103) +* -troff: mpost invocation. (line 111) +* -underline: tangle invocation. (line 41) +* -uppercase: tangle invocation. (line 35) +* -x: weave invocation. (line 22) +* ., used for output: Output file location. + (line 6) +* .2602gf: mf invocation. (line 48) +* .aux cross-reference files: bibtex invocation. (line 6) +* .base: Initial Metafont. (line 6) +* .bbl bibliography files: bibtex invocation. (line 6) +* .bib bibliography databases: bibtex invocation. (line 6) +* .blg BibTeX log file: bibtex invocation. (line 14) +* .fmt: Initial TeX. (line 6) +* .mf: mf invocation. (line 24) +* .mp: mpost invocation. (line 26) +* .mps files and PDF: mpost invocation. (line 82) +* .NNN PostScript figures: mpost invocation. (line 31) +* .NNNgf generic fonts: mf invocation. (line 34) +* .tcx character translation files: Common options. (line 103) +* .tcx character translation files <1>: TCX files. (line 6) +* .tex: tex invocation. (line 20) +* .tfm output: mf invocation. (line 43) +* .tfm output <1>: mpost invocation. (line 31) +* .Xdefaults: Online Metafont graphics. + (line 69) +* .Xresources: Online Metafont graphics. + (line 69) +* 2602gf: mf invocation. (line 48) +* 8 bit clean: Common options. (line 110) +* 8 bit clean output, specifying: Common options. (line 110) +* 8-bit characters: TCX files. (line 6) +* \bibliography: bibtex invocation. (line 18) +* \bibliographystyle: bibtex invocation. (line 18) +* \charsubdef and MLTeX: \charsubdef. (line 6) +* \countN: dvicopy invocation. (line 28) +* \countN <1>: dvitype invocation. (line 46) +* \font and dynamic generation: tex invocation. (line 41) +* \fontdimen: tftopl invocation. (line 99) +* \immediate\write18: Shell escapes. (line 6) +* \input braced (grouped) filename: \input braced filename. + (line 6) +* \input filename caveats: \input filename caveats. + (line 6) +* \input filenames: \input filenames. (line 6) +* \input quoted filename: \input quoted filename. + (line 6) +* \input, and pipes: Shell escapes. (line 64) +* \mag: dvicopy invocation. (line 20) +* \mag <1>: dvitype invocation. (line 28) +* \openin, and pipes: Shell escapes. (line 64) +* \openout and security: tex invocation. (line 48) +* \openout, and pipes: Shell escapes. (line 64) +* \output routine, and \write: Shell escapes. (line 28) +* \pdfshellescape: Shell escapes. (line 64) +* \string, and \input filenames: \input filename caveats. + (line 29) +* \tracingcharsubdef and MLTeX: \tracingcharsubdef. (line 6) +* \tracinglostchars and MLTeX: \tracingcharsubdef. (line 11) +* \write18 shell escape extension: Shell escapes. (line 6) +* ^^ notation, avoiding: TCX files. (line 87) +* ~ expansion in filenames: \input filename caveats. + (line 17) +* abbrv.bst: Basic BibTeX style files. + (line 16) +* accented character: TCX files. (line 6) +* accents, hyphenating words with: MLTeX. (line 6) +* acknowledgements: Introduction. (line 54) +* acm.bst: Basic BibTeX style files. + (line 19) +* Ada, WEB for: WEB. (line 12) +* additional Make targets: Additional targets. (line 6) +* AFM to TFM conversion: Font utilities available elsewhere. + (line 12) +* afm2tfm: Font utilities available elsewhere. + (line 12) +* afmtopl: Font utilities available elsewhere. + (line 12) +* Aleph: TeX extensions. (line 15) +* aliases for fonts: Path searching. (line 14) +* alpha.bst: Basic BibTeX style files. + (line 22) +* American Mathematical Society, typesetting system: Formats. (line 35) +* AMSTeX: Formats. (line 35) +* apalike.bst: Basic BibTeX style files. + (line 25) +* architecture dependencies: Hardware and memory dumps. + (line 6) +* array limit, fixed: Runtime options. (line 45) +* array sizes: Runtime options. (line 6) +* assembly language routines: Compile-time options. + (line 21) +* autotrace: Font utilities available elsewhere. + (line 42) +* Awk, WEB for: WEB. (line 12) +* base file, determining: Determining the memory dump to use. + (line 6) +* base files: Initial Metafont. (line 6) +* base files, need mode definitions: Modes. (line 6) +* base files, plain only: Initial Metafont. (line 26) +* base files, sharing: Hardware and memory dumps. + (line 6) +* bases Make target: Additional targets. (line 28) +* basic BibTeX style files: Basic BibTeX style files. + (line 6) +* basic fonts and macros: Installation. (line 33) +* batch languages: TeX. (line 9) +* BDF and GF conversion: Font utilities available elsewhere. + (line 15) +* beamer, package: Formats. (line 57) +* beginfig: mpost invocation. (line 31) +* Berry, Karl: Introduction. (line 43) +* BIBINPUTS, search path for bib files: bibtex invocation. (line 18) +* bibliographies, creating: BibTeX. (line 6) +* bibliography: References. (line 6) +* bibliography items, cross-referenced: bibtex invocation. (line 31) +* bibtex: bibtex invocation. (line 6) +* BibTeX: BibTeX. (line 6) +* BibTeX collection: bibtex invocation. (line 58) +* BibTeX style files: Basic BibTeX style files. + (line 6) +* BigEndian machines: Hardware and memory dumps. + (line 6) +* binaries, linking: Common options. (line 82) +* blank lines, in TCX files: TCX files. (line 66) +* boxes, memory for: Runtime options. (line 20) +* braced filename for \input: \input braced filename. + (line 6) +* breakpoints, memory for: Runtime options. (line 20) +* Breitenlohner, Peter: Introduction. (line 9) +* BSTINPUTS, search path for bst files: bibtex invocation. (line 18) +* btex for MetaPost labels: mpost invocation. (line 44) +* btxdoc.bib: bibtex invocation. (line 52) +* btxdoc.tex: bibtex invocation. (line 46) +* btxhak.tex: bibtex invocation. (line 49) +* byte position: pktype invocation. (line 40) +* byte position <1>: gftype invocation. (line 76) +* byte swapping: Hardware and memory dumps. + (line 13) +* c-sources Makefile target: Additional targets. (line 12) +* caveats for \input filenames: \input filename caveats. + (line 6) +* change files, and MFT: mft invocation. (line 63) +* change files, and Tangle: tangle invocation. (line 11) +* change files, and Weave: weave invocation. (line 14) +* changing error messages style: Common options. (line 31) +* character codes, in GFtype output: gftype invocation. (line 79) +* character codes, in PKtype output: pktype invocation. (line 47) +* character codes, in TCX files: TCX files. (line 77) +* character proofs of fonts: gftodvi invocation. (line 6) +* CHARACTER property: tftopl invocation. (line 112) +* character translation files: TCX files. (line 6) +* CHARDP property: tftopl invocation. (line 112) +* CHARHT property: tftopl invocation. (line 112) +* CHARIC property: tftopl invocation. (line 112) +* CHARWD property: tftopl invocation. (line 112) +* chtopx: Font utilities available elsewhere. + (line 23) +* class name for Metafont: Online Metafont graphics. + (line 69) +* cm.base: Initial Metafont. (line 26) +* cmbase.mf: Initial Metafont. (line 26) +* cmbase.mft: mft invocation. (line 73) +* cmmf.base not recommended: Initial Metafont. (line 26) +* color, in DVItoMP: dvitomp invocation. (line 15) +* comments, in TCX files: TCX files. (line 70) +* comments, MFT control: mft invocation. (line 24) +* common options: Common options. (line 6) +* commonalities: Commonalities. (line 6) +* compilation: Installation. (line 6) +* compile-time options: configure options. (line 6) +* compile-time options <1>: Compile-time options. + (line 6) +* Computer Modern fonts, and Troff: mpost invocation. (line 61) +* Computer Modern macros: Initial Metafont. (line 26) +* Computer Modern Typefaces, production of: mft invocation. (line 73) +* configuration: Installation. (line 6) +* configuration file reading: Path searching. (line 6) +* configuration file values: Runtime options. (line 6) +* configuration, compile-time: configure options. (line 6) +* configure --with/--enable options: configure options. (line 6) +* CONTENTS.tex: weave invocation. (line 22) +* ConTeXt: Formats. (line 28) +* conventions for options,: Option conventions. (line 6) +* conversion, DVI to plain text: dvitype invocation. (line 6) +* conversion, GF to PK: gftopk invocation. (line 6) +* conversion, GF to plain text: gftype invocation. (line 6) +* conversion, PK to GF: pktogf invocation. (line 6) +* conversion, PK to plain text: pktype invocation. (line 6) +* conversion, property list to TFM: pltotf invocation. (line 6) +* conversion, property list to VF: vptovf invocation. (line 6) +* conversion, TFM to property list: tftopl invocation. (line 6) +* conversion, VF to VPL: vftovp invocation. (line 6) +* copyright notices: Legalisms. (line 6) +* Cork encoding and ISO input: TCX files. (line 48) +* creating memory dumps: Creating memory dumps. + (line 6) +* cross-referenced bibliography items: bibtex invocation. (line 31) +* cross-references, omitting: weave invocation. (line 22) +* current directory, used for output: Output file location. + (line 6) +* Curtis, Pavel: Introduction. (line 43) +* Cweb: WEB. (line 12) +* CWEB: WEB. (line 12) +* date and time, in memory dumps: Hardware and memory dumps. + (line 30) +* debugging DVI utilities: dvitype invocation. (line 52) +* debugging flags, specifying: Common options. (line 64) +* decimal character codes, in TCX files: TCX files. (line 77) +* dependencies, hardware: Hardware and memory dumps. + (line 6) +* design-size units: tftopl invocation. (line 101) +* device definitions, for Metafont: Modes. (line 6) +* device-independent width: pktype invocation. (line 53) +* device-independent width <1>: gftype invocation. (line 112) +* directory structure: Installation. (line 33) +* DISPLAY: Online Metafont graphics. + (line 76) +* dot files, written by TeX programs: tex invocation. (line 48) +* double quote character, ignored in filenames: \input filenames. + (line 22) +* downloading of fonts for MetaPost labels: mpost invocation. (line 66) +* DrawingServant: Online Metafont graphics. + (line 35) +* dump file: Common options. (line 39) +* dumping memory: Memory dumps. (line 6) +* DVI comment, specifying: tex invocation. (line 113) +* DVI files, converting to MPX: dvitomp invocation. (line 6) +* DVI files, explained: Font file formats. (line 29) +* DVI format definition: DVI utilities. (line 14) +* DVI opcodes, showing: dvitype invocation. (line 52) +* DVI utilities: DVI utilities. (line 6) +* dvicopy: dvicopy invocation. (line 6) +* dvitomp: dvitomp invocation. (line 6) +* dvitype DVI validation: dvitype invocation. (line 6) +* dvitype output example: dvitype output example. + (line 6) +* dvitype.web: DVI utilities. (line 14) +* dx horizontal escapement: pktype invocation. (line 57) +* dx horizontal escapement <1>: gftype invocation. (line 106) +* dy vertical escapement: gftype invocation. (line 106) +* dynamic array allocation: Runtime options. (line 45) +* dynamic Metafont mode definitions with smode: Modes. (line 28) +* dynamic packing variable: pktype invocation. (line 44) +* e response at error prompt: Editor invocation. (line 6) +* e-circumflex: \charsubdef. (line 20) +* e-TeX: TeX extensions. (line 10) +* e.mft: mft invocation. (line 73) +* EC fonts: tex invocation. (line 41) +* EC fonts <1>: mf invocation. (line 24) +* editing of bitmap fonts: Font utilities available elsewhere. + (line 23) +* editor invoked at error: Editor invocation. (line 6) +* eight-bit characters in filenames: \input filename caveats. + (line 12) +* empty.tcx: TCX files. (line 48) +* endian dependencies: Hardware and memory dumps. + (line 6) +* eoc GF command: gftype invocation. (line 97) +* Eplain: Formats. (line 50) +* epsf: Online Metafont graphics. + (line 19) +* epTeX: TeX extensions. (line 51) +* errors, editor invoked at: Editor invocation. (line 6) +* escapement, horizontal: pktype invocation. (line 57) +* escapement, horizontal <1>: gftype invocation. (line 106) +* escapement, vertical: gftype invocation. (line 106) +* etex for MetaPost labels: mpost invocation. (line 44) +* etex is pdfTeX: TeX extensions. (line 22) +* eupTeX: TeX extensions. (line 51) +* executables, shared initial and virgin: Initial and virgin. (line 6) +* exit status, of shell escape: Shell escapes. (line 34) +* expanded plain format: Formats. (line 50) +* expand_depth: Runtime options. (line 24) +* expansion limit, recursive: Runtime options. (line 25) +* expansion, and \input filenames: \input filename caveats. + (line 6) +* extensions to TeX: TeX extensions. (line 6) +* extra_mem_bot: Runtime options. (line 19) +* FACE property: tftopl invocation. (line 95) +* FAMILY property: tftopl invocation. (line 95) +* FAMILY property <1>: tftopl invocation. (line 99) +* Ferguson, Michael: MLTeX. (line 6) +* file formats for fonts: Font file formats. (line 6) +* file recorder: Common options. (line 89) +* filename conventions, in input files: \input filenames. (line 6) +* filenames starting with -: Option conventions. (line 19) +* first line of the main input file: Common options. (line 103) +* fixed-point arithmetic: Compile-time options. + (line 21) +* FIXPT: Compile-time options. + (line 21) +* flag byte: pktype invocation. (line 44) +* floating-point arithmetic: Compile-time options. + (line 21) +* floating-point values: Hardware and memory dumps. + (line 22) +* fmt file, determining: Determining the memory dump to use. + (line 6) +* fmt files: Initial TeX. (line 6) +* fmt files, sharing: Hardware and memory dumps. + (line 6) +* fmts Make target: Additional targets. (line 24) +* font aliases: Path searching. (line 14) +* font character code, translating: TCX files. (line 101) +* font design: Metafont. (line 6) +* font downloading for MetaPost labels: mpost invocation. (line 66) +* font file formats: Font file formats. (line 6) +* font proofs: gftodvi invocation. (line 6) +* font utilities: Font utilities. (line 6) +* font utilities, non-Web2c: Font utilities available elsewhere. + (line 6) +* fontforge: Font utilities available elsewhere. + (line 30) +* fontinst, for creating virtual fonts: Font utilities available elsewhere. + (line 49) +* fonts, basic: Installation. (line 33) +* format files: Initial TeX. (line 13) +* formats for TeX: Formats. (line 6) +* formats Make target: Additional targets. (line 17) +* fraction routines: Compile-time options. + (line 21) +* Free Software Foundation documentation system: Formats. (line 43) +* freedom of Web2c: Introduction. (line 23) +* ftp.math.utah.edu: bibtex invocation. (line 58) +* generating source specials: tex invocation. (line 134) +* geometric designs: Metafont. (line 6) +* geometric font scaling: Font file formats. (line 21) +* geometry for Metafont: Online Metafont graphics. + (line 69) +* getopt_long_only: Option conventions. (line 6) +* GF files, explained: Font file formats. (line 39) +* GF files, output by Metafont: mf invocation. (line 34) +* GF format definition: Font utilities. (line 11) +* GF output: mf invocation. (line 34) +* GF, converting PK to: pktogf invocation. (line 6) +* GF, converting to PK: gftopk invocation. (line 6) +* gftodvi: gftodvi invocation. (line 6) +* gftopk: gftopk invocation. (line 6) +* gftopxl: Font utilities available elsewhere. + (line 23) +* gftype GF validation: gftype invocation. (line 6) +* gftype.web: Font utilities. (line 11) +* glue ratio representations: Hardware and memory dumps. + (line 22) +* glue, memory for: Runtime options. (line 20) +* glyph substitutions: MLTeX. (line 6) +* gray font: gftodvi invocation. (line 29) +* group-delimited filename for \input: \input braced filename. + (line 6) +* Gruff, Billy Goat: Triptrap. (line 6) +* gsftopk: Font utilities available elsewhere. + (line 35) +* Harbison, Samuel P.: Hardware and memory dumps. + (line 34) +* hardware and memory dumps: Hardware and memory dumps. + (line 6) +* headerbyte information: tftopl invocation. (line 95) +* height, in pixels: pktype invocation. (line 62) +* help, online: Common options. (line 11) +* Herberts, Mathias: Online Metafont graphics. + (line 20) +* hex character codes, in TCX files: TCX files. (line 77) +* history: Introduction. (line 43) +* Hobby, John: Introduction. (line 9) +* horizontal escapement: pktype invocation. (line 57) +* horizontal escapement <1>: gftype invocation. (line 106) +* hp2627: Online Metafont graphics. + (line 27) +* human languages, supported in TeX: Languages and hyphenation. + (line 6) +* human-readable text, converting DVI to: dvitype invocation. (line 6) +* human-readable text, converting GF to: gftype invocation. (line 6) +* human-readable text, converting PK to: pktype invocation. (line 6) +* human-readable text, converting TFM to: tftopl invocation. (line 6) +* human-readable text, converting VF to: vftovp invocation. (line 6) +* hypertext: TeX extensions. (line 22) +* hyphenation and languages: Languages and hyphenation. + (line 6) +* hyphenation patterns, creating: patgen invocation. (line 6) +* ice cream: Introduction. (line 23) +* identifier case: tangle invocation. (line 35) +* identifier collisions: tangle invocation. (line 46) +* identifier length: tangle invocation. (line 27) +* identifiers with underlines: tangle invocation. (line 41) +* ieeetr.bst: Basic BibTeX style files. + (line 31) +* il1-t1.tcx: TCX files. (line 48) +* il2-t1.tcx: TCX files. (line 48) +* Info format: Formats. (line 43) +* initial form, enabling: Common options. (line 50) +* initial Metafont: Initial Metafont. (line 6) +* initial MetaPost: Initial MetaPost. (line 6) +* initial programs: Initial and virgin. (line 19) +* initial TeX: Initial TeX. (line 6) +* initializations, lengthy: Initial and virgin. (line 19) +* input filenames: \input filenames. (line 6) +* install-bases Make target: Additional targets. (line 28) +* install-fmts Make target: Additional targets. (line 24) +* install-formats Make target: Additional targets. (line 17) +* install-mems Make target: Additional targets. (line 34) +* installation: Installation. (line 6) +* interaction between TCX files and -8bit.: TCX files. (line 104) +* interaction mode: Common options. (line 55) +* international characters: TCX files. (line 6) +* introduction: Introduction. (line 6) +* IPC: IPC and TeX. (line 6) +* IPC_DEBUG: Compile-time options. + (line 28) +* IPC_DEBUG <1>: IPC and TeX. (line 13) +* job name: Common options. (line 60) +* kerning table, in TFM files: tftopl invocation. (line 101) +* keyboard character code, translating: TCX files. (line 101) +* Knuth, Donald E.: Introduction. (line 9) +* Knuth, Donald E. <1>: mft invocation. (line 56) +* KPATHSEA_DEBUG: Common options. (line 64) +* KRN property: tftopl invocation. (line 101) +* label font: gftodvi invocation. (line 36) +* LABEL property: tftopl invocation. (line 101) +* language support in TeX: Languages and hyphenation. + (line 6) +* languages, hyphenation rules for: patgen invocation. (line 6) +* LaTeX: Formats. (line 18) +* Latin Modern: Font utilities available elsewhere. + (line 18) +* left side bearing: pktype invocation. (line 66) +* left side bearing <1>: gftype invocation. (line 82) +* legalisms: Legalisms. (line 6) +* libsigsegv library: Runtime options. (line 33) +* licensing terms: Introduction. (line 23) +* LIG property: tftopl invocation. (line 101) +* ligature table, in TFM files: tftopl invocation. (line 101) +* LIGTABLE property: tftopl invocation. (line 101) +* linking binaries: Common options. (line 82) +* links to binaries: Determining the memory dump to use. + (line 30) +* literate programming: WEB. (line 6) +* LittleEndian machines: Hardware and memory dumps. + (line 6) +* location of texmf.cnf in TeX Live: Runtime options. (line 56) +* log file, BibTeX: bibtex invocation. (line 14) +* Lua: TeX extensions. (line 30) +* LuaTeX: TeX extensions. (line 30) +* machine dependencies: Hardware and memory dumps. + (line 6) +* machine-readable, converting property lists to: pltotf invocation. + (line 6) +* machine-readable, converting property lists to <1>: vptovf invocation. + (line 6) +* MacKay, Pierre: Font file formats. (line 62) +* macro packages, major TeX: Formats. (line 6) +* macros, basic: Installation. (line 33) +* macros, predefining in memory dumps: Memory dumps. (line 6) +* magnification: dvicopy invocation. (line 20) +* magnification <1>: dvitype invocation. (line 28) +* main_memory: Runtime options. (line 15) +* Make targets, additional: Additional targets. (line 6) +* Martin, Rick: Introduction. (line 54) +* Mathematical Reviews: Formats. (line 35) +* mathematical typesetting: TeX. (line 6) +* mem file, determining: Determining the memory dump to use. + (line 6) +* mem files, sharing: Hardware and memory dumps. + (line 6) +* memory dump to use, determining: Determining the memory dump to use. + (line 6) +* memory dumps: Memory dumps. (line 6) +* memory dumps and hardware: Hardware and memory dumps. + (line 6) +* memory dumps, contain date and time: Hardware and memory dumps. + (line 30) +* memory dumps, creating: Creating memory dumps. + (line 6) +* mems Make target: Additional targets. (line 34) +* meta characters in filenames: \input filename caveats. + (line 12) +* Metafont: Metafont. (line 6) +* Metafont geometry: Online Metafont graphics. + (line 69) +* Metafont graphics: Online Metafont graphics. + (line 6) +* Metafont input files: mf invocation. (line 24) +* Metafont invocation: mf invocation. (line 6) +* Metafont meets PostScript: MetaPost. (line 6) +* Metafont online support, new devices: Online Metafont graphics. + (line 79) +* Metafont source, prettyprinting: mft invocation. (line 6) +* Metafont, compatibility in MetaPost: Initial MetaPost. (line 15) +* Metafont, initial: Initial Metafont. (line 6) +* Metafont, MetaPost, and TeX: Three programs. (line 6) +* MetaPost: MetaPost. (line 6) +* MetaPost and plain Metafont compatibility: Initial MetaPost. + (line 15) +* MetaPost input files: mpost invocation. (line 26) +* MetaPost invocation: mpost invocation. (line 6) +* MetaPost source, prettyprinting: mft invocation. (line 79) +* MetaPost, initial: Initial MetaPost. (line 6) +* MetaPost, TeX, and Metafont: Three programs. (line 6) +* metatype1: Font utilities available elsewhere. + (line 18) +* mf: mf invocation. (line 6) +* mf.base: Initial Metafont. (line 14) +* MFEDIT: Editor invocation. (line 10) +* mfplain: Initial MetaPost. (line 15) +* mfput: mf invocation. (line 34) +* mft: mft invocation. (line 6) +* mftalk: Online Metafont graphics. + (line 30) +* MFTERM: Online Metafont graphics. + (line 11) +* mftmac.tex: mft invocation. (line 6) +* micro-typography: TeX extensions. (line 22) +* mktexmf, disabling: mf invocation. (line 24) +* mktextfM, disabling: tex invocation. (line 41) +* mltex: MLTeX. (line 6) +* MLTeX, enabling: tex invocation. (line 108) +* mode needed to run Metafont: mf invocation. (line 48) +* modes file needed for Metafont: Modes. (line 6) +* modes.mf recommended modes file: Modes. (line 10) +* mode_def: Modes. (line 15) +* mode_setup: Modes. (line 15) +* modifying texmf.cnf in TeX Live: Runtime options. (line 56) +* Morgan, Tim: Introduction. (line 43) +* Morris, Bob: Introduction. (line 54) +* MPEDIT: Editor invocation. (line 10) +* mpgraph.pdf: mpost invocation. (line 14) +* mpman.pdf: mpost invocation. (line 6) +* mpost: mpost invocation. (line 6) +* mpost, reason for name change: Installation. (line 19) +* mpout: mpost invocation. (line 31) +* mproof.tex: mpost invocation. (line 66) +* mptrap Make target: Additional targets. (line 41) +* mptrap test: Triptrap. (line 6) +* mptrap.readme: Triptrap. (line 6) +* MPX files, converting from DVI files: dvitomp invocation. (line 6) +* Multi-lingual TeX: MLTeX. (line 6) +* multiple spaces, and \input filenames: \input filename caveats. + (line 6) +* N tilde: \charsubdef. (line 36) +* new graphics support for Metafont: Online Metafont graphics. + (line 79) +* newrow GF command: gftype invocation. (line 93) +* next: Online Metafont graphics. + (line 34) +* non-Unix system, compiling on: Additional targets. (line 12) +* non-windows-capable Metafont: Online Metafont graphics. + (line 65) +* NO_X11WIN: Online Metafont graphics. + (line 56) +* NUL, not allowed in filenames: \input filename caveats. + (line 12) +* octal character codes, in TCX files: TCX files. (line 77) +* offset for overflow labels: gftodvi invocation. (line 59) +* Omega: TeX extensions. (line 15) +* online Metafont graphics: Online Metafont graphics. + (line 6) +* opcodes, showing DVI: dvitype invocation. (line 52) +* OpenType support: TeX extensions. (line 30) +* optical font scaling: Font file formats. (line 21) +* option conventions: Option conventions. (line 6) +* origin: pktype invocation. (line 66) +* output directory, specifying: Common options. (line 71) +* output directory, specifying <1>: Output file location. + (line 15) +* output file location: Output file location. + (line 6) +* output files, written by TeX programs: tex invocation. (line 48) +* output_comment for DVI files: tex invocation. (line 113) +* overflow label offset: gftodvi invocation. (line 59) +* overflow, of runtime stack: Runtime options. (line 25) +* packet length: pktype invocation. (line 50) +* page, starting: dvicopy invocation. (line 28) +* page, starting <1>: dvitype invocation. (line 46) +* parsing the first line: Common options. (line 77) +* Pascal, creating from WEB: tangle invocation. (line 6) +* patgen: patgen invocation. (line 6) +* path searching: Path searching. (line 6) +* path searching debugging: Common options. (line 64) +* PDF: TeX extensions. (line 22) +* PDF, and .mps files: mpost invocation. (line 82) +* pdfTeX: TeX extensions. (line 22) +* permissions, legal: Legalisms. (line 6) +* PFA and PFB conversion: Font utilities available elsewhere. + (line 39) +* pfaedit: Font utilities available elsewhere. + (line 30) +* PiCTeX, increasing memory for: Runtime options. (line 20) +* pipes, reading and writing: Shell escapes. (line 64) +* pixel height: pktype invocation. (line 62) +* pixel width: pktype invocation. (line 62) +* PK bitmaps from PostScript: Font utilities available elsewhere. + (line 35) +* PK files, explained: Font file formats. (line 39) +* PK files, not output by Metafont: mf invocation. (line 34) +* PK format definition: Font utilities. (line 11) +* PK, converting GF to: gftopk invocation. (line 6) +* PK, converting to GF: pktogf invocation. (line 6) +* pktogf: pktogf invocation. (line 6) +* pktype PK validation: pktype invocation. (line 6) +* pktype.web: Font utilities. (line 11) +* PL files, explained: Font file formats. (line 46) +* plain Metafont, compatibility in MetaPost: Initial MetaPost. + (line 15) +* plain text, converting DVI to: dvitype invocation. (line 6) +* plain text, converting GF to: gftype invocation. (line 6) +* plain text, converting PK to: pktype invocation. (line 6) +* plain text, converting TFM to: tftopl invocation. (line 6) +* plain text, converting VF to: vftovp invocation. (line 6) +* plain.base: Initial Metafont. (line 14) +* plain.bst: Basic BibTeX style files. + (line 11) +* plain.fmt: Initial TeX. (line 13) +* plain.mft: mft invocation. (line 67) +* pltotf: pltotf invocation. (line 6) +* pool file, writing: tangle invocation. (line 16) +* Poole, Simon: Online Metafont graphics. + (line 50) +* pooltype: pooltype invocation. (line 6) +* portable filenames: \input filenames. (line 25) +* PostScript fonts, and Troff: mpost invocation. (line 61) +* PostScript meets Metafont: MetaPost. (line 6) +* PostScript output: mpost invocation. (line 31) +* PostScript to PK bitmaps: Font utilities available elsewhere. + (line 35) +* PostScript Type 1 font conversion: Font utilities available elsewhere. + (line 39) +* PostScript, and font scaling: Font file formats. (line 21) +* potrace: Font utilities available elsewhere. + (line 42) +* predefined macros and memory dumps: Memory dumps. (line 6) +* prettyprinting Metafont source: mft invocation. (line 6) +* prettyprinting WEB programs: weave invocation. (line 6) +* primitives, new: TeX extensions. (line 10) +* printable characters, specifying: TCX files. (line 87) +* printer characteristics, for Metafont: Modes. (line 6) +* production use: Initial and virgin. (line 15) +* program name, determines memory dump: Determining the memory dump to use. + (line 30) +* program names, special: Common options. (line 50) +* program names, special <1>: Common options. (line 82) +* program names, special <2>: tex invocation. (line 108) +* prologues: mpost invocation. (line 111) +* prologues, and EPSF output: mpost invocation. (line 76) +* proof mode: mf invocation. (line 48) +* proof sheets, of fonts: gftodvi invocation. (line 6) +* property list format: tftopl invocation. (line 43) +* property list, converting TFM to: tftopl invocation. (line 6) +* property list, converting VF to virtual: vftovp invocation. (line 6) +* ps2pk: Font utilities available elsewhere. + (line 35) +* psfonts.map, read by MetaPost: mpost invocation. (line 76) +* pTeX: TeX extensions. (line 44) +* PXL files, explained: Font file formats. (line 39) +* pxtoch: Font utilities available elsewhere. + (line 23) +* quoted filename for \input: \input quoted filename. + (line 6) +* Raichle, Bernd: MLTeX. (line 6) +* reading, additional: Introduction. (line 62) +* readonly directory, running TeX in: Output file location. + (line 15) +* readonly directory, running TeX in <1>: Output file location. + (line 19) +* reallocation of arrays: Runtime options. (line 45) +* recursive expansion limit: Runtime options. (line 25) +* redefined character substitutions: \tracingcharsubdef. (line 6) +* reference pixel: pktype invocation. (line 66) +* references: References. (line 6) +* regis: Online Metafont graphics. + (line 39) +* Regis graphics support: Online Metafont graphics. + (line 40) +* regression testing: tex invocation. (line 113) +* repeated rows: pktype invocation. (line 76) +* representation of strings: pooltype invocation. (line 30) +* restricted shell escapes: Shell escapes. (line 6) +* right side bearing: pktype invocation. (line 66) +* right side bearing <1>: gftype invocation. (line 82) +* Rokicki, Tomas: Introduction. (line 43) +* run length encoded bitmaps: pktype invocation. (line 76) +* run length encoded bitmaps <1>: gftype invocation. (line 89) +* runtime options: Runtime options. (line 6) +* runtime stack overflow: Runtime options. (line 25) +* scaled pixels: pktype invocation. (line 57) +* scaled pixels <1>: gftype invocation. (line 106) +* scaling of fonts: Font file formats. (line 21) +* security, and output files: tex invocation. (line 48) +* security, and shell escapes: Shell escapes. (line 6) +* security, and write: mpost invocation. (line 88) +* security, and \openout: tex invocation. (line 48) +* segmentation fault: Runtime options. (line 25) +* shapes: Metafont. (line 6) +* sharing memory dumps: Hardware and memory dumps. + (line 6) +* shell commands in TeX: Shell escapes. (line 6) +* shell_escape enabling in TeX: Shell escapes. (line 6) +* shell_escape_commands: Shell escapes. (line 52) +* siam.bst: Basic BibTeX style files. + (line 35) +* side bearings: pktype invocation. (line 66) +* side bearings <1>: gftype invocation. (line 82) +* SIGSEGV: Runtime options. (line 25) +* slant font: gftodvi invocation. (line 39) +* slides, producing: Formats. (line 57) +* SliTeX: Formats. (line 57) +* small Metafont memory and modes: Modes. (line 15) +* smode and dynamic Metafont mode definition: Modes. (line 28) +* sockets: IPC and TeX. (line 6) +* space-terminated filenames: \input filenames. (line 10) +* Spiderweb: WEB. (line 12) +* Stallman, Richard: Introduction. (line 54) +* starting page: dvicopy invocation. (line 28) +* starting page <1>: dvitype invocation. (line 46) +* Steele Jr., Guy L.: Hardware and memory dumps. + (line 34) +* stopping at the first error: Common options. (line 46) +* strategy, overall: Introduction. (line 17) +* string numbers, displaying: pooltype invocation. (line 6) +* string pool, writing: tangle invocation. (line 16) +* string representation: pooltype invocation. (line 30) +* style design, for BibTeX: bibtex invocation. (line 49) +* style files: mft invocation. (line 67) +* substitutions of font glyphs: MLTeX. (line 6) +* sun: Online Metafont graphics. + (line 42) +* sun-gfx.c: Online Metafont graphics. + (line 43) +* Suntools: Online Metafont graphics. + (line 43) +* SunView: Online Metafont graphics. + (line 43) +* swap space, as array limit: Runtime options. (line 45) +* swapping bytes: Hardware and memory dumps. + (line 13) +* syntax of TCX files: TCX files. (line 65) +* system C library function: Shell escapes. (line 6) +* system command: Shell escapes. (line 6) +* system fonts, using: TeX extensions. (line 30) +* T1 encoding and ISO input: TCX files. (line 48) +* tabs, and \input filenames: \input filename caveats. + (line 6) +* Tachikawa, Elizabeth: Font file formats. (line 62) +* tangle: tangle invocation. (line 6) +* targets, additional Make: Additional targets. (line 6) +* TCX character translation files: TCX files. (line 6) +* technical illustrations, creating: MetaPost. (line 6) +* tek: Online Metafont graphics. + (line 47) +* Tektronix: Online Metafont graphics. + (line 48) +* Tektronix 4014: Online Metafont graphics. + (line 51) +* TERM: Online Metafont graphics. + (line 11) +* terminator for filenames: \input filenames. (line 10) +* terse output: bibtex invocation. (line 28) +* tex: tex invocation. (line 6) +* TeX, bibliographies for: bibtex invocation. (line 58) +* TeX, creating from Metafont: mft invocation. (line 6) +* TeX, creating from WEB: weave invocation. (line 6) +* TeX, description of: TeX. (line 6) +* TeX, extensions to: TeX extensions. (line 6) +* TeX, format packages for: Formats. (line 6) +* TeX, initial: Initial TeX. (line 6) +* TeX, input files found: tex invocation. (line 20) +* TeX, invocation: tex invocation. (line 6) +* TeX, Metafont, and MetaPost: Three programs. (line 6) +* TeX, Web2c implementation of: Introduction. (line 9) +* tex.fmt: Initial TeX. (line 13) +* TEXBIB, search path for bib files: bibtex invocation. (line 18) +* TEXEDIT: Editor invocation. (line 10) +* texfonts.map: Path searching. (line 14) +* Texinfo: Formats. (line 43) +* texmf.cnf: Path searching. (line 6) +* texmf.cnf <1>: Runtime options. (line 6) +* texmf.cnf for editors: Editor invocation. (line 10) +* texmf.cnf for shell escapes: Shell escapes. (line 6) +* texmfmp.c: Online Metafont graphics. + (line 79) +* TEXMFOUTPUT, used for reading: Output file location. + (line 25) +* TEXMFOUTPUT, used if . unwritable: Output file location. + (line 19) +* texmf_casefold_search: Runtime options. (line 42) +* texput: tex invocation. (line 33) +* TFM files, converting property lists to: pltotf invocation. (line 6) +* TFM files, explained: Font file formats. (line 12) +* TFM files, output by Metafont: mf invocation. (line 43) +* TFM files, output by MetaPost: mpost invocation. (line 31) +* TFM width of characters: pktype invocation. (line 53) +* TFM width of characters <1>: gftype invocation. (line 112) +* tftopl: tftopl invocation. (line 6) +* three programs: Three programs. (line 6) +* time and date, in memory dumps: Hardware and memory dumps. + (line 30) +* title font: gftodvi invocation. (line 33) +* tokenization, and \input filenames: \input filename caveats. + (line 6) +* toolkits, X: Online Metafont graphics. + (line 59) +* torture tests: Triptrap. (line 6) +* translation file for TeX, specifying: Common options. (line 103) +* translation from WEB to C: Introduction. (line 17) +* trap Make target: Additional targets. (line 41) +* trap test: Triptrap. (line 6) +* trapman.tex: Triptrap. (line 6) +* Trickey, Howard: Introduction. (line 43) +* trip Make target: Additional targets. (line 41) +* trip test: Triptrap. (line 6) +* tripman.tex: Triptrap. (line 6) +* triptrap Make target: Additional targets. (line 41) +* Troff, and MetaPost: mpost invocation. (line 61) +* troff, supported in MetaPost: MetaPost. (line 12) +* Troff, WEB for: WEB. (line 12) +* Trojan horses and TeX programs: tex invocation. (line 48) +* TrueType support: TeX extensions. (line 30) +* TUGboat bibliography: bibtex invocation. (line 58) +* Type 1 conversion: Font utilities available elsewhere. + (line 39) +* type design, personal: Initial Metafont. (line 31) +* type programs, DVI: dvitype invocation. (line 6) +* type programs, GF: gftype invocation. (line 6) +* type programs, PK: pktype invocation. (line 6) +* type programs, pool: pooltype invocation. (line 6) +* typeface families: Metafont. (line 6) +* typesetting: TeX. (line 6) +* Unicode: TeX extensions. (line 15) +* Unicode input: tex invocation. (line 86) +* Unicode input, native: TeX extensions. (line 37) +* uniterm: Online Metafont graphics. + (line 50) +* unsrt.bst: Basic BibTeX style files. + (line 39) +* upTeX: TeX extensions. (line 44) +* UTF-8 input: tex invocation. (line 86) +* UTF-8 input, native: TeX extensions. (line 30) +* validation, of DVI files: dvitype invocation. (line 6) +* validation, of GF files: gftype invocation. (line 6) +* validation, of PK files: pktype invocation. (line 6) +* validation, of TFM files: tftopl invocation. (line 6) +* validation, of VF files: vftovp invocation. (line 6) +* verbose BibTeX output, suppressing: bibtex invocation. (line 28) +* verbosity, enabling: Common options. (line 15) +* version number, finding: Common options. (line 18) +* vertical escapement: gftype invocation. (line 106) +* VF files, converting property lists to: vptovf invocation. (line 6) +* vftovp: vftovp invocation. (line 6) +* virgin programs: Initial and virgin. (line 15) +* virtual font creation: Font utilities available elsewhere. + (line 49) +* virtual fonts, expanding: dvicopy invocation. (line 6) +* virtual-fonts.knuth: Font file formats. (line 56) +* virtualfonts.txt: Font file formats. (line 56) +* vptovf: vptovf invocation. (line 6) +* weave: weave invocation. (line 6) +* WEB: WEB. (line 6) +* web environments, and security: Shell escapes. (line 71) +* WEB pool files, displaying: pooltype invocation. (line 6) +* WEB programs, compiling: tangle invocation. (line 6) +* WEB programs, typesetting: weave invocation. (line 6) +* WEB2C, search path for TCX files: TCX files. (line 35) +* Weber, Olaf: Introduction. (line 43) +* webmac.tex: weave invocation. (line 22) +* webman.tex: WEB. (line 12) +* whitespace, in TCX files: TCX files. (line 68) +* whitespace-terminated filenames: \input filenames. (line 10) +* width, device-independent: pktype invocation. (line 53) +* width, device-independent <1>: gftype invocation. (line 112) +* width, in pixels: pktype invocation. (line 62) +* word processor, not: TeX. (line 9) +* writing memory dumps: Creating memory dumps. + (line 6) +* X bitmap fonts: Font utilities available elsewhere. + (line 15) +* X class name for Metafont: Online Metafont graphics. + (line 69) +* x offset: pktype invocation. (line 66) +* X resources: Online Metafont graphics. + (line 69) +* X toolkits and Metafont: Online Metafont graphics. + (line 59) +* xampl.bib: bibtex invocation. (line 55) +* xbfe, bitmap font editor: Font utilities available elsewhere. + (line 23) +* XeTeX: TeX extensions. (line 37) +* xfed, bitmap font editor: Font utilities available elsewhere. + (line 23) +* xfedor, bitmap font editor: Font utilities available elsewhere. + (line 23) +* Xlib: Online Metafont graphics. + (line 56) +* Xlib support: Online Metafont graphics. + (line 59) +* Xt: Online Metafont graphics. + (line 56) +* Xt support: Online Metafont graphics. + (line 59) +* xterm: Online Metafont graphics. + (line 56) +* y offset: pktype invocation. (line 66) + + + +Tag Table: +Node: Top2759 +Node: Introduction3834 +Node: Installation7174 +Node: configure options9218 +Node: Compile-time options11240 +Node: Additional targets12342 +Node: Triptrap13619 +Node: Commonalities15122 +Node: Option conventions15655 +Node: Common options16878 +Node: Path searching21496 +Node: Output file location22468 +Node: Three programs23770 +Node: Runtime options24477 +Node: Initial and virgin27618 +Node: Memory dumps28567 +Node: Creating memory dumps29019 +Node: Determining the memory dump to use30226 +Node: Hardware and memory dumps31803 +Node: Editor invocation34249 +Node: \input filenames35112 +Node: \input quoted filename36665 +Node: \input braced filename37442 +Node: \input filename caveats38372 +Node: TeX39886 +Node: tex invocation41054 +Node: Initial TeX48039 +Node: Formats49403 +Node: Languages and hyphenation52220 +Node: MLTeX52650 +Node: \charsubdef54278 +Node: \tracingcharsubdef56601 +Node: TCX files57176 +Node: patgen invocation62616 +Node: Shell escapes63322 +Node: IPC and TeX66902 +Node: TeX extensions67472 +Node: Metafont69501 +Node: mf invocation70789 +Node: Initial Metafont74626 +Node: Modes76256 +Node: Online Metafont graphics78506 +Node: gftodvi invocation81931 +Node: mft invocation84751 +Node: MetaPost88749 +Node: mpost invocation89585 +Node: Initial MetaPost94619 +Node: dvitomp invocation95541 +Node: BibTeX96206 +Node: bibtex invocation96567 +Node: Basic BibTeX style files99041 +Node: WEB100371 +Node: tangle invocation101580 +Node: weave invocation103703 +Node: pooltype invocation105110 +Node: DVI utilities106240 +Node: dvicopy invocation107174 +Node: dvitype invocation108459 +Node: dvitype output example110790 +Node: Font utilities113843 +Node: Font file formats115023 +Node: gftopk invocation118292 +Node: pktogf invocation119483 +Node: pktype invocation120649 +Node: gftype invocation123472 +Node: tftopl invocation127975 +Node: pltotf invocation132568 +Node: vftovp invocation133619 +Node: vptovf invocation135854 +Node: Font utilities available elsewhere136881 +Node: Legalisms139086 +Node: References140532 +Node: Index144665 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/Build/source/texk/web2c/doc/web2c.texi b/Build/source/texk/web2c/doc/web2c.texi new file mode 100644 index 00000000000..f96ed0d6a0a --- /dev/null +++ b/Build/source/texk/web2c/doc/web2c.texi @@ -0,0 +1,4353 @@ +\input texinfo +@setfilename web2c.info +@settitle Web2c: A @TeX{} implementation + +@tex +\expandafter\ifx\csname url\endcsname\relax + \errhelp{You must update texinfo.tex to at least version 3.8. +The latest version is available from ftp://ftp.tug.org/tex/texinfo.tex.} + \errmessage{Your texinfo.tex is too old} + \csname bye\expandafter\endcsname +\fi +@end tex + +@set version 2021 +@set month-year February 2021 + +@c Define new indices for commands in auxiliary files, 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 vr cp + +@dircategory TeX +@direntry +* Web2c: (web2c). TeX, Metafont, and companion programs. +@end direntry +@dircategory Individual utilities +@direntry +* bibtex: (web2c)bibtex invocation. Maintaining bibliographies. +* dvicopy: (web2c)dvicopy invocation. Virtual font expansion +* dvitomp: (web2c)dvitomp invocation. DVI to MPX (MetaPost pictures). +* dvitype: (web2c)dvitype invocation. DVI to human-readable text. +* gftodvi: (web2c)gftodvi invocation. Generic font proofsheets. +* gftopk: (web2c)gftopk invocation. Generic to packed fonts. +* gftype: (web2c)gftype invocation. GF to human-readable text. +* mf: (web2c)mf invocation. Creating typeface families. +* mft: (web2c)mft invocation. Prettyprinting Metafont source. +* mltex: (web2c)MLTeX. Multi-lingual TeX. +* mpost: (web2c)mpost invocation. Generating PostScript. +* patgen: (web2c)patgen invocation. Creating hyphenation patterns. +* pktogf: (web2c)pktogf invocation. Packed to generic fonts. +* pktype: (web2c)pktype invocation. PK to human-readable text. +* pltotf: (web2c)pltotf invocation. Property list to TFM. +* pooltype: (web2c)pooltype invocation. Display WEB pool files. +* tangle: (web2c)tangle invocation. WEB to Pascal. +* tex: (web2c)tex invocation. Typesetting. +* tftopl: (web2c)tftopl invocation. TFM -> property list. +* vftovp: (web2c)vftovp invocation. Virtual font -> virtual pl. +* vptovf: (web2c)vptovf invocation. Virtual pl -> virtual font. +* weave: (web2c)weave invocation. WEB to TeX. +@end direntry + +@copying +This file documents the installation and use of the programs in Web2c, +an implementation of Donald Knuth's TeX system. + +Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, +2004, 2005, 2007, 2008, 2009, 2010-2021 Karl Berry & Olaf Weber. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +@end copying + + +@titlepage +@title Web2c +@subtitle for version @value{version} +@subtitle @value{month-year} +@author Karl Berry +@author Olaf Weber +@author @url{https://tug.org/web2c} + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Web2c + +This document describes how to install and use the programs in the Web2c +implementation of the @TeX{} system, especially for Unix systems. It +corresponds to Web2c version @value{version}, released in +@value{month-year}. + +@menu +* Introduction:: A brief introduction. +* Installation:: How to compile and install Web2c. +* Commonalities:: Option syntax, standard options, memory dumps. +* Three programs:: TeX, Metafont, MetaPost have much in common. +* TeX:: Typesetting. +* Metafont:: Typeface design. +* MetaPost:: Technical illustrations. +* BibTeX:: Reusable bibliographies. +* WEB:: Literate programming. +* DVI utilities:: DVI expansion. +* Font utilities:: Font format conversion. +* Legalisms:: Blah blah blah. +* References:: Books and such. +* Index:: General index. +@end menu +@end ifnottex + + +@node Introduction +@chapter Introduction + +@cindex introduction + +This manual corresponds to version @value{version} of Web2c, released in +@value{month-year}. + +@cindex Knuth, Donald E. +@cindex @TeX{}, Web2c implementation of +@cindex Hobby, John +@cindex Breitenlohner, Peter +@dfn{Web2c} is the name of a @TeX{} implementation, originally for +Unix, but now also running under various operating systems. By +@dfn{@TeX{} implementation}, we mean all of the standard programs +developed by the Stanford @TeX{} project directed by Donald E. Knuth: +Metafont, DVItype, GFtoDVI, Bib@TeX{}, Tangle, etc., as well as @TeX{} +itself. Other programs are also included: DVIcopy, written by Peter +Breitenlohner, MetaPost and its utilities (derived from Metafont), by +John Hobby, etc. + +@cindex translation from WEB to C +@cindex strategy, overall +General strategy: Web2c works, as its name implies, by translating the +WEB source in which @TeX{} is written into C source code. Its output is +not self-contained, however; it makes extensive use of many macros and +functions in a library (the @file{web2c/lib} directory in the sources). +Therefore, it will not work without change on an arbitrary WEB program. + +@cindex licensing terms +@cindex freedom of Web2c +@cindex ice cream +Availability: All of Web2c is freely available---``free'' both in the +sense of no cost (free ice cream) and of having the source code to +modify and/or redistribute (free speech). @xref{unixtex.ftp,,, +kpathsea, Kpathsea}, for the practical details of how to obtain Web2c. + +Different parts of the Web2c distribution have different licensing +terms, however, reflecting the different circumstances of their +creation; consult each source file for exact details. The main +practical implication for redistributors of Web2c is that most of the +executables are covered by the GNU General Public License or GNU +Lesser General Public License, and therefore anyone who gets a binary +distribution must also be able to get the sources, as explained by the +terms of the GPL (@url{https://gnu.org/licenses/}. The GPL covers the +Web2c executables, including @code{tex}, because the Free Software +Foundation sponsored the initial development of the Kpathsea library +that Web2c uses. The basic source files from Stanford, however, have +their own copyright terms or are in the public domain, and are not +covered by the GPL. + +@cindex history +@cindex Rokicki, Tomas +@cindex Trickey, Howard +@cindex Curtis, Pavel +@cindex Morgan, Tim +@cindex Berry, Karl +@cindex Weber, Olaf +History: Tomas Rokicki originated the @TeX{}-to-C system in 1987, +working from the first change files for @TeX{} under Unix, which were +done primarily by Howard Trickey and Pavel Curtis. Tim Morgan then +took over development and maintenance for a number of years; the name +changed to Web-to-C somewhere in there. In 1990, Karl Berry became +the maintainer. He made many changes to the original sources, and +started using the shorter name Web2c. In 1997, Olaf Weber took over, +and then in 2006, Karl started taking care of it again. No +significant development or changes have been needed for many +years. Dozens of other people have contributed; their names are listed +in the @file{ChangeLog} files. + +@cindex acknowledgements +@cindex Martin, Rick +@cindex Morris, Bob +@cindex Stallman, Richard +Other acknowledgements by Karl: The University of Massachusetts at Boston +(particularly Rick Martin and Bob Morris) provided computers and ftp +access to me for many years. Richard Stallman at the Free Software +Foundation employed me while I wrote the original path searching library +(for the GNU font utilities). (rms also gave us Emacs, GDB, and GCC, +without which I cannot imagine developing Web2c.) And, of course, +@TeX{} would not exist in the first place without Donald E. Knuth. + +@cindex reading, additional +Further reading: @xref{References}. + + +@include install.texi + + +@node Commonalities +@chapter Commonalities + +@cindex commonalities + +Many aspects of the @TeX{} system are the same among more than one +program, so we describe those pieces together, here. + +@menu +* Option conventions:: -- or -, = or ` ' for values. +* Common options:: --help --version --verbose, and TeX/MF/MP options. +* Path searching:: Features of the common path searching library. +* Output file location:: TEXMFOUTPUT allows output in places other than `.'. +@end menu + + +@node Option conventions +@section Option conventions + +@cindex option conventions +@cindex conventions for options, + +@findex getopt_long_only +To provide a clean and consistent behavior, we chose to have all these +programs use the GNU function @code{getopt_long_only} to parse command +lines. However, we do use in a restricted mode, where all the options +have to come before the rest of the arguments. + +@opindex - @r{starts option names} +@opindex -- @r{starts option names} +As a result, you can: +@itemize @bullet +@item +use @samp{-} or @samp{--} to start an option name; + +@item +use any unambiguous abbreviation for an option name; + +@item +separate option names and values with either @samp{=} or one or more +spaces; + +@item +@flindex - @r{starting a filename} +@cindex filenames starting with @samp{-} +use filenames that would otherwise look like options by putting them +after an option @samp{--}. +@end itemize + +By convention, non-option arguments, if specified, generally define the +name of an input file, as documented for each program. + +If a particular option with a value is given more than once, it is the +last value that counts. + +For example, the following command line specifies the options +@samp{foo}, @samp{bar}, and @samp{verbose}; gives the value @samp{baz} +to the @samp{abc} option, and the value @samp{xyz} to the @samp{quux} +option; and specifies the filename @file{-myfile-}. + +@example +-foo --bar -verb -abc=baz -quux karl --quux xyz -- -myfile- +@end example + + +@node Common options +@section Common options + +@cindex common options +All of these programs accept the standard GNU @samp{--help} and +@samp{--version} options, and several programs accept +@samp{--verbose}. Rather than writing identical descriptions for +every program, they are described here. + +@table @samp +@item --help +@opindex --help @r{common option} +@cindex help, online +Print a usage message listing basic usage and all available options to +standard output, then exit successfully. + +@item --verbose +@opindex --verbose @r{common option} +@cindex verbosity, enabling +Print progress reports to standard output. + +@item --version +@opindex --version @r{common option} +@cindex version number, finding +Print the version number to standard output, then exit successfully. +@end table + +@TeX{}, Metafont, and MetaPost have a number of additional options in +common: + +@table @samp +@item -cnf-line=@var{str} +@opindex -cnf-line +Parse @var{str} as if it were a line in the @file{texmf.cnf} +configuration file, overriding all other settings. @xref{Path +searching options,,,kpathsea,Kpathsea}. + +@item -file-line-error +@opindex -file-line-error +@itemx -no-file-line-error +@opindex -no-file-line-error +@opindex -file-line-error-style +@cindex changing error messages style +Change (or do not change) the way error messages are printed. The +alternate style looks like error messages from many compilers and is +easier to parse for some editors that invoke @TeX{}. This option used +to be called @samp{-file-line-error-style}. + +@item -fmt=@var{dumpname} +@itemx -base=@var{dumpname} +@itemx -mem=@var{dumpname} +@opindex -fmt=@var{dumpname} +@opindex -base=@var{dumpname} +@opindex -mem=@var{dumpname} +@cindex dump file +Use @var{dumpname} instead of the program name or a @samp{%&} line to +determine the name of the memory dump file read (@samp{fmt} for @TeX{}, +@samp{base} for Metafont, @samp{mem} for MetaPost). @xref{Memory +dumps}. Also sets the program name to @var{dumpname} if no +@samp{-progname} option was given. + +@item -halt-on-error +@opindex -halt-on-error +@cindex stopping at the first error +Stop processing and exit when an error occurs, as opposed to the normal +process of trying to recover and continue. + +@item -ini +@opindex -ini +@cindex program names, special +@cindex initial form, enabling +Enable the ``initial'' form of the program (@pxref{Initial and +virgin}). This is implicitly set if the program name is @code{initex} +resp.@: @code{inimf}. + +@item -interaction=@var{string} +@opindex -interaction=@var{string} +@cindex interaction mode +Set the interaction mode from the command line. The @var{string} must +be one of @samp{batchmode}, @samp{nonstopmode}, @samp{scrollmode}, or +@samp{errorstopmode}. + +@item -jobname=@var{string} +@opindex -jobname=@var{string} +@cindex job name +Set the job name to @var{string}, instead of deriving it from the name +of the input file. + +@item -kpathsea-debug=@var{number} +@opindex -kpathsea-debug=@var{number} +@vindex KPATHSEA_DEBUG +@cindex debugging flags, specifying +@cindex path searching debugging +Set path searching debugging flags according to the bits of @var{number} +(@pxref{Debugging,,,kpathsea,Kpathsea}). You can also specify this in +@code{KPATHSEA_DEBUG} environment variable (for all Web2c programs). +(The command line value overrides.) The most useful value is @samp{-1}, +to get all available output. + +@item -output-directory=@var{dirname} +@opindex -output-directory +@cindex output directory, specifying +Specify the directory @var{dirname} to which output files are written. +Also look for input files in @var{dirname} first, before looking along +the normal search path. @xref{Output file location}. + +@item -parse-first-line +@opindex -parse-first-line +@itemx -no-parse-first-line +@opindex -no-parse-first-line +@cindex parsing the first line +Check or disable checking whether the first line of the main input +file starts with @samp{%&}, and parse it if it does. This line can be +used specify the format and/or a TCX file. + +@item -progname=@var{string} +@opindex -progname=@var{string} +@cindex binaries, linking +@cindex linking binaries +@cindex program names, special +Set program (and memory dump) name to @var{string}. This may affect the +search paths and other values used (@pxref{Config files,,, kpathsea, +Kpathsea}). Using this option is equivalent to making a link named +@var{string} to the binary and then invoking the binary under that +name. @xref{Memory dumps}. + +@item -recorder +@opindex -recorder +@cindex file recorder +Enable the filename recorder. This makes the program save a list of the +opened files into a file with (by default) extension @samp{.fls}. For +Aleph, this option is always on, and the file has extension @samp{.ofl}. + +Ordinarily, the @samp{.fls} file is written to the same location as +the @samp{.log} file, for example, respecting +@option{-output-directory} if it is given (@pxref{Output file +location}). However, if @TeX{} processing is done on the command line +(or in response to the @samp{**} prompt), the @samp{.fls} might be +written to the current directory, or include an integer (the current +pid), as in @file{texput1234.fls}. You can use @option{-jobname} to +explicitly set the basename. + +@item -translate-file=@var{tcxfile} +@opindex -translate-file=@var{tcxfile} +@cindex translation file for @TeX{}, specifying +@flindex .tcx @r{character translation files} +@cindex first line of the main input file +Use @var{tcxfile} to define which characters are printable and translations +between the internal and external character sets. Moreover, +@var{tcxfile} can be explicitly declared in the first line of the main +input file @samp{%& -translate-file=@var{tcxfile}}. +This is the recommended method for portability reasons. +@xref{TCX files}. + +@item -8bit +@opindex -8bit +@cindex 8 bit clean +@flindex 8 bit clean output, specifying +This option specifies that by default all characters should be +considered printable. If @samp{-translate-file} was given as well, +then the TCX file may mark characters as non-printable. This is a +no-op in engines natively supporting Unicode. + +@end table + + +@node Path searching +@section Path searching + +@cindex path searching + +@flindex texmf.cnf +@cindex configuration file reading +All of the Web2c programs, including @TeX{}, which do path searching use +the Kpathsea routines to do so. The precise names of the environment +and configuration file variables which get searched for particular file +formatted are therefore documented in the Kpathsea manual +(@pxref{Supported file formats,,, kpathsea, Kpathsea}). Reading +@file{texmf.cnf} (@pxref{Config files,,, kpathsea, Kpathsea}), invoking +@code{mktex@dots{}} scripts (@pxref{mktex scripts,,, kpathsea, +Kpathsea}), and so on are all handled by Kpathsea. + +@cindex font aliases +@cindex aliases for fonts +@flindex texfonts.map +The programs which read fonts make use of another Kpathsea feature: +@file{texfonts.map}, which allows arbitrary aliases for the actual names +of font files; for example, @samp{Times-Roman} for @samp{ptmr8r.tfm}. +The distributed (and installed by default) @file{texfonts.map} includes +aliases for many widely available PostScript fonts by their PostScript +names. + + +@node Output file location +@section Output file location + +@cindex output file location +@cindex current directory, used for output +@flindex .@r{, used for output} +All the programs generally follow the usual convention for output files. +Namely, they are placed in the directory current when the program is +run, regardless of any input file location; or, in a few cases, output +is to standard output. + +For example, if you run @samp{tex /tmp/foo}, for example, the output +will be in @file{./foo.dvi} and @file{./foo.log}, not +@file{/tmp/foo.dvi} and @file{/tmp/foo.log}. + +@opindex -output-directory +@cindex output directory, specifying +@cindex readonly directory, running @TeX{} in +You can use the @samp{-output-directory} option to cause all output +files that would normally be written in the current directory to be +written in the specified directory instead. @xref{Common options}. + +@vindex TEXMFOUTPUT@r{, used if @samp{.} unwritable} +@cindex readonly directory, running @TeX{} in +If the current directory is not writable, and @samp{-output-directory} +is not specified, the main programs (@TeX{}, Metafont, MetaPost, and +Bib@TeX{}) make an exception: if the config file or environment +variable value @code{TEXMFOUTPUT} is set (it is not by default), +output files are written to the directory specified. + +@vindex TEXMFOUTPUT@r{, used for reading} +@code{TEXMFOUTPUT} is also checked for input files, as @TeX{} often +generates files that need to be subsequently read; for input, no +suffixes (such as @samp{.tex}) are added by default and no exhaustive +path searching is done, the input name is +simply checked as given. + + +@node Three programs +@chapter Three programs: Metafont, MetaPost, and @TeX{} + +@cindex three programs +@cindex @TeX{}, Metafont, and MetaPost +@cindex Metafont, MetaPost, and @TeX{} +@cindex MetaPost, @TeX{}, and Metafont + +@TeX{}, Metafont, and MetaPost have a number of features in common. +Besides the ones here, command-line options and other commonalities +are described in the previous section. + +@menu +* Runtime options:: The @file{texmf.cnf} configuration file. +* Initial and virgin:: Making memory dumps vs. production runs. +* Memory dumps:: .fmt/.base files for fast startup. +* Editor invocation:: The `e' response at errors. +* \input filenames:: Filename delimiters and Kpathsea expansion. +@end menu + + +@node Runtime options +@section Runtime options + +@cindex runtime options + +@cindex configuration file values +@cindex array sizes +@flindex texmf.cnf +Besides the configure- and compile-time options described in the +installation section (@pxref{Installation}), you can control a number +of parameters in the @file{texmf.cnf} runtime file read by Kpathsea +(@pxref{Config files,,, kpathsea, Kpathsea}). + +The main purpose of @file{texmf.cnf} is to specify search paths, but +array sizes and other options are also set there. Most are rather +obscure. Here are a few of the more interesting values: + +@vtable @samp +@item main_memory +Total words of memory available, for @TeX{}, Metafont, and MetaPost. +Must remake the format file after changing. + +@item extra_mem_bot +@cindex boxes, memory for +@cindex glue, memory for +@cindex breakpoints, memory for +@cindex PiC@TeX{}, increasing memory for +Extra space for ``large'' @TeX{} data structures (default 0): boxes, +glue, breakpoints, et al. If you use PiC@TeX{}, you may well want to +set this. + +@item expand_depth +@cindex recursive expansion limit +@cindex expansion limit, recursive +@cindex runtime stack overflow +@cindex overflow, of runtime stack +@cindex segmentation fault +@vindex SIGSEGV +Limit on recursive expansion calls before @TeX{} aborts (default +10000). If a @TeX{} program does an unterminated recursive expansion, +@TeX{} will dutifully expand macros until the system's runtime stack +overflows, typically with a segmentation fault (SIGSEGV). This +parameter was introduced to minimize the chance of that unpleasant +(though not dangerous) crash, instead allowing @TeX{} to quit with a +more informative message. + +@pindex libsigsegv @r{library} +The crash can still happen, though, if the system has an exceptionally +small memory allocation for its stack. There is no quantitative way to +determine the limit, and it does not seem worth implementing +system-dependent heuristics to guess at the number, since it's highly +improbable that any real @TeX{} code will ever need more than 10000 +recursive expansions (it has never happened). For the same reason, +using the libsigsegv library (@url{https://gnu.org/s/libsigsegv}) does +not seem worth the effort. + +@item texmf_casefold_search +@xref{Casefolding search,,, kpathsea, Kpathsea}. + +@end vtable + +@cindex array limit, fixed +@cindex swap space, as array limit +@cindex reallocation of arrays +@cindex dynamic array allocation +Ideally all arrays would be dynamically expanded as necessary, so the +only limiting factor would be the amount of swap space available, or +some configurable limit much larger than can currently be supported. + +Unfortunately, implementing this is extremely difficult, as the fixed +size of arrays is assumed in many places throughout the source code. +These runtime limits are a practical compromise between the +compile-time limits in previous versions, and truly dynamic arrays. +(On the other hand, the Web2c Bib@TeX{} implementation does do true +dynamic reallocation of some arrays.) + +@cindex modifying @file{texmf.cnf} in @TeX{} Live +@cindex location of @file{texmf.cnf} in @TeX{} Live +Nowadays there is rarely a reason to modify the values. But if you do +wish to modify @file{texmf.cnf}, in @TeX{} Live the best approach is +to put your changes, and only your changes at the top of the TL +installation tree. That is, if the system @file{texmf.cnf} is +installed in +@file{/some/path/to/texlive/YYYY/texmf-dist/web2c/texmf.cnf} is put +your custom settings in @file{/some/path/to/texlive/YYY/texmf.cnf}, +where @var{YYYY} is the year of installation (if you use that +subdirectory; it's the default). That way, unrelated changes to the +system @file{texmf.cnf} can happen with normal updates, without +affecting your local values. + + +@node Initial and virgin +@section Initial and virgin + +@cindex executables, shared initial and virgin +The @TeX{} and Metafont programs each have two main variants, called +@dfn{initial} and @dfn{virgin}. MetaPost no longer makes this +distinction. + +The initial form is enabled if: +@enumerate +@item +@opindex -ini +the @samp{-ini} option was specified; or +@item +the program name is @file{initex} resp.@: @file{inimf}; or +@item +the first line of the main input file is @samp{%&ini}; +@end enumerate +@noindent +otherwise, the virgin form is used. + +@cindex virgin programs +@cindex production use +The @dfn{virgin} form is the one generally invoked for production use. +The first thing it does is read a memory dump (@pxref{Determining the +memory dump to use}), and then proceeds on with the main job. + +@cindex initial programs +@cindex initializations, lengthy +The @dfn{initial} form is generally used only to create memory dumps +(see the next section). It starts up more slowly than the virgin form, +because it must do lengthy initializations that are encapsulated in the +memory dump file. + + +@node Memory dumps +@section Memory dumps + +@cindex memory dumps + +@cindex dumping memory +@cindex macros, predefining in memory dumps +@cindex predefined macros and memory dumps +In typical use, @TeX{} and Metafont require a large number of +macros to be predefined; therefore, they support @dfn{memory dump} +files, which can be read much more efficiently than ordinary source +code. + +@menu +* Creating memory dumps:: +* Determining the memory dump to use:: +* Hardware and memory dumps:: +@end menu + + +@node Creating memory dumps +@subsection Creating memory dumps + +@cindex memory dumps, creating +@cindex creating memory dumps +@cindex writing memory dumps + +The programs all create memory dumps in slightly idiosyncratic (thought +substantially similar) way, so we describe the details in separate +sections (references below). The basic idea is to run the initial +version of the program (@pxref{Initial and virgin}), read the source +file to define the macros, and then execute the @code{\dump} primitive. + +Also, each program uses a different filename extension for its memory +dumps, since although they are completely analogous they are not +interchangeable (@TeX{} cannot read a Metafont memory dump, for +example). + +Here is a list of filename extensions with references to examples of +creating memory dumps: + +@table @asis +@item @TeX{} +(@samp{.fmt}) @xref{Initial TeX,,Initial @TeX{}}. + +@item Metafont +(@samp{.base}) @xref{Initial Metafont}. +@end table + +When making memory dumps, the programs read environment variables and +configuration files for path searching and other values as usual. If +you are making a new installation and have environment variables +pointing to an old one, for example, you will probably run into +difficulties. + + +@node Determining the memory dump to use +@subsection Determining the memory dump to use + +@cindex memory dump to use, determining +@cindex fmt file, determining +@cindex base file, determining +@cindex mem file, determining + +The virgin form (@pxref{Initial and virgin}) of each program always +reads a memory dump before processing normal source input. All three +programs determine the memory dump to use in the same way: + +@enumerate +@item +If the first non-option command-line argument begins with @samp{&}, the +program uses the remainder of that argument as the memory dump name. +For example, running @samp{tex \&super} reads @file{super.fmt}. (The +backslash protects the @samp{&} against interpretation by the shell.) + +@item +@opindex -fmt=@var{fmt} +@opindex -base=@var{base} +If the @samp{-fmt} resp.@: @samp{-base} option is +specified, its value is used. + +@item +@opindex -progname=@var{string} +If the @samp{-progname} option is specified, its value is used. + +@item +@kindex %& @r{magic number} +If the first line of the main input file (which must be specified on the +command line, not in response to @samp{**}) is @code{%&@var{dump}}, and +@var{dump} is an existing memory dump of the appropriate type, +@var{dump} is used. + +The first line of the main input file can also specify which character +translation file is to be used: @code{%&-translate-file=@var{tcxfile}} +(@pxref{TCX files}). + +These two roles can be combined: @code{%&@var{dump} +-translate-file=@var{tcxfile}}. If this is done, the name of the dump +must be given first. + +@item +@cindex program name, determines memory dump +@cindex links to binaries +Otherwise, the program uses the program invocation name, most commonly +@file{tex} resp.@: @file{mf}. For example, if @file{latex} is a link +to @file{tex}, and the user runs @samp{latex foo}, @file{latex.fmt} +will be used. + +@end enumerate + + +@node Hardware and memory dumps +@subsection Hardware and memory dumps + +@cindex hardware and memory dumps +@cindex memory dumps and hardware +@cindex sharing memory dumps +@cindex fmt files, sharing +@cindex base files, sharing +@cindex mem files, sharing + +@cindex LittleEndian machines +@cindex BigEndian machines +@cindex endian dependencies +@cindex machine dependencies +@cindex architecture dependencies +@cindex dependencies, hardware +@opindex --disable-dump-share configure @r{option} +By default, memory dump files are generally sharable between +architectures of different types; specifically, on machines of different +endianness (@pxref{Byte order,,,libc,GNU C Library}). (This is a +feature of the Web2c implementation, and is not true of all @TeX{} +implementations.) If you specify @samp{--disable-dump-share} to +@code{configure}, however, memory dumps will be endian-dependent. + +@cindex byte swapping +@cindex swapping bytes +The reason to do this is speed. To achieve endian-independence, the +reading of memory dumps on LittleEndian architectures, such as PC's and +DEC architectures, is somewhat slowed (all the multibyte values have to +be swapped). Usually, this is not noticeable, and the advantage of +being able to share memory dumps across all platforms at a site far +outweighs the speed loss. But if you're installing Web2c for use on +LittleEndian machines only, perhaps on a PC being used only by you, you +may wish to get maximum speed. + +@cindex floating-point values +@cindex glue ratio representations +@TeX{}nically, even without @samp{--disable-dump-share}, sharing of +@file{.fmt} files cannot be guaranteed to work. Floating-point values +are always written in native format, and hence will generally not be +readable across platforms. Fortunately, @TeX{} uses floating point +only to represent glue ratios, and all common formats (plain, +@LaTeX{}, AMS@TeX{}, @dots{}) do not do any glue setting at +@file{.fmt}-creation time. Metafont does not use floating point in +any dumped value at all. + +@cindex date and time, in memory dumps +@cindex time and date, in memory dumps +@cindex memory dumps, contain date and time +Incidentally, different memory dump files will never compare equal +byte-for-byte, because the program always dumps the current date and +time. So don't be alarmed by just a few bytes difference. + +@cindex Harbison, Samuel P. +@cindex Steele Jr., Guy L. +If you don't know what endianness your machine is, and you're curious, +here is a little C program to tell you. (The @code{configure} script +contains a similar program.) This is from the book @cite{C: A Reference +Manual}, by Samuel P. Harbison and Guy L. Steele +Jr@:. (@pxref{References}). + +@example +main () +@{ + /* Are we little or big endian? From Harbison&Steele. */ + union + @{ + long l; + char c[sizeof (long)]; + @} u; + u.l = 1; + if (u.c[0] == 1) + printf ("LittleEndian\n"); + else if (u.c[sizeof (long) - 1] == 1) + printf ("BigEndian\n"); + else + printf ("unknownEndian"); + + exit (u.c[sizeof (long) - 1] == 1); +@} +@end example + + +@node Editor invocation +@section Editor invocation + +@cindex editor invoked at error +@cindex errors, editor invoked at +@opindex e @r{response at error prompt} + +@TeX{}, Metafont, and MetaPost all (by default) stop and ask for user +intervention at an error. If the input came from a file, and the user +responds with @kbd{e} or @kbd{E}, the program invokes an editor. + +@vindex TEXEDIT +@vindex MFEDIT +@vindex MPEDIT +@opindex --with-editor=@var{cmd} +@flindex texmf.cnf @r{for editors} +Specifying @samp{--with-editor=@var{cmd}} to @code{configure} sets the +default editor command string to @var{cmd}. The environment +variables/configuration values @code{TEXEDIT}, @code{MFEDIT}, and +@code{MPEDIT} (respectively) override this. If @samp{--with-editor} is +not specified, the default is @code{vi +%d %s} on Unix, and an +invocation of the @TeX{}works editor on Windows. (See +@file{texmf.cnf} for the precise values.) + +In this string, @samp{%d} is replaced by the line number of the error, +and @samp{%s} is replaced by the name of the current input file. + + +@node \input filenames +@section @code{\input} filenames + +@cindex input filenames +@cindex filename conventions, in input files +@findex \input @r{filenames} + +@TeX{}, Metafont, and MetaPost source programs can all read other source +files with the @code{\input} (@TeX{}) and @code{input} (MF and MP) +primitives: +@example +\input @var{name} % in TeX +@end example + +@cindex space-terminated filenames +@cindex whitespace-terminated filenames +@cindex terminator for filenames +The file @var{name} can always be terminated with whitespace; for +Metafont and MetaPost, the statement terminator @samp{;} also works. +(@LaTeX{} and other macro packages provide other interfaces to +@code{\input} that allow different notation; here we are concerned only +with the primitive operation.) + +As (allowed) extensions to standard @TeX{}, Web2c also supports +specifying the filename in double quotes (@code{"some name"}) and in +braces (@code{@{"some name"@}}), which is convenient for filenames +containing spaces or other special characters, as described in the +sections below. + +In all cases, space tokens are ignored after the filename is read. + +@cindex @code{"} character, ignored in filenames +@cindex double quote character, ignored in filenames +Also, double quote (@code{"}) characters are ignored within the +filename; there is no way to read files whose names contain a @code{"}. + +@cindex portable filenames +However, for maximal portability of your document across systems, use +only the characters @samp{a}--@samp{z}, @samp{0}--@samp{9}, and at +most one @samp{.}. Do not use anything but simple filenames, since +directory separators vary among systems; instead, add the necessary +directories to the appropriate search path. + +@menu +* Quotes: \input quoted filename. \input "some name" +* Braces: \input braced filename. \input @{some name@} +* Caveats: \input filename caveats. Tokenization, nulls, Kpathsea expansion. +@end menu + + +@node \input quoted filename +@subsection @code{\input} quoted filename: @code{\input "some name"} + +@cindex @code{\input} quoted filename +@cindex quoted filename for @code{\input} + +As of Web2c version 7.5.3 (2004), double-quote characters can be used +to include spaces or other special characters. In typical use, the +@samp{"} characters surround the entire filename: +@example +\input "filename with spaces" +@end example + +Technically, the quote characters can be used inside the name, and +can enclose any characters, as in: +@example +\input filename" "with" "spaces +@end example + +One more point. In @LaTeX{}, the quotes are needed inside the braces +of its @code{\input} macro, thus: +@example +\input@{a b@} % fails +\input@{"a b"@} % ok +@end example + +There is no way to quote the quote character. + + +@node \input braced filename +@subsection @code{\input} braced filename: @code{\input@{some name@}} + +@cindex @code{\input} braced (grouped) filename +@cindex braced filename for @code{\input} +@cindex group-delimited filename for @code{\input} + +As of Web2c 2020, @code{\input} filenames in @TeX{} engines (this does +not apply in Metafont and MetaPost) can also be specified within a +@TeX{} group, typically curly braces. For example: +@example +\input@{filename with spaces@} +@end example + +As always with @TeX{}, the brace characters are not hardwired; what +counts is the category code: the first token after the @code{\input} +must be of catcode@tie{}1 (begin group), and it is matched with the +next character of catcode@tie{}2 (end group). + +Within the group-delimited filename, braces are treated as normal +characters. + +As with all forms of filenames, following spaces are ignored (after +the end group), and double quote (@code{"}) characters are ignored +within the filename. + + +@node \input filename caveats +@subsection @code{\input} filename caveats + +@cindex @code{\input} filename caveats +@cindex caveats for @code{\input} filenames +@cindex tokenization, and @code{\input} filenames +@cindex expansion, and @code{\input} filenames +@cindex multiple spaces, and @code{\input} filenames +@cindex tabs, and @code{\input} filenames +The quoting mechanisms just described come into play @emph{after} +@TeX{} has tokenized and expanded the input. So, multiple spaces and +tabs will generally be seen as a single space, active characters such +as @samp{~} are expanded first (generally causing an error), and so +on. More examples below. + +@cindex NUL, not allowed in filenames +@cindex eight-bit characters in filenames +@cindex meta characters in filenames +On the other hand, various C library routines and Unix itself use the null +byte (character code zero, ASCII NUL) to terminate strings. So +filenames in Web2c cannot contain nulls, even though @TeX{} itself does +not treat NUL specially. + +@kindex ~ @r{expansion in filenames} +@kindex $ @r{expansion in filenames} +Finally, the present Web2c implementation does @samp{~} and @samp{$} +expansion on @var{name}, unlike Knuth's original implementation. +Thus: +@example +\input ~jsmith/$foo.bar +@end example +will dereference the environment variable or Kpathsea config file +value @samp{foo} and read that file, extended with @samp{.bar}, in +user @samp{jsmith}'s home directory. You can also use braces in the +variable expansion, as in @samp{$@{foo@}bar}, if you want to follow +the variable name with a letter, numeral, or @samp{_}. + +(So another way to get a program to read a filename containing +whitespace is to define an environment variable and dereference it.) + +@findex \string@r{, and @code{\input filenames}} +In all the common @TeX{} formats (plain @TeX{}, @LaTeX{}, Con@TeX{}t, +AMS@TeX{}, @dots{}), the characters @samp{~} and @samp{$} have special +category codes, so to actually use these in a document you have to +change their catcodes or use @code{\string}. + + +@node TeX +@chapter @TeX{}: Typesetting + +@cindex @TeX{}, description of +@cindex typesetting +@cindex mathematical typesetting + +@TeX{} is a typesetting system: it was especially designed to handle +complex mathematics, as well as most ordinary text typesetting. + +@cindex batch languages +@cindex word processor, not +@TeX{} is a batch language, like C or Pascal, and not an interactive +``word processor'': you compile a @TeX{} input file into a corresponding +device-independent (DVI) file (and then translate the DVI file to the +commands for a particular output device). This approach has both +considerable disadvantages and considerable advantages. For a complete +description of the @TeX{} language, see @cite{The @TeX{}book} +(@pxref{References}). Many other books on @TeX{}, introductory and +otherwise, are available. + +@menu +* tex invocation:: Invoking TeX. +* Initial TeX:: Making format files. +* Formats:: Major TeX macro packages. +* Languages and hyphenation:: TeX supports many human languages. +* Shell escapes:: Running subprograms from TeX. +* IPC and TeX:: DVI output to a socket. +* TeX extensions:: Additional engines with additional features. +@end menu + + +@node tex invocation +@section @code{tex} invocation + +@pindex tex +@cindex @TeX{}, invocation + +@TeX{} (usually invoked as @code{tex}) formats the given text and +commands, and outputs a corresponding device-independent representation +of the typeset document. This section merely describes the options +available in the Web2c implementation. For a complete description of +the @TeX{} typesetting language, see @cite{The @TeX{}book} +(@pxref{References}). + +@TeX{}, Metafont, and MetaPost process the command line (described +here) and determine their memory dump (fmt) file in the same way +(@pxref{Memory dumps}). Synopses: + +@example +tex [@var{option}]@dots{} [@var{texname}[.tex]] [@var{tex-commands}] +tex [@var{option}]@dots{} \@var{first-line} +tex [@var{option}]@dots{} &@var{fmt} @var{args} +@end example + +@flindex .tex +@cindex @TeX{}, input files found +@TeX{} searches the usual places for the main input file @var{texname} +(@pxref{Supported file formats,,, kpathsea, Kpathsea}), extending +@var{texname} with @file{.tex} if necessary. To see all the +relevant paths, set the environment variable @code{KPATHSEA_DEBUG} to +@samp{-1} before running the program. + +After @var{texname} is read, @TeX{} processes any remaining +@var{tex-commands} on the command line as regular @TeX{} input. Also, +if the first non-option argument begins with a @TeX{} escape character +(usually @code{\}), @TeX{} processes all non-option command-line +arguments as a line of regular @TeX{} input. + +If no arguments or options are specified, @TeX{} prompts for an +input file name with @samp{**}. + +@flindex texput +@TeX{} writes the main DVI output to the file +@file{@var{basetexname}.dvi}, where @var{basetexname} is the basename of +@var{texname}, or @samp{texput} if no input file was specified. A DVI +file is a device-independent binary representation of your @TeX{} +document. The idea is that after running @TeX{}, you translate the DVI +file using a separate program to the commands for a particular output +device, such as a PostScript printer +(@pxref{Top,,Introduction,dvips,Dvips}) or an X Window System display +(see xdvi(1)). + +@cindex EC fonts +@pindex mktextfM@r{, disabling} +@findex \font @r{and dynamic generation} +@TeX{} also reads TFM files for any fonts you load in your document with +the @code{\font} primitive. By default, it runs an external program +named @file{mktextfm} to create any nonexistent TFM files. You can +disable this at configure-time or runtime (@pxref{mktex +configuration,,, kpathsea, Kpathsea}). This is enabled mostly for the +sake of the EC fonts, which can be generated at any size. + +@findex \openout @r{and security} +@cindex security, and @code{\openout} +@cindex output files, written by @TeX{} programs +@cindex Trojan horses and @TeX{} programs +@cindex dot files, written by @TeX{} programs +@cindex security, and output files +@TeX{} can write output files, via the @code{\openout} primitive; this opens +a security hole vulnerable to Trojan horse attack: an unwitting user could +run a @TeX{} program that overwrites, say, @file{~/.rhosts}. (MetaPost has +a @code{write} primitive with similar implications). To alleviate this and +similar problems the functions @code{kpathsea_out_name_ok} and +@code{kpathsea_in_name_ok} from the Kpathse library (@pxref{Calling +sequence,,, kpathsea, Kpathsea}) are used to determine if a given filename +is acceptable to be opened for output or input, depending on the setting of +the configuration variables @code{openout_any} and @code{openin_any}: +@samp{a} (for ``any'', the default for @code{openin_any}), @samp{r} (for +``restricted''), or @samp{p} (for ``paranoid'', the default for +@code{openout_any}). + +In any case, all @code{\openout} filenames are recorded in the log file, +except those opened on the first line of input, which is processed when +the log file has not yet been opened. + +The program accepts the following options, as well as the standard +@samp{-help} and @samp{-version} (@pxref{Common options}): +@table @samp +@item -enc +@itemx -[no]-file-line-error +@itemx -fmt=@var{fmtname} +@itemx -halt-on-error +@itemx -ini +@itemx -interaction=@var{string} +@itemx -ipc +@itemx -ipc-start +@itemx -jobname=@var{string} +@itemx -kpathsea-debug=@var{number} +@itemx -[no]parse-first-line +@itemx -output-directory +@itemx -progname=@var{string} +@itemx -recorder +@itemx -translate-file=@var{tcxfile} +@itemx -8bit +These options are common to @TeX{}, Metafont, and MetaPost. +@xref{Common options}. + +@item -enc +@opindex -enc +@cindex Unicode input +@cindex UTF-8 input +Enable enc@TeX{} extensions, such as @code{\mubyte}. This can be used +to support the Unicode UTF-8 input encoding, although using an engine +with native Unicode support is more common nowadays. +@url{http://www.olsak.net/enctex.html}. + +@item -ipc +@itemx -ipc-start +@opindex -ipc +@opindex -ipc-start +@opindex --enable-ipc configure @r{option} +With either option, @TeX{} writes its DVI output to a socket as well as +to the usual @file{.dvi} file. With @samp{-ipc-start}, @TeX{} also +opens a server program at the other end to read the output. @xref{IPC +and TeX,,IPC and @TeX{}}. + +These options are available only if the @samp{--enable-ipc} option was +specified to @code{configure} during installation of Web2c. + +@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}. +For @TeX{} proper, @var{filetype} can only be @samp{tex} and +@samp{tfm}, but for pdf@TeX{} and lua@TeX{}, it can also be @samp{pk}. + +@item -mltex +@opindex -mltex +@cindex ML@TeX{}, enabling +@cindex program names, special +If we are @code{INITEX} (@pxref{Initial and virgin}), enable ML@TeX{} +extensions such as @code{\charsubdef}. Implicitly set if the program +name is @code{mltex}. @xref{MLTeX,,ML@TeX{}}. + +@item -output-comment=@var{string} +@opindex -output-comment=@var{string} +@vindex output_comment @r{for DVI files} +@cindex DVI comment, specifying +@cindex regression testing +Use @var{string} as the DVI file comment. Ordinarily, this comment +records the date and time of the @TeX{} run, but if you are doing +regression testing, you may not want the DVI file to have this spurious +difference. This is also taken from the environment variable and +config file value @samp{output_comment}. + +@item -shell-escape +@opindex -shell-escape +@itemx -no-shell-escape +@opindex -no-shell-escape +@itemx -shell-restricted +@opindex -shell-restricted +Enable, or disable, or enable with restrictions the +@code{\write18@{@var{shell-command}@}} feature for external executing +shell commands. @xref{Shell escapes}. + +@item -enable-write18 +@opindex -enable-write18 +@itemx -disable-write18 +@opindex -disable-write18 +Synonyms for @option{-shell-escape} and @option{-no-shell-escape}, for +compatibility with MiK@TeX{}. (MiK@TeX{} also accepts both pairs of +options.) @xref{Shell escapes}. + +@item -src-specials +@itemx -src-specials=@var{string} +@cindex generating source specials +This option makes @TeX{} output specific source information using +@samp{\special} commands in the DVI file. These @samp{\special} track +the current file name and line number. + +Using the first form of this option, the @samp{\special} commands are +inserted automatically. + +In the second form of the option, @var{string} is +a comma separated list of the following values: @samp{cr}, +@samp{display}, @samp{hbox}, @samp{math}, @samp{par}, @samp{parend}, +@samp{vbox}. You can use this list to specify where you want @TeX{} to +output such commands. For example, @samp{-src-specials=cr,math} will +output source information every line and every math formula. + +These commands can be used with the appropriate DVI viewer and text +editor to switch from the current position in the editor to the same +position in the viewer and back from the viewer +to the editor. + +This option works by inserting @samp{\special} commands into the token +stream, and thus in principle these additional tokens can be recovered +or seen by the tricky-enough macros. If you run across a case, let us +know, because this counts as a bug. However, such bugs are very hard +to fix, requiring significant changes to @TeX{}, so please don't count +on it. + +Redefining @samp{\special} will not affect the functioning of this +option. The commands inserted into the token stream are +hard-coded to always use the @samp{\special} primitive. + +@TeX{} does not pass the trip test when this option is enabled. + +@end table + + +@node Initial TeX +@section Initial @TeX{} + +@cindex initial @TeX{} +@cindex @TeX{}, initial + +@flindex .fmt +@cindex fmt files +The @dfn{initial} form of @TeX{} is invoked by @samp{tex -ini}. It +does lengthy initializations avoided by the ``virgin'' (@code{vir}) +form, so as to be capable of dumping @samp{.fmt} files (@pxref{Memory +dumps}). For a detailed comparison of virgin and initial forms, +@pxref{Initial and virgin}. + +For a list of options and other information, @pxref{tex invocation}. + +@flindex plain.fmt +@flindex tex.fmt +@cindex format files +Unlike Metafont and MetaPost, many format files are commonly used with +@TeX{}. The standard one implementing the features described in the +@cite{@TeX{}book} is @samp{plain.fmt}, also known as @samp{tex.fmt} +(again, @pxref{Memory dumps}). It is created by default during +installation, but you can also do so by hand if necessary (e.g., if an +update to @file{plain.tex} is issued): +@example +tex -ini '\input plain \dump' +@end example +@noindent +(The quotes prevent interpretation of the backslashes from the shell.) +Then install the resulting @file{plain.fmt} in @samp{$(fmtdir)} +(@file{/usr/local/share/texmf/web2c} by default), and link +@file{tex.fmt} to it. + +The necessary invocation for generating a format file differs for each +format, so instructions that come with the format should explain. The +top-level @file{web2c} Makefile has targets for making most common +formats: @t{plain latex amstex texinfo eplain}. @xref{Formats}, for +more details on @TeX{} formats. + + +@node Formats +@section Formats + +@cindex formats for @TeX{} +@cindex @TeX{}, format packages for +@cindex macro packages, major @TeX{} + +@TeX{} @dfn{formats} are large collections of macros, often dumped +into a @file{.fmt} file (@pxref{Memory dumps}) by @code{tex -ini} +(@pxref{Initial TeX}). A number of formats are in reasonably +widespread use, and the Web2c Makefile has targets to make the versions +current at the time of release. You can change which formats are +automatically built by setting the @code{fmts} Make variable; by default, +only the @samp{plain} and @samp{latex} formats are made. + +Nowadays, the formats are generally installed and updated as part of a +larger @TeX{} distribution, such as @TeX{} Live +(@url{https://tug.org/texlive}). + +@table @t +@item latex +@cindex @LaTeX{} +The most widely used format. The current release is named +`@LaTeX{}2e'; new versions are released approximately every six +months, with patches issued as needed. The old release was called +`@LaTeX{} 2.09', and is no longer maintained or supported. @LaTeX{} +attempts to provide generic markup instructions, such as +``emphasize'', instead of specific typesetting instructions, such as +``use the 10@dmn{pt} Computer Modern italic font''. The @LaTeX{} home +page: @url{https://www.latex-project.org}. + +@item context +@cindex Con@TeX{}t +Con@TeX{}t is an independent macro package which has a basic document +structuring approach similar to @LaTeX{}. It also supports creating +interactive PDF files and has integrated MetaPost support, among many +other interesting features. The Con@TeX{}t home page: +@url{http://www.pragma-ade.com}. + +@item amstex +@cindex AMS@TeX{} +@cindex American Mathematical Society, typesetting system +@cindex Mathematical Reviews +The official typesetting system of the American Mathematical Society. +Like @LaTeX{}, it encourages generic markup commands. The AMS also +provides many @LaTeX{} packages for authors who prefer @LaTeX{}. Taken +together, they are used to produce nearly all AMS publications, e.g., +@cite{Mathematical Reviews}. The AMS@TeX{} home page: +@url{https://www.ams.org/tex}. + +@item texinfo +@cindex Texinfo +@cindex Info format +@cindex Free Software Foundation documentation system +The documentation system developed and maintained by the Free Software +Foundation for their software manuals. It can be automatically +converted into plain text, a machine-readable on-line format called +`info', HTML, etc. The Texinfo home page: +@url{https://www.gnu.org/software/texinfo}. + +@item eplain +@cindex Eplain +@cindex expanded plain format +The ``expanded plain'' format provides various common features (e.g., +symbolic cross-referencing, tables of contents, indexing, citations +using Bib@TeX{}), for those authors who prefer to handle their own +high-level formatting. The Eplain home page: +@url{https://tug.org/eplain}. + +@item slitex +@cindex Sli@TeX{} +@cindex slides, producing +@flindex beamer@r{, package} +An obsolete @LaTeX{} 2.09 format for making slides. It is replaced by +the @samp{slides} document class, although the @samp{beamer} package +is the most commonly method for making slides nowadays. The Beamer +page on CTAN: @url{https://ctan.org/pkg/beamer}. + +@end table + + +@node Languages and hyphenation +@section Languages and hyphenation + +@cindex language support in @TeX{} +@cindex human languages, supported in @TeX{} +@cindex hyphenation and languages + +@TeX{} supports most natural languages. See also @ref{TeX extensions,, +@TeX{} extensions}. + +@menu +* MLTeX:: Multi-lingual TeX. +* TCX files:: Support for different character sets & fonts. +* patgen invocation:: Creating hyphenation patterns. +@end menu + + +@node MLTeX +@subsection ML@TeX{}: Multi-lingual @TeX{} + +@pindex mltex +@cindex Multi-lingual @TeX{} + +@cindex Ferguson, Michael +@cindex Raichle, Bernd +@cindex accents, hyphenating words with +@cindex glyph substitutions +@cindex substitutions of font glyphs +Multi-lingual @TeX{} (@code{mltex}) is an extension of @TeX{} originally +written by Michael Ferguson and now updated and maintained by Bernd +Raichle. With the advent of Unicode, it has become obsolete, though +it is still supported in Web2c in the event of bugs or compilation +bugs. + +ML@TeX{} allows the use of non-existing glyphs in a font by declaring +glyph substitutions. These are restricted to substitutions of an +accented character glyph, which need not be defined in the current +font, by its appropriate @code{\accent} construction using a base and +accent character glyph, which do have to exist in the current font. +This substitution is automatically done behind the scenes, if +necessary, and thus ML@TeX{} additionally supports hyphenation of +words containing an accented character glyph for fonts missing this +glyph (e.g., Computer Modern). Standard @TeX{} suppresses hyphenation +in this case. + +ML@TeX{} works at @file{.fmt}-creation time: the basic idea is to +specify the @samp{-mltex} option to @TeX{} when you @code{\dump} a +format. Then, when you subsequently invoke @TeX{} and read that +@code{.fmt} file, the ML@TeX{} features described below will be enabled. + +Generally, you use special macro files to create an ML@TeX{} @code{.fmt} +file. + +The sections below describe the two new primitives that ML@TeX{} defines. +Aside from these, ML@TeX{} is completely compatible with standard @TeX{}. + +@menu +* \charsubdef:: Character substitution definitions. +* \tracingcharsubdef:: Tracing substitutions. +@end menu + + +@node \charsubdef +@subsubsection @code{\charsubdef}: Character substitutions + +@findex \charsubdef @r{and ML@TeX{}} + +The most important primitive ML@TeX{} adds is @code{\charsubdef}, used +in a way reminiscent of @code{\chardef}: +@example +\charsubdef @var{composite} [=] @var{accent} @var{base} +@end example + +Each of @var{composite}, @var{accent}, and @var{base} are font glyph +numbers, expressed in the usual @TeX{} syntax: @t{`\e} symbolically, +@t{'145} for octal, @t{"65} for hex, @t{101} for decimal. + +ML@TeX{}'s @code{\charsubdef} declares how to construct an accented +character glyph (not necessarily existing in the current font) using two +character glyphs (that do exist). Thus it defines whether a character +glyph code, either typed as a single character or using the @code{\char} +primitive, will be mapped to a font glyph or to an @code{\accent} glyph +construction. + +For example, if you assume glyph code 138 +@cindex e-circumflex +(decimal) for an e-circumflex +@tex +(\^e) +@end tex +and you are using the Computer Modern fonts, which have the circumflex +accent in position 18 and lowercase `e' in the usual ASCII position 101 +decimal, you would use @code{\charsubdef} as follows: + +@example +\charsubdef 138 = 18 101 +@end example + +For the plain @TeX{} format to make use of this substitution, you have +to redefine the circumflex accent macro @code{\^} in such a way that if +its argument is character `e' the expansion @code{\char138 } is used +instead of @code{\accent18 e}. Similar @code{\charsubdef} declaration +and macro redefinitions have to be done for all other accented +characters. + +To disable a previous @code{\charsubdef @var{c}}, redefine @var{c} +as a pair of zeros. For example: +@example +\charsubdef '321 = 0 0 % disable N tilde +@end example +@cindex N tilde +@noindent +(Octal @t{'321} is the ISO Latin-1 value for the Spanish N tilde.) + +@code{\charsubdef} commands should only be given once. Although in +principle you can use @code{\charsubdef} at any time, the result is +unspecified. If @code{\charsubdef} declarations are changed, usually +either incorrect character dimensions will be used or ML@TeX{} will +output missing character warnings. (The substitution of a +@code{\charsubdef} is used by @TeX{} when appending the character node +to the current horizontal list, to compute the width of a horizontal box +when the box gets packed, and when building the @code{\accent} +construction at @code{\shipout}-time. In summary, the substitution is +accessed often, so changing it is not desirable, nor generally useful.) + + +@node \tracingcharsubdef +@subsubsection @code{\tracingcharsubdef}: Substitution diagnostics + +@findex \tracingcharsubdef @r{and ML@TeX{}} +@cindex redefined character substitutions +To help diagnose problems with @samp{\charsubdef}, ML@TeX{} provides a +new primitive parameter, @code{\tracingcharsubdef}. If positive, every +use of @code{\charsubdef} will be reported. This can help track down +when a character is redefined. + +@findex \tracinglostchars @r{and ML@TeX{}} +In addition, if the @TeX{} parameter @code{\tracinglostchars} is 100 or +more, the character substitutions actually performed at +@code{\shipout}-time will be recorded. + + +@node TCX files +@subsection TCX files: Character translations + +@flindex TCX @r{character translation files} +@flindex .tcx @r{character translation files} +@cindex character translation files + +@cindex international characters +@cindex 8-bit characters +@cindex accented character +TCX (@TeX{} character translation) files help @TeX{} support direct +input of 8-bit international characters if fonts containing those +characters are being used. Specifically, they map an input (keyboard) +character code to the internal @TeX{} character code (a superset of +ASCII). + +Of the various proposals for handling more than one input encoding, +TCX files were chosen because they follow Knuth's original ideas for +the use of the @samp{xchr} and @samp{xord} tables. He ventured that +these would be changed in the WEB source in order to adjust the actual +version to a given environment. It turns out, however, that +recompiling the WEB sources is not as simple a task as Knuth may have +imagined; therefore, TCX files, providing the possibility of changing +of the conversion tables on on-the-fly, have been implemented instead. + +This approach limits the portability of @TeX{} documents, as some +implementations do not support it (or use a different method for +input-internal reencoding). It may also be problematic to determine +the encoding to use for a @TeX{} document of unknown provenance; in +the worst case, failure to do so correctly may result in subtle errors +in the typeset output. But we feel the benefits outweigh these +disadvantages. + +This is entirely independent of the ML@TeX{} extension (@pxref{MLTeX}): +whereas a TCX file defines how an input keyboard character is mapped to +@TeX{}'s internal code, ML@TeX{} defines substitutions for a +non-existing character glyph in a font with a @code{\accent} +construction made out of two separate character glyphs. TCX files +involve no new primitives; it is not possible to specify +that an input (keyboard) character maps to more than one character. + +@vindex WEB2C@r{, search path for TCX files} +Information on specifying TCX files: + +@itemize @bullet +@item +The best way to specify a TCX file is to list it explicitly in the +first line of the main document: +@example +%& -translate-file=@var{tcxfile} +@end example + +@item +You can also specify a TCX file to be used on a particular @TeX{} run +with the command-line option @samp{-translate-file=@var{tcxfile}}. + +@item +TCX files are searched for along the @code{WEB2C} path. + +@item +Initial @TeX{} (@pxref{Initial TeX,,Initial @TeX{}}) ignores TCX files. +@end itemize + +@flindex il1-t1.tcx +@flindex il2-t1.tcx +@flindex empty.tcx +@cindex Cork encoding and ISO input +@cindex T1 encoding and ISO input +The Web2c distribution comes with a number of TCX files. Two +important ones are @file{il1-t1.tcx} and @file{il2-t1.tcx}, which +support ISO Latin 1 and ISO Latin 2, respectively, with Cork-encoded +fonts (a.k.a.@ the @LaTeX{} T1 encoding). TCX files for Czech, +Polish, and Slovak are also provided. + +One other notable TCX file is @file{empty.tcx}, which is, well, +empty. Its purpose is to reset Web2C's behavior to the default (only +visible ASCII being printable, as described below) when a format was +dumped with another TCX being active---which is in fact the case for +everything but plain @TeX{} in the TeX Live and other distributions. +Thus: + +@example +latex somefile8.tex +@result{} terminal etc. output with 8-bit chars +latex --translate-file=empty.tcx somefile8.tex +@result{} terminal etc. output with ^^ notation +@end example + +@cindex syntax of TCX files +Syntax of TCX files: +@enumerate +@item +@cindex blank lines, in TCX files +Line-oriented. Blank lines are ignored. + +@item +@cindex whitespace, in TCX files +Whitespace is ignored except as a separator. + +@item +@cindex comments, in TCX files +Comments start with @samp{%} and continue to the end of the line. + +@item +Otherwise, a line consists of one or two character codes, optionally +followed by 0 or 1. The last number indicates whether @var{dest} is +considered printable. +@example +@var{src} [@var{dest} [@var{prnt}]] +@end example + +@item +@cindex character codes, in TCX files +@cindex octal character codes, in TCX files +@cindex hex character codes, in TCX files +@cindex decimal character codes, in TCX files +Each character code may be specified in octal with a leading @samp{0}, +hexadecimal with a leading @samp{0x}, or decimal otherwise. Values must +be between 0 and 255, inclusive (decimal). + +@item +If the @var{dest} code is not specified, it is taken to be the same as +@var{src}. + +@item +If the same @var{src} code is specified more than once, it is the last +definition that counts. +@end enumerate + +@cindex printable characters, specifying +@kindex ^^ @r{notation, avoiding} +Finally, here's what happens: when @TeX{} sees an input character with +code @var{src}, it 1) changes @var{src} to @var{dest}; and 2) makes the +@var{dest} code ``printable'', i.e., printed as-is in diagnostics and the +log file rather than in @samp{^^} notation. + +By default, no characters are translated, and character codes between 32 +and 126 inclusive (decimal) are printable. + +Specifying translations for the printable ASCII characters (codes +32--127) will yield unpredictable results. Additionally you shouldn't +make the following characters printable: @code{^^I} (TAB), @code{^^J} +(line feed), @code{^^M} (carriage return), and @code{^^?} (delete), +since @TeX{} uses them in various ways. + +@cindex font character code, translating +@cindex keyboard character code, translating +Thus, the idea is to specify the input (keyboard) character code for +@var{src}, and the output (font) character code for @var{dest}. + +@cindex interaction between TCX files and @samp{-8bit}. +By default, only the printable ASCII characters are considered printable +by @TeX{}. If you specify the @samp{-8bit} option, all characters are +considered printable by default. If you specify both the @samp{-8bit} +option and a TCX file, then the TCX can set specific characters to be +non-printable. + +Both the specified TCX encoding and whether characters are printable +are saved in the dump files (like @file{tex.fmt}). So by giving these +options in combination with @samp{-ini}, you control the defaults seen +by anyone who uses the resulting dump file. + +When loading a dump, if the @samp{-8bit} option was given, then all +characters become printable by default. + +When loading a dump, if a TCX file was specified, then the TCX data from +the dump is ignored and the data from the file used instead. + + +@node patgen invocation +@subsection Patgen: Creating hyphenation patterns + +@pindex patgen +@cindex hyphenation patterns, creating +@cindex languages, hyphenation rules for + +Patgen creates hyphenation patterns from dictionary files for use with +@TeX{}. Synopsis: + +@example +patgen @var{dictionary} @var{patterns} @var{output} @var{translate} +@end example + +Each argument is a filename. No path searching is done. The output is +written to the file @var{output}. + +@c @table @var +@c @item dictionary +@c @cindex dictionary file +@c @findex \lefthyphemmin +@c @findex \righthyphenmin +@c The first line contains the values of @code{}\lefthyphenmin} and +@c @code{\righthyphenmin} in columns 1--2 and 3--4. Columns 5, 6, and 7 may +@c optionally contain replacements for the default characters @samp{.}, +@c @samp{-}, and @samp{*} respectively used in the word lists. +@c +@c Subsequent lines are either comments (if they start with two identical +@c characters, e.g., @samp{%%}), or contain the external representation of +@c the lower case version of a letter, followed by an arbitrary number of +@c upper case versions, preceded and separated by a delimiter and followed +@c by two consecutive delimiters. The delimiter may be any character not +@c occurring in either version. + +In addition, Patgen prompts interactively for other values. + +For more information, see @cite{Word hy-phen-a-tion by com-puter} by +Frank Liang (@pxref{References}), and also the @file{patgen.web} source file. + +The only options are @samp{-help} and @samp{-version} (@pxref{Common +options}). + + +@node Shell escapes +@section Shell escapes + +@cindex shell commands in @TeX{} +@cindex security, and shell escapes +@cindex restricted shell escapes +@cindex system command +@vindex shell_escape @r{enabling in @TeX{}} +@findex \immediate\write18 +@findex \write18 @r{shell escape extension} +@findex system @r{C library function} +@flindex texmf.cnf @r{for shell escapes} + +@TeX{} can execute @dfn{shell escapes}, that is, arbitrary shell +commands. Although tremendously useful, this also has obvious +security implications. Therefore, as of @TeX{} Live 2009, a +@dfn{restricted} mode for shell escapes is the default mode of +operation, which allows executing only certain commands, as specified +in the @file{texmf.cnf} configuration file. + +@itemize @bullet +@item +Unrestricted shell escapes are allowed if the option +@option{--shell-escape} is specified, or if the environment variable +or config file value @code{shell_escape} is set to @samp{t} or +@samp{y} and @samp{1}. + +@item +Restricted shell escapes are allowed if @code{shell_escape} is set to +@samp{p}. This is the default. + +@item +Shell escapes are completely disabled if @option{--no-shell-escape} is +specified, or if @code{shell_escape} is set to anything else. +@end itemize + +When enabled, the @TeX{} construct to execute a system command is +@code{\write18@{@var{shell-command}@}}; for example: + +@example +\write18@{echo "hello, world"@} +@end example + +@findex \output @r{routine, and @code{\write}} +From @TeX{}'s point of view, this is a normal @code{\write} command, +and is therefore subject to the usual @TeX{} expansions. Also, the +system call either happens during the @samp{\output} routine or right +away, according to the absence or presence of the @code{\immediate} +prefix, as usual for @code{\write}. + +@cindex exit status, of shell escape +The @var{shell-command} string is passed to the command shell (via the +C library function @code{system}). The output of @var{shell-command} +is not diverted anywhere, so it will not appear in the log file, or +anywhere but the terminal output. The exit status of the system call +is also not available to @TeX{}. + +In unrestricted mode, the argument is simply passed straight to +@code{system} unaltered. + +In restricted mode, ASCII double quote characters (@verb{|"|}) should +always be used in the argument to @code{\write18} where quoting of +arguments is needed, as in the example above. This is to achieve some +measure of system independence. On Unix systems, these are replaced +with single quote (@verb{|'|}) characters to avoid insecure further +expansion. Care is also taken on Windows to avoid additional +expansions (from, e.g., @verb{|`...`|}). Mismatched quotation marks +in the command string result in a diagnostic message in the log file; +no execution is performed. + +@findex shell_escape_commands +After quotation processing, if the first word (delimited by a space or +tab) of the command is in the list specified by the +@code{shell_escape_commands} configuration value, the command is +executed. Otherwise it is not. In any case, a message is written to +the log file. + +The @code{shell_escape_commands} value is a comma-separated list of +words. Whitespace is significant, and typically should not be +present. The default definition in @file{texmf.cnf} looks like this, +but with more commands included: + +@example +shell_escape_commands = bibtex,kpsewhich,repstopdf,... +@end example + +@cindex pipes, reading and writing +@findex \openin@r{, and pipes} +@findex \input@r{, and pipes} +@findex \openout@r{, and pipes} +@findex \pdfshellescape +pdf@TeX{} and lua@TeX{} support reading (via @code{\input} and +@code{\openin}) and writing (via @code{\openout}) from pipes if the +first character is @samp{|}. The following command is then treated +exactly the same as the argument to @code{\write18}. In these +engines, the primitive variable @code{\pdfshellescape} is set to 0 if +shell escapes are disabled, 1 if they are enabled, and 2 if they are +enabled with restrictions. + +@cindex web environments, and security +The purpose of this feature is to make it possible for @TeX{} +documents to perform useful external actions in the common case of an +individual user running a known document on his or her own machine. +In such environments as CGI scripts or wikis where the input has to be +considered untrustworthy, shell escapes should be completely disabled. + + +@node IPC and TeX +@section IPC and @TeX{} + +@cindex IPC +@cindex sockets +(If anyone uses this feature and needs documentation, write +@email{tex-k@@tug.org}.) + +This functionality is available only if the @samp{--enable-ipc} option +was specified to @code{configure} during installation of Web2c +(@pxref{Installation}). + +@vindex IPC_DEBUG +If you define @code{IPC_DEBUG} before compilation (e.g., with @samp{make +XCFLAGS=-DIPC_DEBUG}), @TeX{} will print messages to standard error +about its socket operations. This may be helpful if you are, well, +debugging. + + +@node TeX extensions +@section Extended @TeX{} engines + +@cindex extensions to @TeX{} +@cindex @TeX{}, extensions to + +The base @TeX{} program has been extended in many ways. Here's a +partial list. + +@table @asis +@item e-@TeX{} +@cindex e-@TeX{} +@cindex primitives, new +Adds many new primitives, including right-to-left typesetting and more +registers. Now frozen. More info: @url{https://ctan.org/pkg/etex}. + +@item Aleph +@cindex Aleph +@cindex Omega +@cindex Unicode +This adds Unicode support, right-to-left typesetting, and more. Omega +was the original program. Aleph is an updated version with a variety +of bug fixes, and includes e-@TeX{}. Aleph is not actively maintained. +More info: @url{https://ctan.org/pkg/aleph}, @url{https://ctan.org/pkg/omega}. + +@item pdf@TeX{} +@cindex pdf@TeX{} +@cindex PDF +@cindex micro-typography +@cindex hypertext +@pindex etex @r{is pdf@TeX{}} +Can produce PDF as well as DVI files. It also incorporates the +e-@TeX{} extensions, new primitives for hypertext and +micro-typography, reading/writing from pipes, and much more. In +@TeX{} Live, the command @command{etex} invokes pdf@TeX{} to make all +these additions available with DVI output. Home page: +@url{http://pdftex.org}. + +@item Lua@TeX{} +@cindex Lua@TeX{} +@cindex Lua +@cindex UTF-8 input, native +@cindex OpenType support +@cindex TrueType support +@cindex system fonts, using +Embeds the Lua programming language (@url{http://lua.org}) and opens +up the @TeX{} typesetting engine to control from Lua, starting from +the pdf@TeX{} capabilities as a base. Also natively supports UTF-8 +input, the OpenType and TrueType font formats, and use of system +fonts. Home page: @url{http://luatex.org}. + +@item Xe@TeX{} +@cindex Xe@TeX{} +@cindex Unicode input, native +Combines support for Unicode input, the OpenType and TrueType font +formats, and use of system fonts with the capabilities of pdf@TeX{}, +with the exception of the font expansion part of micro-typography. +Home page: @url{https://tug.org/xetex}. + +@item p@TeX{} +@itemx up@TeX{} +@cindex p@TeX{} +@cindex up@TeX{} +With additional support for Japanese; p@TeX{} was the original engine, +and up@TeX{} has native Unicode support and thus is more useful for +Chinese and Korean. More info: @url{https://ctan.org/pkg/ptex}, +@url{https://ctan.org/pkg/uptex}. + +@item ep@TeX{} +@itemx eup@TeX{} +@cindex ep@TeX{} +@cindex eup@TeX{} +Further extends p@TeX{} and up@TeX{} with the e-@TeX{} extensions. +More info: @url{https://ctan.org/pkg/eptex}, +@url{https://ctan.org/pkg/euptex}. + +@end table + + +@node Metafont +@chapter Metafont: Creating typeface families + +@cindex Metafont +@cindex typeface families +@cindex geometric designs +@cindex shapes +@cindex font design + +Metafont is a system for producing shapes; it was designed for producing +complete typeface families, but it can also produce geometric designs, +dingbats, etc. And it has considerable mathematical and +equation-solving capabilities which can be useful entirely on their own. + +Metafont is a batch language, like C or Pascal: you compile a Metafont +program into a corresponding font, rather than interactively drawing +lines or curves. This approach has both considerable disadvantages +(people unfamiliar with conventional programming languages will be +unlikely to find it usable) and considerable advantages (you can make +your design intentions specific and parameterizable). For a complete +description of the Metafont language, see @cite{The METAFONTbook} +(@pxref{References}). + +@menu +* mf invocation:: Invoking Metafont. +* Initial Metafont:: Making bases. +* Modes:: Device definitions for Metafont. +* Online Metafont graphics:: Seeing MF output online. +* gftodvi invocation:: Making proofsheets for fonts. +* mft invocation:: Prettyprinting Metafont sources. +@end menu + + +@node mf invocation +@section @code{mf} invocation + +@pindex mf +@cindex Metafont invocation + +Metafont (usually invoked as @code{mf}) reads character definitions +specified in the Metafont programming language, and outputs the +corresponding font. This section merely describes the options available +in the Web2c implementation. For a complete description of the Metafont +language, see @cite{The Metafontbook} (@pxref{References}). + +Metafont processes its command line and determines its memory dump +(base) file in a way exactly analogous to MetaPost and @TeX{} +(@pxref{tex invocation}, and @pxref{Memory dumps}). Synopses: + +@example +mf [@var{option}]@dots{} [@var{mfname}[.mf]] [@var{mf-commands}] +mf [@var{option}]@dots{} \@var{first-line} +mf [@var{option}]@dots{} &@var{base} @var{args} +@end example + +Most commonly, a Metafont invocation looks like this: +@example +mf '\mode:=@var{mode}; mag:=@var{magnification}; input @var{mfname}' +@end example +@noindent +(The single quotes avoid unwanted interpretation by the shell.) + +@flindex .mf +@cindex Metafont input files +@cindex EC fonts +@pindex mktexmf@r{, disabling} +Metafont searches the usual places for the main input file @var{mfname} +(@pxref{Supported file formats,,, kpathsea, Kpathsea}), extending +@var{mfname} with @file{.mf} if necessary. To see all the relevant +paths, set the environment variable @code{KPATHSEA_DEBUG} to @samp{-1} +before running the program. By default, Metafont runs an external +program named @file{mktexmf} to create any nonexistent Metafont source +files you input. You can disable this at configure-time or runtime +(@pxref{mktex configuration,,, kpathsea, Kpathsea}). This is mostly +for the sake of the EC fonts, which can be generated at any size. + +@flindex .@var{nnn}gf @r{generic fonts} +@flindex mfput +@cindex GF output +@cindex GF files, output by Metafont +@cindex PK files, not output by Metafont +Metafont writes the main GF output to the file +@file{@var{basemfname}.@var{nnn}gf}, where @var{nnn} is the font +resolution in pixels per inch, and @var{basemfname} is the basename of +@var{mfname}, or @samp{mfput} if no input file was specified. A GF file +contains bitmaps of the actual character shapes. Usually GF files are +converted immediately to PK files with GFtoPK (@pxref{gftopk +invocation}), since PK files contain equivalent information, but are +more compact. (Metafont output in GF format rather than PK for only +historical reasons.) + +@flindex .tfm @r{output} +@cindex TFM files, output by Metafont +Metafont also usually writes a metric file in TFM format to +@file{@var{basemfname}.tfm}. A TFM file contains character dimensions, +kerns, and ligatures, and spacing parameters. @TeX{} reads only this +@t{.tfm} file, not the GF file. + +@cindex mode needed to run Metafont +@findex proof @r{mode} +@flindex 2602gf +@flindex .2602gf +The @var{mode} in the example command above is a name referring to a +device definition (@pxref{Modes}); for example, @code{localfont} or +@code{ljfour}. These device definitions must generally be precompiled +into the base file. If you leave this out, the default is @code{proof} +mode, as stated in @cite{The Metafontbook}, in which Metafont outputs at +a resolution of 2602@dmn{dpi}; this is usually not what you want. The +remedy is simply to assign a different mode---@code{localfont}, for +example. + +The @var{magnification} assignment in the example command above is a +magnification factor; for example, if the device is 600@dmn{dpi} and you +specify @code{mag:=2}, Metafont will produce output at 1200@dmn{dpi}. +Very often, the @var{magnification} is an expression such as +@code{magstep(.5)}, corresponding to a @TeX{} ``magstep'', which are +factors of +@tex +1.2$\sqrt{2}$. +@end tex +@ifinfo +1.2 * sqrt(2). +@end ifinfo + +After running Metafont, you can use the font in a @TeX{} document as +usual. For example: +@example +\font\myfont = newfont +\myfont Now I am typesetting in my new font (minimum hamburgers). +@end example + +The program accepts the following options, as well as the standard +@samp{-help} and @samp{-version} (@pxref{Common options}): +@table @samp +@item -[no]-file-line-error +@itemx -fmt=@var{fmtname} +@itemx -halt-on-error +@itemx -ini +@itemx -interaction=@var{string} +@itemx -jobname=@var{string} +@itemx -kpathsea-debug=@var{number} +@itemx -[no]parse-first-line +@itemx -output-directory +@itemx -progname=@var{string} +@itemx -recorder +@itemx -translate-file=@var{tcxfile} +@itemx -8bit +These options are common to @TeX{}, Metafont, and MetaPost. +@xref{Common options}. + +@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 value that makes sense for @var{filetype} is @samp{mf}. +@end table + + +@node Initial Metafont +@section Initial Metafont + +@cindex initial Metafont +@cindex Metafont, initial + +@flindex .base +@cindex base files +@code{inimf} is the ``initial'' form of Metafont, which does lengthy +initializations avoided by the ``virgin'' (@code{vir}) form, so as to +be capable of dumping @samp{.base} files (@pxref{Memory dumps}). For +a detailed comparison of virgin and initial forms, see @ref{Initial +and virgin}. + +For a list of options and other information, see @ref{mf invocation}. + +@flindex plain.base +@flindex mf.base +The only memory dump file commonly used with Metafont is the default +@samp{plain.base}, also known as @samp{mf.base} (again, @pxref{Memory +dumps}). It is created by default during installation, but you can also +do so by hand if necessary (e.g., if a Metafont update is issued): +@example +mf -ini '\input plain; input modes; dump' +@end example +@noindent +(The quotes prevent interpretation of the backslashes from the shell.) +Then install the resulting @file{plain.base} in @samp{$(basedir)} +(@file{/usr/local/share/texmf/web2c} by default), and link +@file{mf.base} to it. + +For an explanation of the additional @file{modes.mf} file, +see @ref{Modes}. This file has no counterpart in @TeX{} or MetaPost. + +@flindex cmmf.base @r{not recommended} +@flindex cm.base +@flindex cmbase.mf +@cindex Computer Modern macros +@cindex base files, plain only +In the past, it was sometimes useful to create a base file +@file{cmmf.base} (a.k.a.@: @file{cm.base}), with the Computer Modern +macros also included in the base file. Nowadays, however, the +additional time required to read @file{cmbase.mf} is exceedingly small, +usually not enough to be worth the administrative hassle of updating the +@file{cmmf.base} file when you install a new version of @file{modes.mf}. +@cindex type design, personal +People actually working on a typeface may still find it worthwhile to +create their own base file, of course. + + +@node Modes +@section Modes: Device definitions for Metafont + +@cindex modes file needed for Metafont +@cindex base files, need mode definitions +@cindex device definitions, for Metafont +@cindex printer characteristics, for Metafont +Running Metafont and creating Metafont base files requires information +that @TeX{} and MetaPost do not: @dfn{mode} definitions which specify +device characteristics, so Metafont can properly rasterize the shapes. + +@flindex modes.mf @r{recommended modes file} +When making a base file, a file containing modes for locally-available +devices should be input after @file{plain.mf}. One commonly used file +is @url{ftp://ftp.tug.org/tex/modes.mf}; it includes all known +definitions. + +@cindex small Metafont memory and modes +@findex mode_def +@findex mode_setup +If, however, for some reason you have decreased the memory available in +your Metafont, you may need to copy @file{modes.mf} and remove the +definitions irrelevant to you (probably most of them) instead of using +it directly. (Or, if you're a Metafont hacker, maybe you can suggest a +way to redefine @code{mode_def} and/or @code{mode_setup}; right now, the +amount of memory used is approximately four times the total length of +the @code{mode_def} names, and that's a lot.) + +If you have a device not included in @file{modes.mf}, please see +comments in that file for how to create the new definition, and please +send the definition to @email{tex-fonts@@math.utah.edu} to get it included +in the next release of @file{modes.mf}. + +@findex smode @r{and dynamic Metafont mode definition} +@cindex dynamic Metafont mode definitions with @code{smode} +Usually, when you run Metafont you must supply the name of a mode that +was dumped in the base file. But you can also define the mode +characteristics dynamically, by invoking Metafont with an assignment to +@code{smode} instead of @code{mode}, like this: +@example +mf '\smode:="newmode.mf"; mag:=@var{magnification}; input @var{mfname}' +@end example +@noindent +This is most useful when you are working on the definition of a new +mode. + +The @var{magnification} and @var{mfname} arguments are explained in +@ref{mf invocation}. In the file @file{newmode.mf}, you should have the +following (with no @code{mode_def} or @code{enddef}), if you are using +@file{modes.mf} conventions: +@example +mode_param (pixels_per_inch, @var{dpi}); +mode_param (blacker, @var{b}); +mode_param (fillin, @var{f}); +mode_param (o_correction, @var{o}); +mode_common_setup_; +@end example +@noindent +(Of course, you should use real numbers for @var{dpi}, @var{b}, @var{f}, +and @var{o}.) + +For more information on the use of @code{smode}, or if you are not using +@file{modes.mf}, see page 269 of @cite{The Metafontbook}. + + +@node Online Metafont graphics +@section Online Metafont graphics + +@cindex online Metafont graphics +@cindex Metafont graphics + +The Web2c implementation of Metafont can do online graphics with a +number of devices. (See the Metafont manual for more information about +how to draw on your screen.) By default, no graphics support is +enabled. + +@vindex MFTERM +@vindex TERM +Metafont examines the @code{MFTERM} environment variable or config file +value at runtime, or the @code{TERM} environment variable if +@code{MFTERM} is not set, to determine the device support to use. +Naturally, only the devices for which support has been compiled in can +be selected. + +Here is a table of the possibilities, showing the @code{MFTERM} value +and the corresponding @code{configure} option(s) in parentheses. + +@vtable @code +@item epsf +@cindex Herberts, Mathias +@opindex --enable-epsfwin +(@samp{--enable-epsfwin}) Pseudo-window server for Encapsulated +PostScript (see @file{web2c/window/epsf.c}). This device produces an +EPS file containing the graphics which would be displayed online on +other devices. The name of the EPS file defaults to metafont.eps but +can be changed by setting the MFEPSF environment variable to the new +filename. Contributed by Mathias Herberts. + +@item hp2627 +@opindex --enable-hp2627win +(@samp{--enable-hp2627win}) HP2627a color graphics terminals. + +@item mftalk +@opindex --enable-mftalkwin +(@samp{--enable-mftalkwin}) Generic window server (see +@file{web2c/window/mftalk.c}). + +@item next +@pindex DrawingServant +@opindex --enable-next +(@samp{--enable-next}) NeXT window system. This requires a separate +program, called @code{DrawingServant}, available separately. See the +@file{web2c/window/next.c}. + +@item regis +@opindex --enable-regiswin +@cindex Regis graphics support +(@samp{--enable-regiswin}) Regis terminals. + +@item sun +@cindex SunView +@cindex Suntools +@opindex --enable-suntoolswin +@flindex sun-gfx.c +(@samp{--enable-suntoolswin}) The old Suntools (not any flavor of X) +window system. (You can get the even older SunWindows @code{gfx} system +by using @file{sun-gfx.c}.) + +@item tek +@cindex Tektronix +@opindex --enable-tektronixwin +(@samp{--enable-tektronixwin}) Tektronix terminals. + +@cindex Poole, Simon +@item uniterm +@cindex Tektronix 4014 +@opindex --enable-unitermwin +(@samp{--enable-unitermwin}) Uniterm, Simon Poole's emulator of a smart +Tektronix 4014 terminal. This may work with regular Tektronix terminals +as well; it's faster than the driver @samp{--enable-tektronixwin} selects. + +@vindex NO_X11WIN +@pindex Xt +@pindex Xlib +@item xterm +@opindex --with-x +@samp{--with-x} The X window system (version 11). + +@opindex --with-mf-x-toolkit=@var{kit} +@cindex toolkits, X +@cindex X toolkits and Metafont +@cindex Xt support +@cindex Xlib support +There are two variants of the X11 support, one that works with the Xt +toolkit, and another that works directly with Xlib. The Xt support is +more efficient and has more functionality, so it is the default. If you +must use the Xlib support, use @samp{configure --with-x +--with-kf-x-toolkit=no}. + +@opindex --disable-mf-nowin +@cindex non-windows-capable Metafont +Specify @samp{--disable-mf-nowin} in order not to build a separate +non-windows-capable Metafont executable @code{mf-nowin} (or +@code{mf-nowin.exe}). + +@cindex X resources +@cindex X class name for Metafont +@cindex class name for Metafont +@cindex geometry for Metafont +@cindex Metafont geometry +@flindex .Xdefaults +@flindex .Xresources +@opindex -geometry@r{, supported with Xt} +You cannot specify any of the usual X options (e.g., @samp{-geometry}) +on the Metafont command line, but you can specify X resources in your +@file{~/.Xdefaults} or @file{~/.Xresources} file. The class name is +@code{Metafont}. If you're using the Xt support, all the usual X toolkit +resources are supported. If you're using the Xlib support, only the +@code{geometry} resource is supported. + +@vindex DISPLAY +You specify the X display to which Metafont connects in the +@code{DISPLAY} environment variable, as usual. + +@end vtable + +@cindex Metafont online support, new devices +@cindex new graphics support for Metafont +@flindex texmfmp.c +Writing support for a new device is straightforward. Aside from defining +the basic drawing routines that Metafont uses (see @file{mf.web}), you +only have to add another entry to the tables on the last page of +@file{web2c/lib/texmfmp.c}. Or you can write an independent program and +use MFtalk (see @file{web2c/window/mftalk.c}). + + +@node gftodvi invocation +@section GFtoDVI: Character proofs of fonts + +@pindex gftodvi +@cindex character proofs of fonts +@cindex font proofs +@cindex proof sheets, of fonts + +GFtoDVI makes @dfn{proof sheets} from a GF bitmap file as output by, for +example, Metafont (@pxref{Metafont}). This is an indispensable aid for +font designers or Metafont hackers. Synopsis: + +@example +gftodvi [@var{option}]@dots{} @var{gfname}[gf] +@end example + +The font @var{gfname} is searched for in the usual places (@pxref{Glyph +lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the +environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running +the program. + +The suffix @samp{gf} is supplied if not already present. This suffix is +not an extension, no @samp{.} precedes it; for instance, @file{cmr10.600gf}. + +The output filename is the basename of @var{gfname} extended with +@file{.dvi}, e.g., @samp{gftodvi /wherever/foo.600gf} creates +@file{./foo.dvi}. + +The characters from @var{gfname} appear one per page in the DVI output, +with labels, titles, and annotations, as specified in Appendix H +(Hardcopy Proofs) of @cite{The Metafontbook}. + +GFtoDVI uses several fonts besides @var{gfname} itself: + +@itemize @bullet +@item +@cindex gray font +@dfn{gray font} (default @file{gray}): for the pixels that actually make +up the character. Simply using black is not right, since then labels, +key points, and other information could not be shown. + +@item +@cindex title font +@dfn{title font} (default @file{cmr8}): for the header information at +the top of each output page. + +@item +@cindex label font +@dfn{label font} (default @file{cmtt10}): for the labels on key points +of the figure. + +@item +@cindex slant font +@dfn{slant font} (no default): for diagonal lines, which are otherwise +simulated using horizontal and vertical rules. +@end itemize + +To change the default fonts, you must use @code{special} commands in +your Metafont source file, typically via commands like @code{slantfont +slantlj4}. There is no default slant font since no one printer is +suitable as a default. You can make your own by copying one of the +existing files, such as +@file{.../fonts/source/public/misc/slantlj4.mf} and then running +@command{mf} on it. + +For testing purposes, you may it useful to run @code{mf-nowin rtest} +(hit RETURN when it stops) to get a @file{gf} file of a thorn glyph. +Or use @command{mf} instead of @command{mf-nowin} to have the glyph(s) +displayed on the screen. After that, @code{gftodvi rtest.2602gf} +should produce @file{rtest.dvi}, which you process as usual. + +The program accepts the following option, as well as the standard +@samp{-verbose}, @samp{-help}, and @samp{-version} (@pxref{Common +options}): + +@table @samp +@item -overflow-label-offset=@var{points} +@opindex -overflow-label-offset=@var{points} +@cindex overflow label offset +@cindex offset for overflow labels +Typeset the so-called overflow labels, if any, @var{points} @TeX{} +points from the right edge of the character bounding box. The default +is a little over two inches (ten million scaled points, to be precise). +Overflow equations are used to locate coordinates when their actual +position is too crowded with other information. +@end table + + +@node mft invocation +@section MFT: Prettyprinting Metafont source + +@pindex mft +@cindex Metafont source, prettyprinting +@cindex prettyprinting Metafont source +@cindex @TeX{}, creating from Metafont + +@flindex mftmac.tex +MFT translates a Metafont program into a @TeX{} document suitable for +typesetting, with the aid of @TeX{} macros defined in the file +@file{mftmac.tex}. Synopsis: + +@example +mft [@var{option}]@dots{} @var{mfname}[.mf] +@end example + +MFT searches the usual places for @var{mfname} (@pxref{Supported file +formats,,, kpathsea, Kpathsea}). To see all the relevant paths, set the +environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running +the program. The output goes to the basename of @var{mfname} extended +with @file{.tex}, e.g., @samp{mft /wherever/foo.mf} creates +@file{./foo.tex}. + +Line breaks in the input are carried over into the output; moreover, +blank spaces at the beginning of a line are converted to quads of +indentation in the output. Thus, you have full control over the +indentation and line breaks. Each line of input is translated +independently of the others. + +Further control is allowed via Metafont comments: +@cindex comments, MFT control +@itemize @bullet +@item +Metafont comments following a single @samp{%} should be valid @TeX{} +input. But Metafont material can be included within vertical bars in a +comment; this will be translated by MFT as if it were regular Metafont +code. For example, a comment like @samp{% |x2r| is the tip of the bowl} +will be translated into the @TeX{} @samp{% $x_@{2r@}$ is the @dots{}}, +i.e., the @samp{x2r} is treated as an identifier. + +@item +@samp{%%} indicates that the remainder of an input line should be copied +verbatim to the output. This is typically used to introduce additional +@TeX{} material at the beginning or an MFT job, e.g. code to modify the +standard layout or the formatting macros defined in @file{mftmac.tex}, +or to add a line saying @samp{%%\bye} at the end of the job. (MFT +doesn't add this automatically in order to allow processing several +files produces by MFT in the same @TeX{} job.) + +@item +@samp{%%% @var{token1} @var{other-tokens}} +introduces a change in MFT's formatting rules; all the @var{other-tokens} +will henceforth be translated according to the current conventions for +@var{token1}. The tokens must be symbolic (i.e., not +numeric or string tokens). For example, the input line +@example +%%% addto fill draw filldraw +@end example +@noindent +says to format the @samp{fill}, @samp{draw}, and @samp{filldraw} +operations of plain Metafont just like the primitive token @samp{addto}, +i.e., in boldface type. Without such reformatting commands, MFT would +treat @samp{fill} like an ordinary tag or variable name. In fact, you +need a @samp{%%%} command even to get parentheses to act like +delimiters. + +@item +@samp{%%%%} introduces an MFT comment, i.e., MFT ignores the remainder +of such a line. + +@item +Five or more @samp{%} signs should not be used. +@end itemize + +@cindex Knuth, Donald E. +(The above description was edited from @file{mft.web}, written by +@w{D.E. Knuth}.) + +The program accepts the following options, as well as the standard +@samp{-help} and @samp{-version} (@pxref{Common options}): +@table @samp +@item -change=@var{chfile}[.ch] +@opindex -change=@var{chfile} +@cindex change files, and MFT +Apply the change file @var{chfile} as with Tangle and Weave +(@pxref{WEB}). + +@item -style=@var{mftfile}[.mft] +@opindex -style=@var{mftfile} +@cindex style files +@flindex plain.mft +Read @var{mftfile} before anything else; a MFT style file typically +contains only MFT directives as described above. The default style file +is named @file{plain.mft}, which defines this properly for programs +using plain Metafont. The MFT files is searched along the +@code{MFTINPUTS} path; see @ref{Supported file formats,,, kpathsea, Kpathsea}. + +@flindex cmbase.mft +@flindex e.mft +@cindex @cite{Computer Modern Typefaces}, production of +Other examples of MFT style files are @file{cmbase.mft}, which defines +formatting rules for the macros defined in @file{cm.base}, and +@file{e.mft}, which was used in the production of Knuth's Volume@w{ }E, +@cite{Computer Modern Typefaces}. + +@cindex MetaPost source, prettyprinting +Using an appropriate MFT style file, it is also possible to configure +MFT for typesetting MetaPost sources. However, MFT does not search +the usual places for MetaPost input files. +@end table + +If you use eight-bit characters in the input file, they are +passed on verbatim to the @TeX{} output file; it is up to you to +configure @TeX{} to print these properly. + + +@node MetaPost +@chapter MetaPost: Generating PostScript + +@cindex MetaPost +@cindex PostScript meets Metafont +@cindex Metafont meets PostScript +@cindex technical illustrations, creating +MetaPost is a picture-drawing language similar to Metafont +(@pxref{Metafont}), but instead of outputting bitmaps in a ``font'', it +outputs PostScript commands. It's primarily intended for creating +technical illustrations, but can also be used to create PostScript or +OpenType fonts (@url{https://ctan.org/pkg/metatype1}). + +@pindex troff@r{, supported in MetaPost} +MetaPost also provides for arbitrary integration of text and graphics in +a natural way, using any typesetter (@TeX{} and Troff are both +supported) and a number of other subsidiary programs, described below. + +@menu +* mpost invocation:: Invoking MetaPost. +* Initial MetaPost:: Making mems. +* dvitomp invocation:: DVI-to-MPX translation. +@end menu + + +@node mpost invocation +@section @code{mpost} invocation + +@pindex mpost +@cindex MetaPost invocation + +@flindex mpman.pdf +MetaPost (installed as @code{mpost}) reads a series of pictures +specified in the MetaPost programming language, and outputs +corresponding PostScript code. This section merely describes the +options available in the Web2c implementation. For a complete +description of the MetaPost language, see AT&T technical report +CSTR-162, generally available in @file{@var{texmf}/doc/metapost/}, +where @var{texmf} is the root of @TeX{} directory structure. +The MetaPost home page: @url{https://tug.org/metapost}. + +@flindex mpgraph.pdf +Also, a standard MetaPost package for drawing graphs is documented in +AT&T technical report CSTR-164, available as the file @file{mpgraph.ps}, +generally stored alongside @file{mpman.ps}. + +MetaPost processes its command line and determines its memory dump +(mem) file in a way analogous to Metafont and @TeX{} (@pxref{tex +invocation,,@code{tex} invocation}, and @pxref{Memory dumps}). +Synopses: + +@example +mpost [@var{option}]@dots{} [@var{mpname}[.mp]] [@var{mp-commands}] +mpost [@var{option}]@dots{} \@var{first-line} +mpost [@var{option}]@dots{} &@var{mem} @var{args} +@end example + +@flindex .mp +@cindex MetaPost input files +MetaPost searches the usual places for the main input file @var{mpname} +(@pxref{Supported file formats,,, kpathsea, Kpathsea}), extending +@var{mpname} with @file{.mp} if necessary. To see all the relevant +paths, set the environment variable @code{KPATHSEA_DEBUG} to @samp{-1} +before running the program. + +@findex beginfig +@flindex .@var{nnn} @r{PostScript figures} +@flindex .tfm @r{output} +@flindex mpout +@cindex TFM files, output by MetaPost +@cindex PostScript output +MetaPost writes its PostScript output to a series of files +@file{@var{basempname}.@var{nnn}} (or perhaps +@file{@var{basempname}.ps}, very occasionally +@file{@var{basempname}.tfm}), where @var{nnn} are the figure numbers +specified in the input, typically to the @code{beginfig} macro, and +@var{basempname} is the basename of @var{mpname}, or @samp{mpout} if no +input file was specified. MetaPost uses the @samp{.ps} extension when +the figure number is out of range, e.g., if you say @code{beginfig(-1)}. + +You can use the output files as figures in a @TeX{} document just as +with any other PostScript figures. For example, with this @TeX{} command: +@example +\special@{psfile="@var{filename}"@} +@end example +@noindent +or by using @file{epsf.tex} (@pxref{EPSF macros,,, dvips, Dvips}). + +@findex btex @r{for MetaPost labels} +@findex etex @r{for MetaPost labels} +The MetaPost construct +@example +btex @dots{} @var{tex-input} @dots{} etex +@end example +@noindent +generates a MetaPost picture expression corresponding to +@var{tex-input}. + +The construct +@example +verbatimtex @dots{} @var{tex-input} @dots{} etex +@end example +@noindent +simply passes the @var{tex-input} through to +@TeX{}. For example, if you are using @LaTeX{}, your MetaPost input file +must start with a @code{verbatimtex} block that gives the necessary +@code{\documentclass} (or @code{\documentstyle}) +@code{\begin@{document@}} command. You will also need to set the +enviroment variable @code{TEX} to @samp{latex}. + +@var{tex-input} need not be specifically @TeX{} input; it could also be +Troff. In that case, you will need the @samp{-m pictures} Troff macro +package (unfortunately absent from many Troff implementations), or an +equivalent such as the @samp{-m pspic} macros from GNU groff described +in grops(1). + +@cindex PostScript fonts, and Troff +@cindex Troff, and MetaPost +@cindex Computer Modern fonts, and Troff +Naturally, you must use fonts that are supported by the typesetter; +specifically, you'll probably want to use standard PostScript fonts with +Troff. And only the @TeX{} system understands Computer Modern or other +Metafont fonts; you can also use PostScript fonts with @TeX{}, of course. + +@flindex mproof.tex +@cindex downloading of fonts for MetaPost labels +@cindex font downloading for MetaPost labels +MetaPost-generated PostScript figures which do use Computer Modern fonts +for labels cannot be directly previewed or printed. Instead, you must +include them in a @TeX{} document and run the resulting DVI file through +Dvips to arrange for the downloading of the required fonts (@pxref{Fonts +in figures,,, dvips, Dvips}). To help with this, the MetaPost +distribution provides a small @TeX{} file @file{mproof.tex} which is +typically called as: +@example +tex mproof @var{mp-output-files}... ; dvips mproof -o +@end example +@noindent +The resulting file @file{mproof.ps} can then be printed or previewed. + +@vindex prologues@r{, and EPSF output} +@flindex psfonts.map@r{, read by MetaPost} +To generate EPSF files, set the internal MetaPost variable +@code{prologues} positive. To make the output files self-contained, use +only standard PostScript fonts. MetaPost reads the same +@file{psfonts.map} file as Dvips, to determine PostScript fonts that +need to be downloaded (@pxref{psfonts.map,,, dvips, Dvips}). + +@cindex PDF, and @code{.mps} files +@cindex @code{.mps} files and PDF +It is posible for pdf@TeX{} to read MetaPost output directly; this is +in contrast to general EPSF files, which have to be converted for use +with PDF output. The easiest way is to name the MetaPost output files +with the @code{.mps} extension. Then the @LaTeX{} +@code{\includegraphics} command, for example, will be able to read +them, even when outputting PDF. + +@cindex security, and @code{write} +MetaPost can write output files, via the @code{write} primitive; this +opens a security hole. @xref{tex invocation}. + +The program accepts the following options, as well as the standard +@samp{-help} and @samp{-version} (@pxref{Common options}): +@table @samp +@item -[no]-file-line-error +@itemx -fmt=@var{fmtname} +@itemx -halt-on-error +@itemx -ini +@itemx -interaction=@var{string} +@itemx -jobname=@var{string} +@itemx -kpathsea-debug=@var{number} +@itemx -[no]parse-first-line +@itemx -output-directory +@itemx -progname=@var{string} +@itemx -recorder +@itemx -translate-file=@var{tcxfile} +@itemx -8bit +These options are common to @TeX{}, Metafont, and MetaPost. +@xref{Common options}. + +@item -T +@itemx -troff +@opindex -T +@opindex -troff +@vindex prologues +Set the @code{prologues} internal variable to @code{1}. + +@item -tex=@var{texprogram} +@opindex -tex=@var{texprogram} +When this option is given, the program @var{texprogram} is used to +typeset the labels. + +@end table + + +@node Initial MetaPost +@section Initial MetaPost + +@cindex initial MetaPost +@cindex MetaPost, initial + +As of MetaPost 1.504 (@TeX{} Live 2011), MetaPost no longer dumps +@file{.mem} files (@pxref{Memory dumps}) and does not distinguish +virgin and initial forms (@pxref{Initial and virgin}). Instead, the +``initial'' file name is read in its source form---that is, +@file{mpost.mp} when the program is invoked as @command{mpost}. + +For a list of options and other information, see @ref{mpost invocation}. + +@cindex Metafont, compatibility in MetaPost +@cindex plain Metafont, compatibility in MetaPost +@cindex MetaPost and plain Metafont compatibility +@flindex mfplain +MetaPost provides a format with all the features of plain Metafont, +called @file{mfplain}. You can use that in the same way; just run +@command{mfplain} instead of @command{mpost}. This lets you directly +process Metafont source files with MetaPost, producing character +proofs (one file for each character) similar to those produced with +Metafont in proof mode and GFtoDVI (@pxref{gftodvi invocation}). + + +@node dvitomp invocation +@section DVItoMP: DVI to MPX conversion + +@pindex dvitomp +@cindex DVI files, converting to MPX +@cindex MPX files, converting from DVI files + +DVItoMP converts DVI files into low-level MetaPost commands in a +so-called MPX file. Synopsis: + +@example +dvitomp @var{dvifile}[.dvi] [@var{mpxfile}[.mpx]] +@end example + +@noindent +If @var{mpxfile} is not specified, the output goes to the basename of +@var{dvifile} extended with @file{.mpx}, e.g., @samp{dvitomp +/wherever/foo.dvi} creates @file{./foo.mpx}. + +@cindex color, in DVItoMP +DVItoMP supports Dvips-style color specials, such as @samp{color push +@var{name}} and @samp{color pop}, outputting them as @code{withcolor} +MetaPost commands. + +The only options are @samp{-help} and @samp{-version} (@pxref{Common +options}). + + +@node BibTeX +@chapter Bib@TeX{}: Bibliographies + +@cindex bibliographies, creating +@cindex Bib@TeX{} + +Bib@TeX{} automates much of the job of typesetting bibliographies, and +makes bibliography entries reusable in many different contexts. + +@menu +* bibtex invocation:: +* Basic BibTeX style files:: The standard and semi-standard styles. +@end menu + + +@node bibtex invocation +@section Bib@TeX{} invocation + +@pindex bibtex + +@flindex .bbl @r{bibliography files} +@flindex .aux @r{cross-reference files} +@flindex .bib @r{bibliography databases} +Bib@TeX{} creates a printable bibliography (@file{.bbl}) file from +references in a @file{.aux} file, generally written by @TeX{} or +@LaTeX{}. The @file{.bbl} file is then incorporated on a subsequent +run. The basic bibliographic information comes from @file{.bib} files, +and a Bib@TeX{} style (@file{.bst}) file controls the precise contents +of the @file{.bbl} file. Synopsis: + +@example +bibtex [@var{option}]@dots{} @var{auxfile}[.aux] +@end example + +@flindex .blg @r{Bib@TeX{} log file} +@cindex log file, Bib@TeX{} +@noindent +The output goes to the basename of @var{auxfile} extended with +@file{.bbl}; for example, @samp{bibtex /wherever/foo.aux} creates +@file{./foo.bbl}. Bib@TeX{} also writes a log file to the basename of +@var{auxfile} extended with @samp{.blg}. + +@findex \bibliography +@findex \bibliographystyle +@vindex TEXBIB@r{, search path for bib files} +@vindex BIBINPUTS@r{, search path for bib files} +@vindex BSTINPUTS@r{, search path for bst files} +The names of the @file{.bib} and @file{.bst} files are specified in the +@file{.aux} file as well, via the @file{\bibliography} and +@file{\bibliographystyle} (La)@TeX{} macros. Bib@TeX{} searches for +@file{.bib} files using the @code{BIBINPUTS} and @code{TEXBIB} paths, +and for @file{.bst} files using @code{BSTINPUTS} (@pxref{Supported file +formats,,,kpathsea,Kpathsea}). It does no path searching for +@file{.aux} files. + +The program accepts the following options, as well as the standard +@samp{-help} and @samp{-version} (@pxref{Common options}): +@table @samp +@item -terse +@opindex -terse +@cindex terse output +@cindex verbose Bib@TeX{} output, suppressing +Suppress the program banner and progress reports normally output. + +@item -min-crossrefs=@var{n} +@opindex -min-crossrefs=@var{n} +@cindex cross-referenced bibliography items +@cindex bibliography items, cross-referenced +If at least @var{n} (2 by default) bibliography entries refer to another +entry @var{e} via their @code{crossref} field, include @var{e} in the +@t{.bbl} file, even if it was not explicitly referenced in the @t{.aux} +file. For example, @var{e} might be a conference proceedings as a whole, +with the cross-referencing entries being individual articles published +in the proceedings. + +If you want to avoid these automatic inclusions altogether, make +@var{n} a sufficiently large number, and be sure to remove any +previous @t{.aux} and @t{.bbl} files. Otherwise the option may +appear to have no effect, since Bib@TeX{} will have added the citation +for @var{e} to the @t{.aux}, and nothing will remove it. + +@end table + +See also: +@table @file +@item btxdoc.tex +@flindex btxdoc.tex +Basic @LaTeX{}able documentation for general Bib@TeX{} users. + +@item btxhak.tex +@flindex btxhak.tex +@cindex style design, for Bib@TeX{} +@LaTeX{}able documentation for style designers. + +@item btxdoc.bib +@flindex btxdoc.bib +Bib@TeX{} database file for the two above documents. + +@item xampl.bib +@flindex xampl.bib +Example database file with all the standard entry types. + +@item @url{ftp://ftp.math.utah.edu/pub/tex/bib/} +@flindex ftp.math.utah.edu +@cindex Bib@TeX{} collection +@cindex TUGboat bibliography +@cindex @TeX{}, bibliographies for +A very large @file{.bib} and @file{.bst} collection, including +references for all the standard @TeX{} books and a complete bibliography +for TUGboat. +@end table + + +@node Basic BibTeX style files +@section Basic Bib@TeX{} style files + +@cindex basic Bib@TeX{} style files +@cindex Bib@TeX{} style files + +Here are descriptions of the four standard and four semi-standard basic +Bib@TeX{} styles. @file{@var{CTAN:}/biblio/bibtex} contains these and +many more (for CTAN info, @pxref{unixtex.ftp,,, kpathsea, Kpathsea}). + +@table @code +@item plain +@flindex plain.bst +Sorts entries alphabetically, with numeric labels. Generally formatted +according to van Leunen's @cite{A Handbook for Scholars}. The other +style files listed here are based on @code{plain}. + +@item abbrv +@flindex abbrv.bst +First names, month names, and journal names are abbreviated. + +@item acm +@flindex acm.bst +Names are printed in small caps. + +@item alpha +@flindex alpha.bst +Alphanumeric labels, e.g., @samp{Knu66}. + +@item apalike +@flindex apalike.bst +No labels at all; instead, the year appears in parentheses after the author. +Use this in conjunction with @file{apalike.tex} (plain @TeX{}) or +@file{apalike.sty} (@LaTeX{}), which also changes the citations in the +text to be @samp{(@var{author}, @var{year})}. + +@item ieeetr +@flindex ieeetr.bst +Numeric labels, entries in citation order, @sc{ieee} abbreviations, +article titles in quotes. + +@item siam +@flindex siam.bst +Numeric labels, alphabetic order, @cite{Math.@: Reviews} +abbreviations, names in small caps. + +@item unsrt +@flindex unsrt.bst +Lists entries in citation order, i.e., unsorted. + +@item btxbst.doc +The template file and documentation for the standard styles. + +@end table + + +@node WEB +@chapter WEB: Literate programming + +@cindex WEB +@cindex literate programming + +@dfn{WEB} languages allow you to write a single source file that can +produce both a compilable program and a well-formatted document +describing the program in as much detail as you wish to prepare. +Writing in this kind of dual-purpose language is called @dfn{literate +programming}. (The Usenet newsgroup @file{comp.programming.literate} +is devoted to this subject.) + +@flindex webman.tex +@cindex Spiderweb +@cindex Cweb +@cindex CWEB +@cindex Awk, WEB for +@cindex Ada, WEB for +@cindex Troff, WEB for +WEB-like languages have been implemented with many pairs of base +languages: Cweb provides C and Troff (@pxref{References}); CWEB provides +C and @TeX{} (@file{@var{CTAN:}/web/c_cpp/cweb}); Spiderweb provides C, +C++, Awk, Ada, many others, and @TeX{} +(@file{@var{CTAN:}/web/spiderweb}); and, of course, the original WEB +provides Pascal and @TeX{}, the implementation languages for the +original @TeX{}, Metafont, MetaPost, and related programs to come from +the @TeX{} project at Stanford. + +The original WEB language is documented in the file @file{webman.tex}, +which is included in the @url{ftp://ftp.tug.org/tex/lib.tar.gz} archive +(and available in many other places, of course). + +@menu +* tangle invocation:: +* weave invocation:: +* pooltype invocation:: +@end menu + + +@node tangle invocation +@section Tangle: Translate WEB to Pascal + +@pindex tangle +@cindex Pascal, creating from WEB +@cindex WEB programs, compiling + +Tangle creates a compilable Pascal program from a WEB source file +(@pxref{WEB}). Synopsis: + +@example +tangle [@var{option}]@dots{} @var{webfile}[.web] [@var{changefile}[.ch]] +@end example + +@cindex change files, and Tangle +@noindent +The Pascal output is written to the basename of @var{webfile} extended +with @samp{.p}; for example, @samp{tangle /wherever/foo.web} creates +@file{./foo.p}. Tangle applies @var{changefile} to @var{webfile} before +writing the output; by default, there is no change file. + +@cindex pool file, writing +@cindex string pool, writing +If the program makes use of the WEB string facility, Tangle writes the +string pool to the basename of @var{webfile} extended with @samp{.pool}. + +The Pascal output is packed into lines of 72 characters or less, with +the only concession to readability being the termination of lines at +semicolons when this can be done conveniently. + +The program accepts the following options, as well as the standard +@samp{--help} and @samp{--version} (@pxref{Common options}): + +@table @samp +@item -length=@var{number} +@opindex -length=@var{number} +@cindex identifier length +The number of characters that are considered significant in an +identifier. Whether underline characters are counted depends on the +@samp{-underline} option. The default value is 32, the original tangle +used 7, but this proved too restrictive for use by Web2c. + +@item -lowercase +@itemx -mixedcase +@itemx -uppercase +@opindex -lowercase +@opindex -mixedcase +@opindex -uppercase +@cindex identifier case +These options specify the case of identifiers in the output of tangle. +If @samp{-uppercase} (@samp{-lowercase}) is specified, tangle will +convert all identfiers to uppercase (lowercase). The default is +@samp{-mixedcase}, which specifies that the case will not be changed. + +@item -underline +@opindex -underline +@cindex identifiers with underlines +When this option is given, tangle does not strip underline characters +from identifiers. + +@item -loose +@itemx -strict +@opindex -loose +@opindex -strict +@cindex identifier collisions +These options specify how strict tangle must be when checking +identifiers for equality. The default is @samp{-loose}, which means +that tangle will follow the rules set by the case-smashing and underline +options above. If @samp{-strict} is set, then identifiers will always +be stripped of underlines and converted to uppercase before checking +whether they collide. + +@end table + +@node weave invocation +@section Weave: Translate WEB to @TeX{} + +@pindex weave +@cindex @TeX{}, creating from WEB +@cindex WEB programs, typesetting +@cindex prettyprinting WEB programs + +Weave creates a @TeX{} document from a WEB source file (@pxref{WEB}), +assuming various macros defined in @file{webmac.tex}. It takes care of +typographic details such as page layout, indentation, and italicizing +identifiers. It also automatically gathers and outputs extensive +cross-reference information. Synopsis: + +@example +weave [@var{option}]@dots{} @var{webfile}[.web] [@var{changefile}[.ch]] +@end example + +@cindex change files, and Weave +@noindent +The output is to the basename of @var{webfile} extended with +@samp{.tex}; for example, @samp{weave /wherever/foo.web} creates +@file{./foo.tex}. Weave applies @var{changefile} to @var{webfile} +before writing the output; by default, there is no change file. + +The program accepts the following option, as well as the standard +@samp{-verbose}, @samp{-help} and @samp{-version} (@pxref{Common +options}): +@table @samp +@item -x +@opindex -x +@cindex cross-references, omitting +@flindex CONTENTS.tex +@flindex webmac.tex +Omit the cross-reference information: the index, the list of WEB module +names, and the table of contents (an empty @file{CONTENTS.tex} file will +still be written when the Weave output file is processed by @TeX{} using +the default @file{webmac.tex}, though). +@end table + +Conventionally, WEB programmers should define the @TeX{} @code{\title} +macro at the beginning of the source file. Also, to get output of only +changed modules, one can say @code{\let\maybe=\iffalse} (usually as the +first change in the change file). + + +@node pooltype invocation +@section Pooltype: Display WEB pool files + +@pindex pooltype +@cindex type programs, pool +@cindex string numbers, displaying +@cindex WEB pool files, displaying + +Pooltype shows the so-called @dfn{string number} of each string in a WEB +pool file (@pxref{WEB}), as output by Tangle (@pxref{tangle +invocation}), including the first 256 strings corresponding to the +possible input characters. Pooltype primarily serves as an example of +WEB conventions to implementors of the @TeX{} system. Synopsis: + +@example +pooltype [@var{option}]@dots{} @var{poolfile}[.pool] +@end example + +@noindent +No path searching is done for @var{poolfile}. Output is to standard +output. + +The only options are @samp{--help} and @samp{--version} (@pxref{Common +options}). + +As an example of the output, here is the (edited) output for @file{tex.pool}: +@example +0: "^^@@" +1: "^^A" +@dots{} +255: "^^ff" +256: "pool size" +@dots{} +1314: "Using character substitution: " +(23617 characters in all.) +@end example + +@cindex representation of strings +@cindex string representation +In Metafont and MetaPost, the first 256 characters are actually +represented as single bytes (i.e., themselves), not in the @samp{^^} +notation. Consider Pooltype as showing the results after conversion for +output. + + +@node DVI utilities +@chapter DVI utilities + +@cindex DVI utilities + +@TeX{} outputs a file in @dfn{DVI} (DeVice Independent) format as a +compact representation of the original document. DVI files can be +translated to meet the requirements of a real physical device, such as +PostScript printers (@pxref{Top,, Introduction, dvips, Dvips}), PCL +printers (see dvilj(1)), and X displays (see xdvi(1)). In fact, DVI +translators are available for virtually all common devices: see +@file{@var{CTAN:}/dviware} (for CTAN info, @pxref{unixtex.ftp,,, +kpathsea, Kpathsea}). + +@flindex dvitype.web +@cindex DVI format definition +For the precise definition of the DVI file format, see (for example) the +source file @file{web2c/dvitype.web}. + +The DVI-processing programs in the Web2c distribution are not device +drivers; they perform generic utility functions. + +@menu +* dvicopy invocation:: Expand virtual fonts. +* dvitype invocation:: DVI to human-readable text. +@end menu + +@node dvicopy invocation +@section DVIcopy: Canonicalize virtual font references + +@pindex dvicopy +@cindex virtual fonts, expanding + +DVIcopy reads a DVI file, expands any references to virtual fonts +(@pxref{Virtual fonts,,, dvips, Dvips}) to base fonts, and writes the +resulting DVI file. Thus you can use virtual fonts even if your DVI +processor does not support them, by passing the documents through +DVIcopy first. Synopsis: + +@example +dvicopy [@var{option}]@dots{} [@var{indvi}[.dvi] [@var{outdvi}[.dvi]]] +@end example + +DVIcopy reads standard input if @var{indvi} is not specified, and writes +standard output if @var{outdvi} is not specified. + +The program accepts the following options, as well as the standard +@samp{-help} and @samp{-version} (@pxref{Common options}): +@table @samp +@item -magnification=@var{integer} +@opindex -magnification=@var{integer} +@cindex magnification +@findex \mag +Override existing magnification in @var{indvi} with @var{integer}; 1000 +specifies no magnification. This is equivalent to setting @TeX{}'s +@code{\mag} parameter. + +@item -max-pages=@var{n} +@opindex -max-pages=@var{n} +Process @var{n} pages; default is one million. + +@item -page-start=@var{page-spec} +@opindex -page-start=@var{page-spec} +@cindex starting page +@cindex page, starting +@findex \count@var{n} +Start at the first page matching @var{page-spec}, which is one or more +(signed) integers separated by periods, corresponding to @TeX{}'s +@code{\count0@dots{}9} parameters at @code{\shipout} time; @samp{*} +matches anything. Examples: @samp{3}, @samp{1.*.-4}. +@end table + + +@node dvitype invocation +@section DVItype: Plain text transliteration of DVI files + +@pindex dvitype @r{DVI validation} +@cindex conversion, DVI to plain text +@cindex plain text, converting DVI to +@cindex human-readable text, converting DVI to +@cindex type programs, DVI +@cindex validation, of DVI files + +DVItype translates a DeVice Independent (DVI) file (as output by @TeX{}, +for example) to a plain text file that humans can read. It also serves +as a DVI-validating program, i.e., if DVItype can read a file, it's +correct. Synopsis: + +@example +dvitype [@var{option}]@dots{} @var{dvifile}[.dvi] +@end example + +@noindent +DVItype does not read any bitmap files, but it does read TFM files for +fonts referenced in @var{dvifile}. The usual places are searched +(@pxref{Supported file formats,,, kpathsea, Kpathsea}). To see all the +relevant paths, set the environment variable @code{KPATHSEA_DEBUG} to +@samp{-1} before running the program. + +Output goes to standard output. + +The program accepts the following options, as well as the standard +@samp{-help} and @samp{-version} (@pxref{Common options}): +@table @samp +@item -dpi=@var{real} +@opindex -dpi=@var{real} +Do pixel movement calculations at @var{real} pixels per inch; default +300.0. + +@item -magnification=@var{integer} +@opindex -magnification=@var{integer} +@cindex magnification +@findex \mag +Override existing magnification in @var{indvi} with @var{integer}; 1000 +specifies no magnification. This is equivalent to setting @TeX{}'s +@code{\mag} parameter. + +@item -max-pages=@var{n} +@opindex -max-pages=@var{n} +Process @var{n} pages; default is one million. + +@item -output-level=@var{n} +@opindex -output-level=@var{n} +Verbosity level of output, from 0 to 4 (default 4): +@itemize @bullet +@item 0: Global document information only. +@item 1: Most DVI commands included, and typeset characters summarized. +@item 2: Character and movement commands explicitly included. +@item 3: DVI stack and current position calculations included. +@item 4: Same information as level 3, but DVItype does random positioning +in the file, reading the DVI postamble first. +@end itemize + +@item -page-start=@var{page-spec} +@opindex -page-start=@var{page-spec} +@cindex starting page +@cindex page, starting +@findex \count@var{n} +Start at the first page matching @var{page-spec}, which is one or more +(signed) integers separated by periods, corresponding to @TeX{}'s +@code{\count0@dots{}9} parameters at @code{\shipout} time; @samp{*} +matches anything. Examples: @samp{1}, @samp{5.*.-9}. + +@item -show-opcodes +@opindex -show-opcodes +@cindex opcodes, showing DVI +@cindex DVI opcodes, showing +@cindex debugging DVI utilities +Show numeric opcode values (in decimal) for DVI commands, in braces +after the command name. This can help in debugging DVI utilities. We +use decimal because in the DVI format documentation (in +@file{dvitype.web}, among others) the opcodes are shown in decimal. +@end table + +@menu +* dvitype output example:: +@end menu + + +@node dvitype output example +@subsection DVItype output example + +@cindex dvitype output example +As an example of the output from DVItype (see section above), here is +its (abridged) translation of the @file{story.dvi} resulting from +running the example in @cite{The @TeX{}book}, with +@samp{-output-level=4} and @samp{-show-opcodes} on. + +@example +@dots{} +Options selected: + Starting page = * + Maximum number of pages = 1000000 + Output level = 4 (the works) + Resolution = 300.00000000 pixels per inch +numerator/denominator=25400000/473628672 +magnification=1000; 0.00006334 pixels per DVI unit +' TeX output 1992.05.17:0844' +Postamble starts at byte 564. +maxv=43725786, maxh=30785863, maxstackdepth=3, totalpages=1 +Font 33: cmsl10---loaded at size 655360 DVI units +Font 23: cmbx10---loaded at size 655360 DVI units +Font 0: cmr10---loaded at size 655360 DVI units + +42: beginning of page 1 +87: push @{141@} +level 0:(h=0,v=0,w=0,x=0,y=0,z=0,hh=0,vv=0) +88: down3 -917504 @{159@} v:=0-917504=-917504, vv:=-58 +92: pop @{142@} +@dots{} +104: putrule @{137@} height 26214, width 30785863 (2x1950 pixels) +113: down3 5185936 @{159@} v:=655360+5185936=5841296, vv:=370 +117: push @{141@} +level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) +118: right4 12265425 @{146@} h:=0+12265425=12265425, hh:=777 +[ ] +123: fntdef1 23 @{243@}: cmbx10 +145: fntnum23 @{194@} current font is cmbx10 +146: setchar65 h:=12265425+569796=12835221, hh:=813 +147: w3 251220 @{150@} h:=12835221+251220=13086441, hh:=829 +151: setchar83 h:=13086441+418700=13505141, hh:=856 +@dots{} +164: setchar82 h:=17448202+565245=18013447, hh:=1142 +165: x0 -62805 @{152@} h:=18013447-62805=17950642, hh:=1138 +166: setchar89 h:=17950642+569796=18520438, hh:=1174 +[A SHORT STORY] +167: pop @{142@} +level 1:(h=0,v=5841296,w=0,x=0,y=0,z=0,hh=0,vv=370) +@dots{} +550: pop @{142@} +level 0:(h=0,v=42152922,w=0,x=0,y=0,z=0,hh=0,vv=2670) +551: down3 1572864 @{159@} v:=42152922+1572864=43725786, vv:=2770 +555: push @{141@} +level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) +556: right4 15229091 @{146@} h:=0+15229091=15229091, hh:=965 +561: setchar49 h:=15229091+327681=15556772, hh:=986 +[ 1] +562: pop @{142@} +level 0:(h=0,v=43725786,w=0,x=0,y=0,z=0,hh=0,vv=2770) +563: eop @{140@} +@end example + +Explanation: + +@itemize @bullet +@item +The DVItype options are recorded at the beginning, followed by +global information about the document, including fonts used. + +@item +Each DVI command is preceded by its byte position in the file +(@samp{42:}, @samp{87:}, @dots{}), and (because of the +@samp{-show-opcodes}) followed by its decimal opcode value in braces +(@samp{@{141@}}, @samp{@{142@}}, @dots{}). + +@item +The @samp{level} lines record information about the DVI stack; @samp{h} +and @samp{v} define the current position in DVI units, while @samp{hh} +and @samp{vv} are the same in pixels. + +@item +Text sequences are summarized in brackets, as in @samp{[A SHORT +STORY]} and the @samp{[ 1]}. +@end itemize + + +@node Font utilities +@chapter Font utilities + +@cindex font utilities + +The Web2c programs described here convert between various @TeX{}-related +font formats; the first section below briefly describes the +formats. GFtoPK is the only one that is routinely used, as Metafont +outputs GF format, but it's most efficient for device drivers to use PK. + +@flindex pktype.web +@flindex gftype.web +@cindex PK format definition +@cindex GF format definition +The precise definitions of the PK, GF, TFM, PL, VF, and VPL formats +mentioned below are in the source files that read them; +@file{pktype.web}, @file{gftype.web}, @file{tftopl.web}, etc. + +@menu +* Font file formats:: Explanations of GF, PK, TFM, VF, ... +* gftopk invocation:: GF -> PK (compact) +* pktogf invocation:: PK -> GF (expand). +* pktype invocation:: PK -> human-readable text. +* gftype invocation:: GF -> human-readable text. +* tftopl invocation:: TFM -> PL (for editing TFM). +* pltotf invocation:: PL -> TFM (make editing results usable). +* vftovp invocation:: VF -> VPL (tftopl for virtual fonts). +* vptovf invocation:: VPL -> VF (pltotf for virtual fonts). +* Font utilities available elsewhere:: Type 1, BDF, editors, etc. +@end menu + + +@node Font file formats +@section Font file formats + +@cindex font file formats +@cindex file formats for fonts + +(For another perspective on this, @pxref{Font concepts,,, dvips, +Dvips}). + +Font files come in several varieties, with suffixes like: +@example +.tfm .*pk .*gf .*pxl@r{ (obsolete)} .pl .mf .vf .vpl +@end example +@noindent +Each represents a file format. + +@cindex TFM files, explained +A TFM (@TeX{} font metric) file is a compact binary file that contains +information about each character in a font, about combinations of +characters within that font, and about the font as a whole. The font +metric information contained in TFM files is device-independent units is +used by @TeX{} to do typesetting. Unlike the bitmap (raster) fonts +described below, TFM font files contain no information about the shapes +of characters. They describe rectangular areas and combinations +thereof, but not what will eventually be printed in those areas. + +@cindex scaling of fonts +@cindex optical font scaling +@cindex geometric font scaling +@cindex PostScript, and font scaling +Since @TeX{} does scaling calculations, one TFM file serves for all +magnifications of a given typeface. On the other hand, the best printed +results are obtained when magnified (or reduced fonts) are not produced +geometrically (as done by PostScript, for example) but rather optically, +with each size a separate design (as done with Computer Modern and the +EC fonts, for example); then a separate TFM file is needed for each +size. + +@cindex DVI files, explained +At any rate, @TeX{} produces a DVI (DeVice Independent) file from your +source document. In order to print DVI files on real devices, you need +font files defining digitized character shapes and other data. Then +previewers and printer-driver programs can translate your DVI files into +something usable by your monitor or printer. Bitmap fonts come with +suffixes such as @samp{.600pk} or @samp{.600gf} or @samp{.3000pxl}, where +the @samp{600} is the horizontal dots-per-inch resolution at which the +font was produced, and the @samp{pk} or @samp{gf} or @samp{pxl} +indicates the font format. Outline fonts in PostScript Type 1 format +have suffixes such as @samp{.pfa} or @samp{.pfb}. + +@cindex PXL files, explained +@cindex PK files, explained +@cindex GF files, explained +Fonts in pk (packed) format are in the tightly packed raster format that +is pretty much the standard today. They take up less space than fonts +in the gf (generic font) format that Metafont generates, and far less +space than fonts in pxl format. Fonts in pxl format take up gross +amounts of disk space and permit only 128 characters. They are +obsolete. + +@cindex PL files, explained +Font files with the @samp{.pl} (property list) suffix are the plain text +(human-readable) analog of the binary @samp{.tfm} files. +The TFtoPL and PLtoTF programs convert between the two formats +(@pxref{tftopl invocation} and @ref{pltotf invocation}). + +Font files with the @samp{.mf} suffix are in Metafont source format. +These are the files used by Metafont to generate rastered fonts for +specific typefaces at specific magnifications for the specific +resolution and type of mapping used by your device. + +@flindex virtual-fonts.knuth +@flindex virtualfonts.txt +The suffix @samp{.vf} identifies ``virtual font'' files, for which +@samp{.vpl} is the human-readable analog. See @xref{vftovp invocation}, +and @ref{vptovf invocation}. For further discussion of virtual fonts, +see @file{@var{CTAN:}/doc/virtual-fonts.knuth}, +@file{@var{CTAN:}/help/virtualfonts.txt}, and @ref{Virtual fonts,,, +dvips, Dvips}. + +@cindex MacKay, Pierre +@cindex Tachikawa, Elizabeth +(This section is based on documentation in the original Unix @TeX{} +distribution by Pierre MacKay and Elizabeth Tachikawa.) + + +@node gftopk invocation +@section GFtoPK: Generic to packed font conversion + +@pindex gftopk +@cindex conversion, GF to PK +@cindex PK, converting GF to +@cindex GF, converting to PK + +GFtoPK converts a generic font (GF) file output by, for example, +Metafont (@pxref{mf invocation}) to a packed font (PK) file. PK files +are considerably smaller than the corresponding gf files, so they are +generally the bitmap font format of choice. Some DVI-processing +programs, notably Dvips, only support PK files and not GF files. +Synopsis: + +@example +gftopk [@var{option}]@dots{} @var{gfname}.@var{dpi}[gf] [@var{pkfile}] +@end example + +@noindent +The font @var{gfname} is searched for in the usual places (@pxref{Glyph +lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the +environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running +the program. + +The suffix @samp{gf} is supplied if not already present. This suffix is +not an extension; no @samp{.} precedes it: for instance, +@file{cmr10.600gf}. + +If @var{pkfile} is not specified, the output is written to the basename +of @samp{@var{gfname}.@var{dpi}pk}, e.g., @samp{gftopk +/wherever/cmr10.600gf} creates @file{./cmr10.600pk}. + +The only options are @samp{--verbose}, @samp{--help}, and +@samp{--version} (@pxref{Common options}). + + +@node pktogf invocation +@section PKtoGF: Packed to generic font conversion + +@pindex pktogf +@cindex conversion, PK to GF +@cindex GF, converting PK to +@cindex PK, converting to GF + +PKtoGF converts a packed font (PK) file to a generic font (GF) file. +Since PK format is much more compact than GF format, the most likely +reason to do this is to run GFtype (@pxref{gftype invocation}) on the +result, so you can see the bitmap images. Also, a few old utility +programs do not support PK format. Synopsis: + +@example +pktogf [@var{option}]@dots{} @var{pkname}.@var{dpi}[pk] [@var{gffile}] +@end example + +@noindent +The font @var{pkname} is searched for in the usual places (@pxref{Glyph +lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the +environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running +the program. + +The suffix @samp{pk} is supplied if not already present. This suffix is +not an extension; no @samp{.} precedes it: for instance, +@file{cmr10.600pk}. + +If @var{gffile} is not specified, the output is written to the basename +of @samp{@var{pkname}.@var{dpi}gf}, e.g., @samp{pktogf +/wherever/cmr10.600pk} creates @file{./cmr10.600gf}. + +The only options are @samp{--verbose}, @samp{--help}, and +@samp{--version} (@pxref{Common options}). + + +@node pktype invocation +@section PKtype: Plain text transliteration of packed fonts + +@pindex pktype @r{PK validation} +@cindex conversion, PK to plain text +@cindex plain text, converting PK to +@cindex human-readable text, converting PK to +@cindex type programs, PK +@cindex validation, of PK files + +PKtype translates a packed font (PK) bitmap file (as output by GFtoPK, +for example) to a plain text file that humans can read. It also serves +as a PK-validating program, i.e., if PKtype can read a file, it's +correct. Synopsis: + +@example +pktype @var{pkname}.@var{dpi}[pk] +@end example + +The font @var{pkname} is searched for in the usual places (@pxref{Glyph +lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the +environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running +the program. + +The suffix @samp{pk} is supplied if not already present. This suffix is +not an extension; no @samp{.} precedes it: for instance, @file{cmr10.600pk}. + +The translation is written to standard output. + +The only options are @samp{-help} and @samp{-version} +(@pxref{Common options}). + +As an example of the output, here is the (abridged) translation of the +letter `K' in @samp{cmr10}, as rendered at 600@dmn{dpi} with the mode +@samp{ljfour} from @url{modes.mf} (available from +@file{ftp://ftp.tug.org/tex/modes.mf}). + +@smallexample +955: Flag byte = 184 Character = 75 Packet length = 174 + Dynamic packing variable = 11 + TFM width = 815562 dx = 4259840 + Height = 57 Width = 57 X-offset = -3 Y-offset = 56 + [2]23(16)17(8)9(25)11(13)7(27)7(16)7(28)4(18)7(28)2(20)7(27)@dots{} + @dots{} + (14)9(24)12(5)[2]23(13)21 +@end smallexample + +@noindent +Explanation: + +@table @samp +@item 955 +@cindex byte position +The byte position in the file where this character starts. + +@item Flag byte +@itemx Dynamic packing variable +@cindex flag byte +@cindex dynamic packing variable +Related to the packing for this character; see the source code. + +@item Character +@cindex character codes, in PKtype output +The character code, in decimal. + +@item Packet length +@cindex packet length +The total length of this character definition, in bytes. + +@item TFM width +@cindex TFM width of characters +@cindex device-independent width +@cindex width, device-independent +The device-independent (TFM) width of this character. It is 2^24 +times the ratio of the true width to the font's design size. + +@item dx +@cindex horizontal escapement +@cindex escapement, horizontal +@cindex scaled pixels +@cindex dx @r{horizontal escapement} +The device-dependent width, in @dfn{scaled pixels}, i.e., units of +horizontal pixels times 2^16. + +@item Height +@itemx Width +@cindex height, in pixels +@cindex pixel height +@cindex pixel width +@cindex width, in pixels +The bitmap height and width, in pixels. + +@item X-offset +@itemx Y-offset +@cindex x offset +@cindex y offset +@cindex origin +@cindex reference pixel +@cindex side bearings +@cindex left side bearing +@cindex right side bearing +Horizontal and vertical offset from the upper left pixel to the +reference (origin) pixel for this character, in pixels (right and down +are positive). The @dfn{reference pixel} is the pixel that occupies the +unit square in Metafont; the Metafont reference point is the lower left +hand corner of this pixel. Put another way, the x-offset is the negative +of the left side bearing; the right side bearing is the horizontal +escapement minus the bitmap width plus the x-offset. + +@item [2]23(16)@dots{} +@cindex run length encoded bitmaps +@cindex repeated rows +Finally, run lengths of black pixels alternate with parenthesized run +lengths of white pixels, and brackets indicate a repeated row. +@end table + + +@node gftype invocation +@section GFtype: Plain text transliteration of generic fonts + +@pindex gftype @r{GF validation} +@cindex conversion, GF to plain text +@cindex plain text, converting GF to +@cindex human-readable text, converting GF to +@cindex type programs, GF +@cindex validation, of GF files + +GFtype translates a generic font (GF) bitmap file (as output by +Metafont, for example) to a plain text file that humans can read. It +also serves as a GF-validating program, i.e., if GFtype can read a file, +it's correct. Synopsis: + +@example +gftype [@var{option}]@dots{} @var{gfname}.@var{dpi}[gf] +@end example + +The font @var{gfname} is searched for in the usual places (@pxref{Glyph +lookup,,, kpathsea, Kpathsea}). To see all the relevant paths, set the +environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running +the program. + +The suffix @samp{gf} is supplied if not already present. This suffix is +not an extension; no @samp{.} precedes it: for instance, @file{cmr10.600gf}. + +The translation is written to standard output. + +The program accepts the following options, as well as the standard +@samp{-help} and @samp{-version} (@pxref{Common options}): +@table @samp +@item -images +@opindex -images +Show the characters' bitmaps using asterisks and spaces. + +@item -mnemonics +@opindex -mnemonics +Translate all commands in the GF file. +@end table + +As an example of the output, here is the (abrdiged) translation of the +letter `K' in @samp{cmr10}, as rendered at 600@dmn{dpi} with the mode +@samp{ljfour} from @file{modes.mf} (available from +@url{ftp://ftp.tug.org/tex/modes.mf}), with both @samp{-mnemonics} and +@samp{-images} enabled. + +GFtype outputs the information about a character in two places: a main +definition and a one-line summary at the end. We show both. Here is the +main definition: + +@example +2033: beginning of char 75: 3<=m<=60 0<=n<=56 +(initially n=56) paint (0)24(12)20 +2043: newrow 0 (n=55) paint 24(12)20 +2047: newrow 0 (n=54) paint 24(12)20 +2051: newrow 0 (n=53) paint 24(12)20 +2055: newrow 7 (n=52) paint 10(21)13 +2059: newrow 8 (n=51) paint 8(23)9 +@dots{} +2249: newrow 8 (n=5) paint 8(23)11 +2253: newrow 7 (n=4) paint 10(22)12 +2257: newrow 0 (n=3) paint 24(11)22 +2261: newrow 0 (n=2) paint 24(11)22 +2265: newrow 0 (n=1) paint 24(11)22 +2269: newrow 0 (n=0) paint 24(11)22 +2273: eoc +@group +.<--This pixel's lower left corner is at (3,57) in METAFONT coordinates +************************ ******************** +************************ ******************** +************************ ******************** +************************ ******************** + ********** ************* + ******** ********* +@dots{} + ******** *********** + ********** ************ +************************ ********************** +************************ ********************** +************************ ********************** +************************ ********************** +.<--This pixel's upper left corner is at (3,0) in METAFONT coordinates +@end group +@end example + +@noindent +Explanation: + +@table @samp +@item 2033 +@itemx 2043 +@itemx @dots{} +@cindex byte position +The byte position in the file where each GF command starts. + +@item beginning of char 75 +@cindex character codes, in GFtype output +The character code, in decimal. + +@item 3<=m<=60 0<=n<=56 +@cindex left side bearing +@cindex right side bearing +@cindex side bearings +The character's bitmap lies between 3 and 60 (inclusive) horizontally, +and between 0 and 56 (inclusive) vertically. (@math{m} is a column +position and @math{n} is a row position.) Thus, 3 is the left side +bearing. The right side bearing is the horizontal escapement (given +below) minus the maximum @math{m}. + +@item (initially n=56) paint (0)24(12)20 +@cindex run length encoded bitmaps +The first row of pixels: 0 white pixels, 24 black pixels, 12 white +pixels, etc. + +@item newrow 0 (n=55) paint 24(12)20 +@findex newrow @r{GF command} +The second row of pixels, with zero leading white pixels on the row. + +@item eoc +@findex eoc @r{GF command} +The end of the main character definition. + +@end table + +Here is the GF postamble information that GFtype outputs at the end: + +@example +Character 75: dx 4259840 (65), width 815562 (64.57289), loc 2033 +@end example + +Explanation: + +@table @samp +@item dx +@cindex horizontal escapement +@cindex escapement, horizontal +@cindex vertical escapement +@cindex escapement, vertical +@cindex scaled pixels +@cindex dx @r{horizontal escapement} +@cindex dy @r{vertical escapement} +The device-dependent width, in @dfn{scaled pixels}, i.e., units of +horizontal pixels times 2^16. The @samp{(65)} is simply the same number +rounded. If the vertical escapement is nonzero, it would appear here as +a @samp{dy} value. + +@item width +@cindex TFM width of characters +@cindex device-independent width +@cindex width, device-independent +The device-independent (TFM) width of this character. It is 2^24 +times the ratio of the true width to the font's design size. The +@samp{64.57289} is the same number converted to pixels. + +@item loc +The byte position in the file where this character starts. + +@end table + + +@node tftopl invocation +@section TFtoPL: @TeX{} font metric to property list conversion + +@pindex tftopl +@cindex conversion, TFM to property list +@cindex validation, of TFM files +@cindex property list, converting TFM to +@cindex human-readable text, converting TFM to +@cindex plain text, converting TFM to + +TFtoPL translates a @TeX{} font metric (TFM, @pxref{Metric +files,,,dvips,Dvips}) file (as output by Metafont, for example) to +@dfn{property list format} (a list of parenthesized items describing the +font) that humans can edit or read. This program is mostly used by +people debugging @TeX{} implementations, writing font utilities, etc. +Synopsis: + +@example +tftopl [@var{option}]@dots{} @var{tfmname}[.tfm] [@var{plfile}[.pl]] +@end example + +The font @var{tfmname} (extended with @samp{.tfm} if necessary) is +searched for in the usual places (@pxref{Supported file formats,,, +kpathsea, Kpathsea}). To see all the relevant paths, set the +environment variable @code{KPATHSEA_DEBUG} to @samp{-1} before running +the program. + +If @var{plfile} (which is extended with @samp{.pl} if necessary) is not +specified, the property list file is written to standard output. The +property list file can be converted back to TFM format by the companion +program TFtoPL (see the next section). + +The program accepts the following option, as well as the standard +@samp{-verbose}, @samp{-help} and @samp{-version} (@pxref{Common +options}): +@table @samp +@item -charcode-format=@var{type} +@opindex -charcode-format=@var{type} +Output character codes in the PL file according to @var{type}: either +@samp{octal} or @samp{ascii}. Default is @samp{ascii} for letters and +digits, octal for all other characters. Exception: if the font's coding +scheme starts with @samp{TeX math sy} or @samp{TeX math ex}, all +character codes are output in octal. + +In @samp{ascii} format, character codes that correspond to graphic +characters, except for left and right parentheses, are output as a +@samp{C} followed by the single character: @samp{C K}, for example. In +octal format, character codes are output as the letter @samp{O} followed +by octal digits, as in @samp{O 113} for @samp{K}. + +@samp{octal} format is useful for symbol and other non-alphabetic fonts, +where using ASCII characters for the character codes is merely +confusing. +@end table + +@cindex property list format +As an example of the output, here is the (abridged) property list +translation of @file{cmr10.tfm}: + +@example +(FAMILY CMR) +(FACE O 352) +(CODINGSCHEME TEX TEXT) +(DESIGNSIZE R 10.0) +(COMMENT DESIGNSIZE IS IN POINTS) +(COMMENT OTHER SIZES ARE MULTIPLES OF DESIGNSIZE) +(CHECKSUM O 11374260171) +(FONTDIMEN + (SLANT R 0.0) + (SPACE R 0.333334) + (STRETCH R 0.166667) + (SHRINK R 0.111112) + (XHEIGHT R 0.430555) + (QUAD R 1.000003) + (EXTRASPACE R 0.111112) + ) +(LIGTABLE + @dots{} + (LABEL C f) + (LIG C i O 14) + (LIG C f O 13) + (LIG C l O 15) + (KRN O 47 R 0.077779) + (KRN O 77 R 0.077779) + (KRN O 41 R 0.077779) + (KRN O 51 R 0.077779) + (KRN O 135 R 0.077779) + (STOP) + @dots{} + ) +@dots{} +(CHARACTER C f + (CHARWD R 0.305557) + (CHARHT R 0.694445) + (CHARIC R 0.077779) + (COMMENT + (LIG C i O 14) + (LIG C f O 13) + (LIG C l O 15) + (KRN O 47 R 0.077779) + (KRN O 77 R 0.077779) + @dots{} + ) + ) +@dots{} +@end example + +As you can see, the general format is a list of parenthesized +@dfn{properties}, nested where necessary. + +@itemize @bullet +@item +@findex FAMILY @r{property} +@findex FACE @r{property} +@findex headerbyte @r{information} +The first few items (@code{FAMILY}, @code{FACE}, and so on) are +the so-called @dfn{headerbyte} information from Metafont, giving general +information about the font. + +@item +@findex FAMILY @r{property} +@findex \fontdimen +The @code{FONTDIMEN} property defines the @TeX{} @code{\fontdimen} +values. + +@item +@findex LIGTABLE @r{property} +@findex LABEL @r{property} +@findex LIG @r{property} +@findex KRN @r{property} +@cindex ligature table, in TFM files +@cindex kerning table, in TFM files +@cindex design-size units +The @code{LIGTABLE} property defines the ligature and kerning table. +@code{LIG} properties define ligatures: in the example above, an +@samp{f} (in the @samp{LABEL}) followed by an @samp{i} is a ligature, +i.e., a typesetting program like @TeX{} replaces those two consecutive +characters by the character at position octal '014 in the current +font---presumably the `fi' ligature. @code{KRN} properties define +kerns: if an @samp{f} is followed by character octal '047 (an +apostrophe), @TeX{} inserts a small amount of space between them: +0.077779 times the design size the font was loaded at (about +three-quarters of a printer's point by default in this case, or .001 +inches). + +@item +@findex CHARACTER @r{property} +@findex CHARWD @r{property} +@findex CHARHT @r{property} +@findex CHARDP @r{property} +@findex CHARIC @r{property} +The @code{CHARACTER} property defines the dimensions of a character: its +width, height, depth, and italic correction, also in design-size units, +as explained in the previous item. For our example `f', the depth is +zero, so that property is omitted. TFtoPL also inserts any kerns and +ligatures for this character as a comment. + +@end itemize + + +@node pltotf invocation +@section PLtoTF: Property list to @TeX{} font metric conversion + +@pindex pltotf +@cindex conversion, property list to TFM +@cindex TFM files, converting property lists to +@cindex machine-readable, converting property lists to + +PLtoTF translates a property list file (as output by TFtoPL, for +example) to @TeX{} font metric (TFM, @pxref{Metric files,,,dvips,Dvips}) +format. It's much easier for both programs and humans to create the +(plain text) property list files and let PLtoTF take care of creating +the binary TFM equivalent than to output TFM files directly. Synopsis: + +@example +pltotf [@var{option}]@dots{} @var{plfile}[.pl] [@var{tfmfile}[.tfm]] +@end example + +If @var{tfmfile} (extended with @samp{.tfm} if necessary) is +not specified, the TFM file is written to the basename of +@samp{@var{plfile}.tfm}, e.g., @samp{pltotf /wherever/cmr10.pl} creates +@file{./cmr10.tfm}. (Since TFM files are binary, writing to standard +output by default is undesirable.) + +The only options are @samp{-verbose}, @samp{-help}, and +@samp{-version} (@pxref{Common options}). + +For an example of property list format, see the previous section. + + +@node vftovp invocation +@section VFtoVP: Virtual font to virtual property lists + +@pindex vftovp +@cindex conversion, VF to VPL +@cindex validation, of VF files +@cindex property list, converting VF to virtual +@cindex human-readable text, converting VF to +@cindex plain text, converting VF to + +VFtoVP translates a virtual font metric (VF, @pxref{Virtual +fonts,,,dvips,Dvips}) file and its accompanying @TeX{} font metric (TFM, +@pxref{Metric files,,,dvips,Dvips}) file (as output by VPtoVF, for +example) to @dfn{virtual property list format} (a list of parenthesized +items describing the virtual font) that humans can edit or read. This +program is mostly used by people debugging virtual font utilities. +Synopsis: + +@example +vftovp [@var{option}]@dots{} @var{vfname}[.vf] [@var{tfmname}[.tfm] @c +[@var{vplfile}[.vpl]]] +@end example + +The fonts @var{vfname} and @var{tfmname} (extended with @samp{.vf} and +@samp{.tfm} if necessary) are searched for in the usual places +(@pxref{Supported file formats,,, kpathsea, Kpathsea}). To see all the +relevant paths, set the environment variable @code{KPATHSEA_DEBUG} to +@samp{-1} before running the program. If @var{tfmname} is not +specified, @var{vfname} (without a trailing @samp{.vf}) is used. + +If @var{vplfile} (extended with @samp{.vpl} if necessary) is +not specified, the property list file is written to standard output. +The property list file can be converted back to VF and TFM format by the +companion program VFtoVP (see the next section). + +The program accepts the following option, as well as the standard +@samp{-verbose}, @samp{-help} and @samp{-version} (@pxref{Common +options}): +@table @samp +@item -charcode-format=@var{type} +@opindex -charcode-format=@var{type} +Output character codes in the PL file according to @var{type}: either +@samp{octal} or @samp{ascii}. Default is @samp{ascii} for letters and +digits, octal for all other characters. Exception: if the font's coding +scheme starts with @samp{TeX math sy} or @samp{TeX math ex}, all +character codes are output in octal. + +In @samp{ascii} format, character codes that correspond to graphic +characters, except for left and right parentheses, are output as a +@samp{C} followed by the single character: @samp{C K}, for example. In +octal format, character codes are output as the letter @samp{O} followed +by octal digits, as in @samp{O 113} for @samp{K}. + +@samp{octal} format is useful for symbol and other non-alphabetic fonts, +where using ASCII characters for the character codes is merely +confusing. +@end table + + +@node vptovf invocation +@section VPtoVF: Virtual property lists to virtual font + +@pindex vptovf +@cindex conversion, property list to VF +@cindex VF files, converting property lists to +@cindex machine-readable, converting property lists to + +VPtoVF translates a virtual property list file (as output by VFtoVP, for +example) to virtual font (VF, @pxref{Virtual fonts,,,dvips,Dvips}) and +@TeX{} font metric (TFM, @pxref{Metric files,,,dvips,Dvips}) files. +It's much easier for both programs and humans to create the (plain text) +property list files and let VPtoVF take care of creating the binary VF +and TFM equivalents than to output them directly. Synopsis: + +@example +vptovf [@var{option}]@dots{} @var{vplfile}[.vpl] [@var{vffile}[.vf] @c +[@var{tfmfile}[.tfm]]] +@end example + +If @var{vffile} (extended with @samp{.vf} if necessary) is not +specified, the VF output is written to the basename of +@samp{@var{vplfile}.vf}; similarly for @var{tfmfile}. For example, +@samp{vptovf /wherever/ptmr.vpl} creates @file{./ptmr.vf} and +@file{./ptmr.tfm}. + +The only options are @samp{-verbose}, @samp{-help}, and @samp{-version} +(@pxref{Common options}). + + +@node Font utilities available elsewhere +@section Font utilities available elsewhere + +@cindex font utilities, non-Web2c + +The Web2c complement of font utilities merely implements a few basic +conversions. Many other more sophisticated font utilities exist; most +are in @file{@var{CTAN:}/fonts/utilities} (for CTAN info, +@pxref{unixtex.ftp,,, kpathsea, Kpathsea}). Here are some of the most +commonly-requested items: + +@itemize @bullet +@item +@cindex AFM to TFM conversion +@pindex afm2tfm +@pindex afmtopl +AFM (Adobe font metric) to TFM conversion: @pxref{Invoking afm2tfm,,, +dvips, Dvips}, and @file{@var{CTAN:}/fonts/utilities/afmtopl}. + +@item +@cindex X bitmap fonts +@cindex BDF and GF conversion +BDF (the X bitmap format) conversion: +@url{ftp://ftp.tug.org/tex/bdf.tar.gz}. + +@item +@pindex metatype1 +@cindex Latin Modern +Creating fonts using MetaPost: MetaType1. +@url{ftp://bop.eps.gda.pl/pub/metatype1}. This is used to create +the excellent Latin Modern font family (@file{@var{CTAN:}/fonts/lm}), +which extends Computer Modern to a vast repertoire of scripts. + +@item +@cindex editing of bitmap fonts +@pindex xbfe@r{, bitmap font editor} +@pindex xfed@r{, bitmap font editor} +@pindex xfedor@r{, bitmap font editor} +@pindex gftopxl +@pindex chtopx +@pindex pxtoch +Editing of bitmap fonts: Xbfe from the GNU font utilities mentioned +below; the X BDF-editing programs available from +@url{ftp://ftp.x.org/R5contrib/xfed.tar.Z} and +@url{ftp://ftp.x.org/R5contrib/xfedor.tar.Z}; and finally, if your +fonts have only 128 characters, you can use the old @code{gftopxl}, +@code{pxtoch}, and @code{chtopx} programs from +@url{ftp://ftp.tug.org/tex/web}. + +@item +@pindex fontforge +@pindex pfaedit +Editing of outline fonts: FontForge, @url{fontforge.sourceforge.net}. +This is a very elaborate program with support for many outline formats +(Type@tie{}1, OpenType, TrueType, @dots{}), and many advanced font +editing features. + +@item +@cindex PK bitmaps from PostScript +@cindex PostScript to PK bitmaps +@pindex gsftopk +@pindex ps2pk +PK bitmaps from PostScript outline fonts: gsftopk from the @samp{xdvi} +distribution. Alternatively, @code{ps2pk}, from +@file{@var{CTAN:}/fonts/utilities/ps2pk}. + +@item +@cindex Type 1 conversion +@cindex PFA and PFB conversion +@cindex PostScript Type 1 font conversion +PostScript Type 1 font format conversion (i.e., between PFA and PFB +formats): @url{https://www.lcdf.org/type}. + +@item +@pindex autotrace +@pindex potrace +Tracing bitmaps to fitted outlines: Autotrace +(@url{http://autotrace.sourceforge.net}), Potrace +(@url{http://potrace.sourceforge.net}). For Metafont fonts, either of +the two programs @code{mftrace} +(@url{http://www.xs4all.nl/~hanwen/mftrace}) or @code{textrace} +(@url{http://textrace.sourceforge.net}) make the job easier. + +@item +@cindex virtual font creation +@pindex fontinst@r{, for creating virtual fonts} +Virtual font creation: @url{https://ctan.org/pkg/fontinst}. +@end itemize + + +@node Legalisms +@appendix Legalisms + +@cindex legalisms +@cindex copyright notices +@cindex permissions, legal + +In general, each file has its own copyright notice stating the copying +permissions for that file. Following is a summary. + +The Stanford @TeX{} programs and Web2c system itself are in the public +domain (@url{https://tug.org/texlive/copying.html}). The sources may +be copied verbatim, or used as the starting point of new software +under different names; however, per the wishes of the authors, they +should be modified only through a @file{.ch} file, but this is in the +nature of a development request rather than a legal requirement. + +ML@TeX{}, pdf@TeX{}, Lua@TeX{}, Xe@TeX{}, and all the other derived +engines have used various license terms for their additions to the +base code, often the GPL (see @url{https://www.gnu.org/licenses/#GPL} +or (for example) the file @file{web2c/pdftexdir/COPYINGv2}. They also +mostly make use of additional libraries with their own (compatible) +terms. Please see each program's sources. + +The Kpathsea library is covered by the GNU Lesser General Public +License (@pxref{Introduction,,, kpathsea, Kpathsea}). Therefore, the +@emph{binaries} resulting from a standard Web2c compilation are also +covered by the LGPL; so if you (re)distribute the binaries, you must +also (offer to) distribute the complete source that went into those +binaries. See @url{https://gnu.org/licenses/#LGPL} or the file +@file{kpathsea/COPYING.LESSERv2}. + +@node References +@appendix References + +@cindex references +@cindex bibliography + +@enumerate +@item +Kpathsea: @xref{Top, Introduction,, kpathsea, Kpathsea}. + +@item +Dvips and Afm2tfm: @xref{Top, Introduction,, dvips, Dvips}. + +@item +The @TeX{} Users Group: @url{https://tug.org}. For an introduction +to the @TeX{} system, see @url{https://tug.org/begin.html}. + +@item +TUGboat, the principal journal for the @TeX{} world: +@url{https://tug.org/TUGboat}. + +@item +@TeX{} and computer typesetting in general:@* +@url{ftp://ftp.math.utah.edu/pub/tex/bib/texbook1.bib}. + +@item +For a bibliography of formal articles and technical reports on the +@TeX{} project, see the books @cite{@TeX{}: The Program} or +@cite{Metafont: The Program} cited below. + +@include ref.txi + +@end enumerate + + +@node Index +@unnumbered Index + +@printindex cp + +@bye |