{ "content": [ { "type": "text", "text": "# kpathsea (info)\n\n## Sections\n\n- **File: kpathsea.info, Node: Top, Next: Introduction, Up: (dir)**\n- **Kpathsea library**\n- **This manual documents the Kpathsea library for path searching. It**\n- **File: kpathsea.info, Node: Introduction, Next: unixtex.ftp, Prev: Top, Up: Top**\n- **1 Introduction**\n- **This manual corresponds to version 6.3.3 of the Kpathsea library,**\n- **Public License (LGPL), version 2.1 or (at your option) any later**\n- **See accompanying files for the text of the GNU licenses, or**\n- **File: kpathsea.info, Node: History, Up: Introduction** (1 subsections)\n- **This section is for those people who are curious about how the library**\n- **February 1990, but I may have done some work before then. In any case,**\n- **Tim Morgan and I were jointly maintaining it for a time. (I should**\n- **They weren't yet a library, though. I just kept things up to date with**\n- **Neumann's help, implemented a way for TeX to get at all those neat**\n- **Web2c with Kpathsea. After the release of a stable Web2c, I hope to be**\n- **Unix by then, or that software patents haven't stopped software**\n- **In 2009, Taco Hoekwater implemented a major rearrangement to make the**\n- **File: kpathsea.info, Node: unixtex.ftp, Next: Security, Prev: Introduction, Up: Top**\n- **2 'unixtex.ftp': Obtaining TeX**\n- **However, unless you want to undertake the project of building your TeX**\n- **File: kpathsea.info, Node: Security, Next: TeX directory structure, Prev: unixtex.ftp, Up: Top**\n- **3 Security**\n- **None of the programs in the TeX system require any special system**\n- **File: kpathsea.info, Node: TeX directory structure, Next: Path searching, Prev: Security, Up: Top**\n- **4 TeX directory structure**\n- **This section describes the default installation hierarchy of the**\n- **File: kpathsea.info, Node: Path searching, Next: TeX support, Prev: TeX directory structure, Up: Top**\n- **5 Path searching**\n- **This chapter describes the generic path searching mechanism Kpathsea**\n- **German, ...) as part of the TeX Live guide; see**\n- **File: kpathsea.info, Node: Searching overview, Next: Path sources, Up: Path searching** (1 subsections)\n- **Kpathsea simply checks if that file exists, with a fallback to a**\n- **File: kpathsea.info, Node: Path sources, Next: Path expansion, Prev: Searching overview, Up: Path searching** (1 subsections)\n- **File: kpathsea.info, Node: Config files, Up: Path sources**\n- **Kpathsea warns if the program name contains a path separator or other**\n- **File: kpathsea.info, Node: Path expansion, Next: Casefolding search, Prev: Path sources, Up: Path searching** (1 subsections)\n- **Kpathsea recognizes certain special characters and constructions in**\n- **File: kpathsea.info, Node: Default expansion, Next: Variable expansion, Up: Path expansion**\n- **File: kpathsea.info, Node: Variable expansion, Next: Tilde expansion, Prev: Default expansion, Up: Path expansion**\n- **Shell variable values cannot be seen by Kpathsea, i.e., ones defined**\n- **File: kpathsea.info, Node: Tilde expansion, Next: Brace expansion, Prev: Variable expansion, Up: Path expansion**\n- **File: kpathsea.info, Node: Brace expansion, Next: KPSEDOT expansion, Prev: Tilde expansion, Up: Path expansion**\n- **File: kpathsea.info, Node: KPSEDOT expansion, Next: Subdirectory expansion, Prev: Brace expansion, Up: Path expansion**\n- **When 'KPSEDOT' is defined in the environment, it names a directory that**\n- **File: kpathsea.info, Node: Subdirectory expansion, Prev: KPSEDOT expansion, Up: Path expansion**\n- **Two or more consecutive slashes in a path element following a directory**\n- **That is to say, the 'stnlink' field in the 'stat' structure will be**\n- **File: kpathsea.info, Node: Casefolding search, Next: Filename database, Prev: Path expansion, Up: Path searching** (1 subsections)\n- **In Kpathsea version 6.3.0 (released with TeX Live 2018), a new fallback**\n- **File: kpathsea.info, Node: Casefolding rationale, Next: Casefolding examples, Up: Casefolding search**\n- **The purpose of the fallback casefolding search is to ease moving complex**\n- **Macs be case-insensitive some years ago, and this has exacerbated a**\n- **It works on the Mac but if the document is transferred and run on a**\n- **Windows, where (for practical purposes) all file names are**\n- **File: kpathsea.info, Node: Casefolding examples, Prev: Casefolding rationale, Up: Casefolding search**\n- **The casefolding implementation prefers exact matches to casefolded**\n- **Backward compatibility is not perfect, however, as a casefolded match**\n- **Also (as expected), searching for 'FOOBAR.TEX' (or whatever variation)**\n- **Perhaps unexpectedly, searching for all 'foobar.tex' or 'FooBar.tex'**\n- **Because Kpathsea never searches the disk in the big system directory,**\n- **TeX Live, that is the 'texmf-local' and 'texmf-dist' trees (also**\n- **The rationale for this is that in practice, case mangling happens with**\n- **Kpathsea would be a lot of error-prone trouble for something that is**\n- **File: kpathsea.info, Node: Filename database, Next: Invoking kpsewhich, Prev: Casefolding search, Up: Path searching** (1 subsections)\n- **Kpathsea goes to some lengths to minimize disk accesses for searches**\n- **File: kpathsea.info, Node: ls-R, Next: Filename aliases, Up: Filename database**\n- **You can put one at the root of each TeX installation hierarchy you wish**\n- **In TeX Live, the most notable case of this is the 'TEXMFHOME' tree, to**\n- **File: kpathsea.info, Node: Filename aliases, Next: Database format, Prev: ls-R, Up: Filename database**\n- **For example, suppose a TeX document was created using a DOS system and**\n- **File: kpathsea.info, Node: Database format, Prev: Filename aliases, Up: Filename database**\n- **The format is that generated by GNU (and most other) 'ls' programs given**\n- **File: kpathsea.info, Node: Invoking kpsewhich, Prev: Filename database, Up: Path searching** (1 subsections)\n- **The Kpsewhich program exercises the path searching functionality**\n- **File: kpathsea.info, Node: Path searching options, Next: Specially-recognized files, Up: Invoking kpsewhich**\n- **Kpsewhich looks up each non-option argument on the command line as a**\n- **File: kpathsea.info, Node: Specially-recognized files, Next: Auxiliary tasks, Prev: Path searching options, Up: Invoking kpsewhich**\n- **File: kpathsea.info, Node: Auxiliary tasks, Next: Standard options, Prev: Specially-recognized files, Up: Invoking kpsewhich**\n- **File: kpathsea.info, Node: Standard options, Prev: Auxiliary tasks, Up: Invoking kpsewhich**\n- **File: kpathsea.info, Node: TeX support, Next: Programming, Prev: Path searching, Up: Top**\n- **6 TeX support**\n- **Although the basic features in Kpathsea can be used for any type of path**\n- **Indeed, many of the purportedly generic path searching features were**\n- **Searches are based solely on names of files, not their contents--if a GF**\n- **File: kpathsea.info, Node: Supported file formats, Next: File lookup, Up: TeX support** (1 subsections)\n- **Kpathsea has support for a number of file types. Each file type has a**\n- **File: kpathsea.info, Node: File lookup, Next: Glyph lookup, Prev: Supported file formats, Up: TeX support** (1 subsections)\n- **This section describes how Kpathsea searches for most files (bitmap font**\n- **File: kpathsea.info, Node: Glyph lookup, Next: Suppressing warnings, Prev: File lookup, Up: TeX support** (1 subsections)\n- **This section describes how Kpathsea searches for a bitmap font in GF or**\n- **File: kpathsea.info, Node: Basic glyph lookup, Next: Fontmap, Up: Glyph lookup**\n- **When Kpathsea looks for a bitmap font NAME at resolution DPI in a format**\n- **File: kpathsea.info, Node: Fontmap, Next: Fallback font, Prev: Basic glyph lookup, Up: Glyph lookup**\n- **If a bitmap font or metric file is not found with the original name (see**\n- **Web2c distribution. It makes the old and new names of the LaTeX circle**\n- **File: kpathsea.info, Node: Fallback font, Prev: Fontmap, Up: Glyph lookup**\n- **If a bitmap font cannot be found or created at the requested size,**\n- **Kpathsea looks first for a program-specific environment variable (e.g.,**\n- **File: kpathsea.info, Node: Suppressing warnings, Next: mktex scripts, Prev: Glyph lookup, Up: TeX support** (1 subsections)\n- **Kpathsea provides a way to suppress selected usually-harmless warnings;**\n- **File: kpathsea.info, Node: mktex scripts, Prev: Suppressing warnings, Up: TeX support** (1 subsections)\n- **If Kpathsea cannot otherwise find a file, for some file types it is**\n- **Building all fonts in advance is therefore impractical, if not**\n- **File: kpathsea.info, Node: mktex configuration, Next: mktex script names, Up: mktex scripts**\n- **The list of file types and program names that can run an external** (7 subsections)\n- **File: kpathsea.info, Node: mktex script names, Next: mktex script arguments, Prev: mktex configuration, Up: mktex scripts**\n- **The following table shows the default name of the script for each of the**\n- **These names can be overridden by an environment variable specific to the**\n- **Otherwise, nothing is written. The name 'missfont.log' is overridden by**\n- **File: kpathsea.info, Node: mktex script arguments, Prev: mktex script names, Up: mktex scripts**\n- **The first argument to a 'mktex' script is always the name of the file to**\n- **File: kpathsea.info, Node: Programming, Next: Reporting bugs, Prev: TeX support, Up: Top**\n- **7 Programming**\n- **Introduction::, for the conditions under which you may do so (in short,**\n- **File: kpathsea.info, Node: Programming overview, Next: Calling sequence, Up: Programming** (1 subsections)\n- **Aside from this manual, your best source of information is the source to**\n- **Kpathsea header, as it provides symbols used in the other headers. Note**\n- **Kpathsea has support for looking up Dvips config files, even though no**\n- **File: kpathsea.info, Node: Calling sequence, Next: Program-specific files, Prev: Programming overview, Up: Programming** (1 subsections)\n- **The typical way to use Kpathsea in your program goes something like**\n- **File: kpathsea.info, Node: Program-specific files, Next: Programming with config files, Prev: Calling sequence, Up: Programming** (1 subsections)\n- **Many programs will need to find some configuration files. Kpathsea**\n- **File: kpathsea.info, Node: Programming with config files, Prev: Program-specific files, Up: Programming** (1 subsections)\n- **You can (and probably should) use the same 'texmf.cnf' configuration**\n- **File: kpathsea.info, Node: Reporting bugs, Next: Index, Prev: Programming, Up: Top**\n- **8 Reporting bugs**\n- **If you have problems or suggestions, please report them to**\n- **File: kpathsea.info, Node: Bug checklist, Next: Mailing lists, Up: Reporting bugs** (1 subsections)\n- **Before reporting a bug, please check below to be sure it isn't already**\n- **File: kpathsea.info, Node: Mailing lists, Next: Debugging, Prev: Bug checklist, Up: Reporting bugs** (1 subsections)\n- **Web2c and Kpathsea in general are discussed on the mailing list**\n- **File: kpathsea.info, Node: Debugging, Next: Logging, Prev: Mailing lists, Up: Reporting bugs** (1 subsections)\n- **Kpathsea provides a number of runtime debugging options, detailed below**\n- **File: kpathsea.info, Node: Logging, Next: Common problems, Prev: Debugging, Up: Reporting bugs** (1 subsections)\n- **Kpathsea can record the time and filename found for each successful**\n- **Only filenames that are absolute are recorded, to preserve some**\n- **File: kpathsea.info, Node: Common problems, Prev: Logging, Up: Reporting bugs** (1 subsections)\n- **Here are some common problems with configuration, compilation, linking,**\n- **File: kpathsea.info, Node: Unable to find files, Next: Slow path searching, Up: Common problems**\n- **If a program complains it cannot find fonts (or other input files), any**\n- **File: kpathsea.info, Node: Slow path searching, Next: Unable to generate fonts, Prev: Unable to find files, Up: Common problems**\n- **If your program takes an excessively long time to find fonts or other**\n- **File: kpathsea.info, Node: Unable to generate fonts, Next: TeX or Metafont failing, Prev: Slow path searching, Up: Common problems**\n- **Metafont outputs fonts in bitmap format, tuned for a particular device**\n- **Then copy the 'plain.base' file from the current directory to where the**\n- **File: kpathsea.info, Node: TeX or Metafont failing, Prev: Unable to generate fonts, Up: Common problems**\n- **If TeX or Metafont get a segmentation fault or otherwise fail while**\n- **File: kpathsea.info, Node: Index, Prev: Reporting bugs, Up: Top**\n- **Index**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "kpathsea", "section": "", "mode": "info", "summary": null, "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "", "long": "--without-mktexfmt-default", "arg": null, "description": "" }, { "flag": "", "long": "--without-mktexmf-default", "arg": null, "description": "" }, { "flag": "", "long": "--without-mktexocp-default", "arg": null, "description": "" }, { "flag": "", "long": "--without-mktexofm-default", "arg": null, "description": "" }, { "flag": "", "long": "--without-mktexpk-default", "arg": null, "description": "" }, { "flag": "", "long": "--without-mktextfm-default", "arg": null, "description": "" }, { "flag": "", "long": "--with-mktextex-default", "arg": null, "description": "The 'configure' setting is overridden if the environment variable or configuration file value named for the script is set; e.g., 'MKTEXPK' (*note mktex script arguments::). 'mktexfmt' reads a file 'fmtutil.cnf', typically located in 'texmf/web2c/' to glean its configuration information. The rest of the files and features in this section are primarily intended for the font generation scripts. As distributed, all the scripts source a file 'texmf/web2c/mktex.cnf' if it exists, so you can override various defaults. See 'mktex.opt', for instance, which defines the default mode, resolution, some special directory names, etc. If you prefer not to change the distributed scripts, you can simply create 'mktex.cnf' with the appropriate definitions (you do not need to create it if you have nothing to put in it). 'mktex.cnf' has no special syntax; it's an arbitrary Bourne shell script. The distribution contains a sample 'mktex.cnf' for you to copy and modify as you please (it is not installed anywhere). In addition, you can configure a number of features with the 'MTFEATURES' variable, which you can define: * in 'mktex.opt', as just mentioned; * by editing the file 'mktex.opt', either before 'make install' (in the source hierarchy) or after (in the installed hierarchy); * or in the environment. If none of the options below are enabled, 'mktexpk', 'mktextfm', and 'mktexmf' follow the following procedure to decide where fonts should be installed. Find the tree where the font's sources are, and test the permissions of the 'fonts' directory of that tree to determine whether it is writable. If it is, put the files in the tree in appropriate locations. If it isn't writable, see whether the tree is a system tree (named in 'SYSTEXMF'). If so, the 'VARTEXFONTS' tree is used. In all other cases the working directory is used. The 'appendonlydir' option is enabled by default. 'appendonlydir' Tell 'mktexdir' to create directories append-only, i.e., set their sticky bit (*note (coreutils)Mode Structure::). This feature is silently ignored on non-Unix platforms (e.g. Windows/NT and MS-DOS) which don't support similar functionality. This feature is enabled by default. 'dosnames' Use 8.3 names; e.g., 'dpi600/cmr10.pk' instead of 'cmr10.600pk'. Note that this feature only affects filenames that would otherwise clash with other TeX-related filenames; 'mktex' scripts do nothing about filenames which exceed the 8+3 MS-DOS limits but remain unique when truncated (by the OS) to these limits, and nether do the scripts care about possible clashes with files which aren't related with TeX. For example, 'cmr10.600pk' would clash with 'cmr10.600gf' and is therefore changed when 'dosnames' is in effect, but 'mf.pool' and 'mp.base' don't clash with any TeX-related files and are therefore unchanged. This feature is turned on by default on MS-DOS. If you do not wish 'dosnames' to be set on an MS-DOS platform, you need to set the 'MTFEATURES' environment variable to a value that doesn't include 'dosnames'. You can also change the default setting by editing 'mktex.opt', but only if you use the 'mktex' shell scripts; the emulation programs don't consult 'mktex.opt'. 'fontmaps' Instead of deriving the location of a font in the destination tree from the location of the sources, the aliases and directory names from the Fontname distribution are used. (*note Introduction: (fontname)Top.). 'nomfdrivers' Let mktexpk and mktextfm create metafont driver files in a temporary directory. These will be used for just one metafont run and not installed permanently. 'nomode' Omit the directory level for the mode name; this is fine as long as you generate fonts for only one mode. 'stripsupplier' Omit the font supplier name directory level. 'striptypeface' Omit the font typeface name directory level. 'strip' Omit the font supplier and typeface name directory levels. This feature is deprecated in favour of 'stripsupplier' and 'striptypeface'. 'varfonts' When this option is enabled, fonts that would otherwise be written in system texmf tree go to the 'VARTEXFONTS' tree instead. The default value in 'kpathsea/Makefile.in' is '/var/tmp/texfonts'. The 'Linux File System Standard' recommends '/var/tex/fonts'. The 'varfonts' setting in 'MTFEATURES' is overridden by the 'USEVARTEXFONTS' environment variable: if set to '1', the feature is enabled, and if set to '0', the feature is disabled. 'texmfvar' Force generated files that would go into a system tree (as defined by 'SYSTEXMF') into 'TEXMFVAR'. Starting with teTeX-3.0, the variable 'TEXMFVAR' is always set. The 'varfonts' feature takes precedence if also set. The 'texmfvar' setting in 'MTFEATURES' is overridden by the 'USETEXMFVAR' environment variable: if set to '1', the feature is enabled, and if set to '0', the feature is disabled." } ], "examples": [], "see_also": [], "section_outline": [ { "name": "File: kpathsea.info, Node: Top, Next: Introduction, Up: (dir)", "lines": 1, "subsections": [] }, { "name": "Kpathsea library", "lines": 1, "subsections": [] }, { "name": "This manual documents the Kpathsea library for path searching. It", "lines": 18, "subsections": [] }, { "name": "File: kpathsea.info, Node: Introduction, Next: unixtex.ftp, Prev: Top, Up: Top", "lines": 1, "subsections": [] }, { "name": "1 Introduction", "lines": 1, "subsections": [] }, { "name": "This manual corresponds to version 6.3.3 of the Kpathsea library,", "lines": 26, "subsections": [] }, { "name": "Public License (LGPL), version 2.1 or (at your option) any later", "lines": 5, "subsections": [] }, { "name": "See accompanying files for the text of the GNU licenses, or", "lines": 13, "subsections": [] }, { "name": "File: kpathsea.info, Node: History, Up: Introduction", "lines": 1, "subsections": [ { "name": "1.1 History", "lines": 1 } ] }, { "name": "This section is for those people who are curious about how the library", "lines": 6, "subsections": [] }, { "name": "February 1990, but I may have done some work before then. In any case,", "lines": 1, "subsections": [] }, { "name": "Tim Morgan and I were jointly maintaining it for a time. (I should", "lines": 25, "subsections": [] }, { "name": "They weren't yet a library, though. I just kept things up to date with", "lines": 17, "subsections": [] }, { "name": "Neumann's help, implemented a way for TeX to get at all those neat", "lines": 6, "subsections": [] }, { "name": "Web2c with Kpathsea. After the release of a stable Web2c, I hope to be", "lines": 2, "subsections": [] }, { "name": "Unix by then, or that software patents haven't stopped software", "lines": 12, "subsections": [] }, { "name": "In 2009, Taco Hoekwater implemented a major rearrangement to make the", "lines": 5, "subsections": [] }, { "name": "File: kpathsea.info, Node: unixtex.ftp, Next: Security, Prev: Introduction, Up: Top", "lines": 1, "subsections": [] }, { "name": "2 'unixtex.ftp': Obtaining TeX", "lines": 16, "subsections": [] }, { "name": "However, unless you want to undertake the project of building your TeX", "lines": 9, "subsections": [] }, { "name": "File: kpathsea.info, Node: Security, Next: TeX directory structure, Prev: unixtex.ftp, Up: Top", "lines": 1, "subsections": [] }, { "name": "3 Security", "lines": 1, "subsections": [] }, { "name": "None of the programs in the TeX system require any special system", "lines": 48, "subsections": [] }, { "name": "File: kpathsea.info, Node: TeX directory structure, Next: Path searching, Prev: Security, Up: Top", "lines": 1, "subsections": [] }, { "name": "4 TeX directory structure", "lines": 1, "subsections": [] }, { "name": "This section describes the default installation hierarchy of the", "lines": 76, "subsections": [] }, { "name": "File: kpathsea.info, Node: Path searching, Next: TeX support, Prev: TeX directory structure, Up: Top", "lines": 1, "subsections": [] }, { "name": "5 Path searching", "lines": 1, "subsections": [] }, { "name": "This chapter describes the generic path searching mechanism Kpathsea", "lines": 5, "subsections": [] }, { "name": "German, ...) as part of the TeX Live guide; see", "lines": 11, "subsections": [] }, { "name": "File: kpathsea.info, Node: Searching overview, Next: Path sources, Up: Path searching", "lines": 1, "subsections": [ { "name": "5.1 Searching overview", "lines": 54 } ] }, { "name": "Kpathsea simply checks if that file exists, with a fallback to a", "lines": 14, "subsections": [] }, { "name": "File: kpathsea.info, Node: Path sources, Next: Path expansion, Prev: Searching overview, Up: Path searching", "lines": 1, "subsections": [ { "name": "5.2 Path sources", "lines": 29 } ] }, { "name": "File: kpathsea.info, Node: Config files, Up: Path sources", "lines": 93, "subsections": [] }, { "name": "Kpathsea warns if the program name contains a path separator or other", "lines": 14, "subsections": [] }, { "name": "File: kpathsea.info, Node: Path expansion, Next: Casefolding search, Prev: Path sources, Up: Path searching", "lines": 1, "subsections": [ { "name": "5.3 Path expansion", "lines": 1 } ] }, { "name": "Kpathsea recognizes certain special characters and constructions in", "lines": 16, "subsections": [] }, { "name": "File: kpathsea.info, Node: Default expansion, Next: Variable expansion, Up: Path expansion", "lines": 45, "subsections": [] }, { "name": "File: kpathsea.info, Node: Variable expansion, Next: Tilde expansion, Prev: Default expansion, Up: Path expansion", "lines": 12, "subsections": [] }, { "name": "Shell variable values cannot be seen by Kpathsea, i.e., ones defined", "lines": 16, "subsections": [] }, { "name": "File: kpathsea.info, Node: Tilde expansion, Next: Brace expansion, Prev: Variable expansion, Up: Path expansion", "lines": 21, "subsections": [] }, { "name": "File: kpathsea.info, Node: Brace expansion, Next: KPSEDOT expansion, Prev: Tilde expansion, Up: Path expansion", "lines": 23, "subsections": [] }, { "name": "File: kpathsea.info, Node: KPSEDOT expansion, Next: Subdirectory expansion, Prev: Brace expansion, Up: Path expansion", "lines": 1, "subsections": [] }, { "name": "When 'KPSEDOT' is defined in the environment, it names a directory that", "lines": 5, "subsections": [] }, { "name": "File: kpathsea.info, Node: Subdirectory expansion, Prev: KPSEDOT expansion, Up: Path expansion", "lines": 1, "subsections": [] }, { "name": "Two or more consecutive slashes in a path element following a directory", "lines": 22, "subsections": [] }, { "name": "That is to say, the 'stnlink' field in the 'stat' structure will be", "lines": 21, "subsections": [] }, { "name": "File: kpathsea.info, Node: Casefolding search, Next: Filename database, Prev: Path expansion, Up: Path searching", "lines": 1, "subsections": [ { "name": "5.4 Casefolding search", "lines": 1 } ] }, { "name": "In Kpathsea version 6.3.0 (released with TeX Live 2018), a new fallback", "lines": 14, "subsections": [] }, { "name": "File: kpathsea.info, Node: Casefolding rationale, Next: Casefolding examples, Up: Casefolding search", "lines": 1, "subsections": [] }, { "name": "The purpose of the fallback casefolding search is to ease moving complex", "lines": 2, "subsections": [] }, { "name": "Macs be case-insensitive some years ago, and this has exacerbated a", "lines": 2, "subsections": [] }, { "name": "It works on the Mac but if the document is transferred and run on a", "lines": 9, "subsections": [] }, { "name": "Windows, where (for practical purposes) all file names are", "lines": 5, "subsections": [] }, { "name": "File: kpathsea.info, Node: Casefolding examples, Prev: Casefolding rationale, Up: Casefolding search", "lines": 1, "subsections": [] }, { "name": "The casefolding implementation prefers exact matches to casefolded", "lines": 1, "subsections": [] }, { "name": "Backward compatibility is not perfect, however, as a casefolded match", "lines": 26, "subsections": [] }, { "name": "Also (as expected), searching for 'FOOBAR.TEX' (or whatever variation)", "lines": 12, "subsections": [] }, { "name": "Perhaps unexpectedly, searching for all 'foobar.tex' or 'FooBar.tex'", "lines": 4, "subsections": [] }, { "name": "Because Kpathsea never searches the disk in the big system directory,", "lines": 6, "subsections": [] }, { "name": "TeX Live, that is the 'texmf-local' and 'texmf-dist' trees (also", "lines": 1, "subsections": [] }, { "name": "The rationale for this is that in practice, case mangling happens with", "lines": 16, "subsections": [] }, { "name": "Kpathsea would be a lot of error-prone trouble for something that is", "lines": 18, "subsections": [] }, { "name": "File: kpathsea.info, Node: Filename database, Next: Invoking kpsewhich, Prev: Casefolding search, Up: Path searching", "lines": 1, "subsections": [ { "name": "5.5 Filename database ('ls-R')", "lines": 1 } ] }, { "name": "Kpathsea goes to some lengths to minimize disk accesses for searches", "lines": 20, "subsections": [] }, { "name": "File: kpathsea.info, Node: ls-R, Next: Filename aliases, Up: Filename database", "lines": 1, "subsections": [] }, { "name": "You can put one at the root of each TeX installation hierarchy you wish", "lines": 57, "subsections": [] }, { "name": "In TeX Live, the most notable case of this is the 'TEXMFHOME' tree, to", "lines": 10, "subsections": [] }, { "name": "File: kpathsea.info, Node: Filename aliases, Next: Database format, Prev: ls-R, Up: Filename database", "lines": 1, "subsections": [] }, { "name": "For example, suppose a TeX document was created using a DOS system and", "lines": 20, "subsections": [] }, { "name": "File: kpathsea.info, Node: Database format, Prev: Filename aliases, Up: Filename database", "lines": 1, "subsections": [] }, { "name": "The format is that generated by GNU (and most other) 'ls' programs given", "lines": 35, "subsections": [] }, { "name": "File: kpathsea.info, Node: Invoking kpsewhich, Prev: Filename database, Up: Path searching", "lines": 1, "subsections": [ { "name": "5.6 'kpsewhich': Standalone path searching", "lines": 1 } ] }, { "name": "The Kpsewhich program exercises the path searching functionality", "lines": 20, "subsections": [] }, { "name": "File: kpathsea.info, Node: Path searching options, Next: Specially-recognized files, Up: Invoking kpsewhich", "lines": 1, "subsections": [] }, { "name": "Kpsewhich looks up each non-option argument on the command line as a", "lines": 238, "subsections": [] }, { "name": "File: kpathsea.info, Node: Specially-recognized files, Next: Auxiliary tasks, Prev: Path searching options, Up: Invoking kpsewhich", "lines": 44, "subsections": [] }, { "name": "File: kpathsea.info, Node: Auxiliary tasks, Next: Standard options, Prev: Specially-recognized files, Up: Invoking kpsewhich", "lines": 82, "subsections": [] }, { "name": "File: kpathsea.info, Node: Standard options, Prev: Auxiliary tasks, Up: Invoking kpsewhich", "lines": 8, "subsections": [] }, { "name": "File: kpathsea.info, Node: TeX support, Next: Programming, Prev: Path searching, Up: Top", "lines": 1, "subsections": [] }, { "name": "6 TeX support", "lines": 1, "subsections": [] }, { "name": "Although the basic features in Kpathsea can be used for any type of path", "lines": 7, "subsections": [] }, { "name": "Indeed, many of the purportedly generic path searching features were", "lines": 5, "subsections": [] }, { "name": "Searches are based solely on names of files, not their contents--if a GF", "lines": 10, "subsections": [] }, { "name": "File: kpathsea.info, Node: Supported file formats, Next: File lookup, Up: TeX support", "lines": 1, "subsections": [ { "name": "6.1 Supported file formats", "lines": 1 } ] }, { "name": "Kpathsea has support for a number of file types. Each file type has a", "lines": 250, "subsections": [] }, { "name": "File: kpathsea.info, Node: File lookup, Next: Glyph lookup, Prev: Supported file formats, Up: TeX support", "lines": 1, "subsections": [ { "name": "6.2 File lookup", "lines": 1 } ] }, { "name": "This section describes how Kpathsea searches for most files (bitmap font", "lines": 34, "subsections": [] }, { "name": "File: kpathsea.info, Node: Glyph lookup, Next: Suppressing warnings, Prev: File lookup, Up: TeX support", "lines": 1, "subsections": [ { "name": "6.3 Glyph lookup", "lines": 1 } ] }, { "name": "This section describes how Kpathsea searches for a bitmap font in GF or", "lines": 28, "subsections": [] }, { "name": "File: kpathsea.info, Node: Basic glyph lookup, Next: Fontmap, Up: Glyph lookup", "lines": 1, "subsections": [] }, { "name": "When Kpathsea looks for a bitmap font NAME at resolution DPI in a format", "lines": 14, "subsections": [] }, { "name": "File: kpathsea.info, Node: Fontmap, Next: Fallback font, Prev: Basic glyph lookup, Up: Glyph lookup", "lines": 1, "subsections": [] }, { "name": "If a bitmap font or metric file is not found with the original name (see", "lines": 45, "subsections": [] }, { "name": "Web2c distribution. It makes the old and new names of the LaTeX circle", "lines": 14, "subsections": [] }, { "name": "File: kpathsea.info, Node: Fallback font, Prev: Fontmap, Up: Glyph lookup", "lines": 1, "subsections": [] }, { "name": "If a bitmap font cannot be found or created at the requested size,", "lines": 2, "subsections": [] }, { "name": "Kpathsea looks first for a program-specific environment variable (e.g.,", "lines": 10, "subsections": [] }, { "name": "File: kpathsea.info, Node: Suppressing warnings, Next: mktex scripts, Prev: Glyph lookup, Up: TeX support", "lines": 1, "subsections": [ { "name": "6.4 Suppressing warnings", "lines": 1 } ] }, { "name": "Kpathsea provides a way to suppress selected usually-harmless warnings;", "lines": 30, "subsections": [] }, { "name": "File: kpathsea.info, Node: mktex scripts, Prev: Suppressing warnings, Up: TeX support", "lines": 1, "subsections": [ { "name": "6.5 'mktex' scripts", "lines": 1 } ] }, { "name": "If Kpathsea cannot otherwise find a file, for some file types it is", "lines": 7, "subsections": [] }, { "name": "Building all fonts in advance is therefore impractical, if not", "lines": 17, "subsections": [] }, { "name": "File: kpathsea.info, Node: mktex configuration, Next: mktex script names, Up: mktex scripts", "lines": 1, "subsections": [] }, { "name": "The list of file types and program names that can run an external", "lines": 5, "subsections": [ { "name": "--without-mktexfmt-default", "lines": 1, "long": "--without-mktexfmt-default" }, { "name": "--without-mktexmf-default", "lines": 1, "long": "--without-mktexmf-default" }, { "name": "--without-mktexocp-default", "lines": 1, "long": "--without-mktexocp-default" }, { "name": "--without-mktexofm-default", "lines": 1, "long": "--without-mktexofm-default" }, { "name": "--without-mktexpk-default", "lines": 1, "long": "--without-mktexpk-default" }, { "name": "--without-mktextfm-default", "lines": 1, "long": "--without-mktextfm-default" }, { "name": "--with-mktextex-default", "lines": 112, "long": "--with-mktextex-default" } ] }, { "name": "File: kpathsea.info, Node: mktex script names, Next: mktex script arguments, Prev: mktex configuration, Up: mktex scripts", "lines": 1, "subsections": [] }, { "name": "The following table shows the default name of the script for each of the", "lines": 25, "subsections": [] }, { "name": "These names can be overridden by an environment variable specific to the", "lines": 9, "subsections": [] }, { "name": "Otherwise, nothing is written. The name 'missfont.log' is overridden by", "lines": 2, "subsections": [] }, { "name": "File: kpathsea.info, Node: mktex script arguments, Prev: mktex script names, Up: mktex scripts", "lines": 1, "subsections": [] }, { "name": "The first argument to a 'mktex' script is always the name of the file to", "lines": 20, "subsections": [] }, { "name": "File: kpathsea.info, Node: Programming, Next: Reporting bugs, Prev: TeX support, Up: Top", "lines": 1, "subsections": [] }, { "name": "7 Programming", "lines": 1, "subsections": [] }, { "name": "Introduction::, for the conditions under which you may do so (in short,", "lines": 9, "subsections": [] }, { "name": "File: kpathsea.info, Node: Programming overview, Next: Calling sequence, Up: Programming", "lines": 1, "subsections": [ { "name": "7.1 Programming overview", "lines": 1 } ] }, { "name": "Aside from this manual, your best source of information is the source to", "lines": 30, "subsections": [] }, { "name": "Kpathsea header, as it provides symbols used in the other headers. Note", "lines": 5, "subsections": [] }, { "name": "Kpathsea has support for looking up Dvips config files, even though no", "lines": 11, "subsections": [] }, { "name": "File: kpathsea.info, Node: Calling sequence, Next: Program-specific files, Prev: Programming overview, Up: Programming", "lines": 1, "subsections": [ { "name": "7.2 Calling sequence", "lines": 1 } ] }, { "name": "The typical way to use Kpathsea in your program goes something like", "lines": 116, "subsections": [] }, { "name": "File: kpathsea.info, Node: Program-specific files, Next: Programming with config files, Prev: Calling sequence, Up: Programming", "lines": 1, "subsections": [ { "name": "7.3 Program-specific files", "lines": 1 } ] }, { "name": "Many programs will need to find some configuration files. Kpathsea", "lines": 16, "subsections": [] }, { "name": "File: kpathsea.info, Node: Programming with config files, Prev: Program-specific files, Up: Programming", "lines": 1, "subsections": [ { "name": "7.4 Programming with config files", "lines": 1 } ] }, { "name": "You can (and probably should) use the same 'texmf.cnf' configuration", "lines": 27, "subsections": [] }, { "name": "File: kpathsea.info, Node: Reporting bugs, Next: Index, Prev: Programming, Up: Top", "lines": 1, "subsections": [] }, { "name": "8 Reporting bugs", "lines": 1, "subsections": [] }, { "name": "If you have problems or suggestions, please report them to", "lines": 14, "subsections": [] }, { "name": "File: kpathsea.info, Node: Bug checklist, Next: Mailing lists, Up: Reporting bugs", "lines": 1, "subsections": [ { "name": "8.1 Bug checklist", "lines": 1 } ] }, { "name": "Before reporting a bug, please check below to be sure it isn't already", "lines": 64, "subsections": [] }, { "name": "File: kpathsea.info, Node: Mailing lists, Next: Debugging, Prev: Bug checklist, Up: Reporting bugs", "lines": 1, "subsections": [ { "name": "8.2 Mailing lists", "lines": 1 } ] }, { "name": "Web2c and Kpathsea in general are discussed on the mailing list", "lines": 12, "subsections": [] }, { "name": "File: kpathsea.info, Node: Debugging, Next: Logging, Prev: Mailing lists, Up: Reporting bugs", "lines": 1, "subsections": [ { "name": "8.3 Debugging", "lines": 1 } ] }, { "name": "Kpathsea provides a number of runtime debugging options, detailed below", "lines": 104, "subsections": [] }, { "name": "File: kpathsea.info, Node: Logging, Next: Common problems, Prev: Debugging, Up: Reporting bugs", "lines": 1, "subsections": [ { "name": "8.4 Logging", "lines": 1 } ] }, { "name": "Kpathsea can record the time and filename found for each successful", "lines": 25, "subsections": [] }, { "name": "Only filenames that are absolute are recorded, to preserve some", "lines": 10, "subsections": [] }, { "name": "File: kpathsea.info, Node: Common problems, Prev: Logging, Up: Reporting bugs", "lines": 1, "subsections": [ { "name": "8.5 Common problems", "lines": 1 } ] }, { "name": "Here are some common problems with configuration, compilation, linking,", "lines": 9, "subsections": [] }, { "name": "File: kpathsea.info, Node: Unable to find files, Next: Slow path searching, Up: Common problems", "lines": 1, "subsections": [] }, { "name": "If a program complains it cannot find fonts (or other input files), any", "lines": 44, "subsections": [] }, { "name": "File: kpathsea.info, Node: Slow path searching, Next: Unable to generate fonts, Prev: Unable to find files, Up: Common problems", "lines": 1, "subsections": [] }, { "name": "If your program takes an excessively long time to find fonts or other", "lines": 24, "subsections": [] }, { "name": "File: kpathsea.info, Node: Unable to generate fonts, Next: TeX or Metafont failing, Prev: Slow path searching, Up: Common problems", "lines": 1, "subsections": [] }, { "name": "Metafont outputs fonts in bitmap format, tuned for a particular device", "lines": 39, "subsections": [] }, { "name": "Then copy the 'plain.base' file from the current directory to where the", "lines": 7, "subsections": [] }, { "name": "File: kpathsea.info, Node: TeX or Metafont failing, Prev: Unable to generate fonts, Up: Common problems", "lines": 1, "subsections": [] }, { "name": "If TeX or Metafont get a segmentation fault or otherwise fail while", "lines": 19, "subsections": [] }, { "name": "File: kpathsea.info, Node: Index, Prev: Reporting bugs, Up: Top", "lines": 1, "subsections": [] }, { "name": "Index", "lines": 920, "subsections": [] } ], "sections": { "File: kpathsea.info, Node: Top, Next: Introduction, Up: (dir)": { "content": "", "subsections": [] }, "Kpathsea library": { "content": "", "subsections": [] }, "This manual documents the Kpathsea library for path searching. It": { "content": "corresponds to version 6.3.3, released in April 2021.\n\n* Menu:\n\n* Introduction:: Overview and history.\n\n* unixtex.ftp:: Obtaining TeX software.\n* Security:: Who can write what files, etc.\n* TeX directory structure:: Managing the horde of TeX input files.\n\n* Path searching:: How filename lookups work.\n* TeX support:: Special support for TeX-related file lookups.\n\n* Programming:: How to use Kpathsea features in your program.\n\n* Reporting bugs:: Where and how to report bugs.\n* Index:: General index.\n", "subsections": [] }, "File: kpathsea.info, Node: Introduction, Next: unixtex.ftp, Prev: Top, Up: Top": { "content": "", "subsections": [] }, "1 Introduction": { "content": "", "subsections": [] }, "This manual corresponds to version 6.3.3 of the Kpathsea library,": { "content": "released in April 2021.\n\nThe library's fundamental purpose is to return a filename from a list\nof directories specified by the user, similar to what shells do when\nlooking up program names to execute.\n\nThe following software, all of which is maintained in parallel, uses\nthis library:\n\n* Dviljk (see the 'dvilj' man page)\n* Dvipsk (*note (dvips)::)\n* GNU font utilities (*note (fontu)::)\n* Web2c (*note (web2c)::)\n* Xdvik (see the 'xdvi' man page)\n\nOther software that we do not maintain also uses it.\n\nKpathsea is now maintained as part of the TeX Live distribution\n(), which includes several more Kpathsea-using\nprograms. For information on configuration, building, installing, and\nmore, *note (tlbuild)::.\n\nThe library is still actively maintained. If you have comments or\nsuggestions, please send along (*note Reporting bugs::).\n\nThe Kpathsea library is distributed under the GNU Library General", "subsections": [] }, "Public License (LGPL), version 2.1 or (at your option) any later": { "content": "version. In short, this means if you write a program using the library,\nyou must (offer to) distribute the source to the library, along with any\nchanges you have made, and allow anyone to modify the library source and\ndistribute their modifications. It does not mean you have to distribute\nthe source to your program using the library, although we hope you will.", "subsections": [] }, "See accompanying files for the text of the GNU licenses, or": { "content": ".\n\nIf you know enough about TeX to be reading this manual, then you (or\nyour institution) should consider joining the TeX Users Group (if you're\nalready a member, thanks!). TUG produces the periodical 'TUGboat',\nsponsors an annual meeting and publishes the proceedings, and arranges\ncourses on TeX for all levels of users throughout the world. See\n for information.\n\n* Menu:\n\n* History::\n", "subsections": [] }, "File: kpathsea.info, Node: History, Up: Introduction": { "content": "", "subsections": [ { "name": "1.1 History", "content": "" } ] }, "This section is for those people who are curious about how the library": { "content": "came about. If you like to read historical accounts of software, we\nurge you to seek out the GNU Autoconf manual and the \"Errors of TeX\"\npaper by Don Knuth, published in his book 'Digital Typography', among\nother places.\n\n[Karl writes.] My first ChangeLog entry for Web2c seems to be", "subsections": [] }, "February 1990, but I may have done some work before then. In any case,": { "content": "", "subsections": [] }, "Tim Morgan and I were jointly maintaining it for a time. (I should": { "content": "mention here that Tim had made Web2c into a real distribution long\nbefore I had ever used it or even heard of it, and Tom Rokicki did the\noriginal implementation. When I started, I was using 'pxp' and 'pc' on\nVAX 11/750's and the hot new Sun 2 machines.)\n\nIt must have been later in 1990 and 1991 that I started working on\n'TeX for the Impatient'. Dvips, Xdvi, Web2c, and the GNU fontutils\n(which I was also writing at the time) all used different environment\nvariables, and, more importantly, had different bugs in their path\nsearching. This became extremely painful, as I was stressing everything\nto the limit working on the book. I also desperately wanted to\nimplement subdirectory searching, since I couldn't stand putting\neverything in one big directory, and also couldn't stand having to\nexplicitly specify 'cm', 'pandora', ... in a path.\n\nIn the first incarnation, I just hacked separately on each\nprogram--that was the original subdirectory searching code in both Xdvi\nand Dvips. That is, I tried to go with the flow in each program, rather\nthan changing the program's calling sequences to conform to new\nroutines.\n\nThen, as bugs inevitably appeared, I found I was fixing the same\nthing three times (Web2c and fontutils were already sharing code, since\nI maintained both of those--there was no Dvipsk or Xdvik or Dviljk at\nthis point). After a while, I finally started sharing source files.", "subsections": [] }, "They weren't yet a library, though. I just kept things up to date with": { "content": "shell scripts. (I was developing on a 386 running ISC 2.2 at the time,\nand so didn't have symbolic links. An awful experience.)\n\nThe ChangeLogs for Xdvik and Dvipsk record initial releases of those\ndistributions in May and June 1992. I think it was because I was tired\nof the different configuration strategies of each program, not so much\nbecause of the path searching. Autoconf was being developed by David\nMacKenzie and others, and I was adapting it to TeX and friends.\n\nI started to make a separate library that other programs could link\nwith on my birthday in April 1993, according to the ChangeLog. I don't\nremember exactly why I finally took the time to make it a separate\nlibrary; a conversation with david zuhn initiated it. Just seemed like\nit was time.\n\nDviljk got started in March 1994 after I bought a Laserjet 4.\n(Kpathsea work got suspended while Norm Walsh and I, with Gustaf", "subsections": [] }, "Neumann's help, implemented a way for TeX to get at all those neat": { "content": "builtin LJ4 fonts ... such a treat to have something to typeset in\nbesides Palatino!)\n\nBy spring of 1995, I had implemented just about all the\npath-searching features in Kpathsea that I plan to, driven beyond my\ninitial goals by Thomas Esser and others. I then started to integrate", "subsections": [] }, "Web2c with Kpathsea. After the release of a stable Web2c, I hope to be": { "content": "able to stop development, and turn most of my attention back to making\nfonts for GNU. (Always assuming Microst hasn't completely obliterated", "subsections": [] }, "Unix by then, or that software patents haven't stopped software": { "content": "development by anybody smaller than a company with a\nmillion-dollar-a-year legal budget. Which is actually what I think is\nlikely to happen, but that's another story...)\n\n[Olaf writes.] At the end of 1997, Unix is still alive and kicking,\nindividuals still develop software, and Web2c development still\ncontinues. Karl had been looking for some time for someone to take up\npart of the burden, and I volunteered.\n\n[Karl writes again.] Indeed, time goes on. As of 2006 or so, Olaf's\navailable time for Kpathsea was reduced, and I started taking overall\ncare of it again, although I did not do any significant new development.", "subsections": [] }, "In 2009, Taco Hoekwater implemented a major rearrangement to make the": { "content": "library suitable for use within the MetaPost library (*note Programming\noverview::). Also, for some years now, Peter Breitenlohner has made\nmany improvements to the infrastructure and kept it up-to-date with\nrespect to the overall TeX Live build, where Kpathsea is now maintained.\n", "subsections": [] }, "File: kpathsea.info, Node: unixtex.ftp, Next: Security, Prev: Introduction, Up: Top": { "content": "", "subsections": [] }, "2 'unixtex.ftp': Obtaining TeX": { "content": "This is , a.k.a.\n, last updated 29 February 2020. Email\n with comments or questions.\n\nThe principal free TeX distribution for Unix-like systems is TeX\nLive, on the web at . The pages there describe\nmany ways to acquire and/or build TeX, over the Internet or on physical\nmedia, both the sources and precompiled binaries for many systems,\neither standalone or as part of various operating system distributions.\n\nWeb2c, Kpathsea, Dvips, and Dviljk, among others, are no longer\nreleased as a separate packages. Their sources are now maintained as\npart of TeX Live.\n\nThe host ftp.cs.stanford.edu is the original source for the files for\nwhich Donald Knuth is directly responsible: 'tex.web', 'plain.tex', etc.", "subsections": [] }, "However, unless you want to undertake the project of building your TeX": { "content": "system from scratch, it is more reliable and less work to retrieve these\nfiles as part of a larger package.\n\nIn any case, the Stanford ftp site is not the canonical source for\nanything except what was created as part of Knuth's original TeX, so do\nnot rely on any other files available there being up-to-date. The best\nplace to check for up-to-date files is CTAN (the Comprehensive TeX\nArchive Network), .\n", "subsections": [] }, "File: kpathsea.info, Node: Security, Next: TeX directory structure, Prev: unixtex.ftp, Up: Top": { "content": "", "subsections": [] }, "3 Security": { "content": "", "subsections": [] }, "None of the programs in the TeX system require any special system": { "content": "privileges, so there's no first-level security concern of people gaining\nillegitimate root access.\n\nA TeX document, however, can write to arbitrary files, e.g.,\n'~/.rhosts', and thus an unwitting user who runs TeX on a random\ndocument is vulnerable to a trojan horse attack. This loophole is\nclosed by default, but you can be permissive if you so desire in\n'texmf.cnf'. *Note (web2c)tex invocation::. MetaPost has the same\nissue.\n\nDvips, Xdvi, and TeX can also execute shell commands under some\ncircumstances. To disable this, see the '-R' option in *note\n(dvips)Option details::, the xdvi man page, and *note (web2c)tex\ninvocation::, respectively.\n\nAnother security issue arises because it's very useful--almost\nnecessary--to make arbitrary fonts on user demand with 'mktexpk' and\nfriends. Where do these files get installed? By default, the 'mktexpk'\ndistributed with Kpathsea assumes a world-writable '/var/tmp' directory;\nthis is a simple and convenient approach, but it may not suit your\nsituation because it means that a local cache of fonts is created on\nevery machine.\n\nTo avoid this duplication, many people consider a shared, globally\nwritable font tree desirable, in spite of the potential security\nproblems. To do this you should change the value of 'VARTEXFONTS' in\n'texmf.cnf' to refer to some globally known directory. *Note mktex\nconfiguration::.\n\nThe first restriction you can apply is to make newly-created\ndirectories under 'texmf' be append-only with an option in 'mktex.cnf'.\n*Note mktex configuration::.\n\nAnother approach is to establish a group (or user) for TeX files,\nmake the 'texmf' tree writable only to that group (or user), and make\n'mktexpk' et al. setgid to that group (or setuid to that user). Then\nusers must invoke the scripts to install things. (If you're worried\nabout the inevitable security holes in scripts, then you could write a C\nwrapper to exec the script.)\n\nThe 'mktex...' scripts install files with the same read and write\npermissions as the directory they are installed in. The executable,\nsgid, suid, and sticky bits are always cleared.\n\nAny directories created by the 'mktex...' scripts have the same\npermissions as their parent directory, unless the 'appendonlydir'\nfeature is used, in which case the sticky bit is always set.\n", "subsections": [] }, "File: kpathsea.info, Node: TeX directory structure, Next: Path searching, Prev: Security, Up: Top": { "content": "", "subsections": [] }, "4 TeX directory structure": { "content": "", "subsections": [] }, "This section describes the default installation hierarchy of the": { "content": "distribution. It conforms to both the GNU coding standards and the TeX\ndirectory structure (TDS) standard. For rationale and further\nexplanation, please see those documents. The GNU document is available\nfrom . The TDS document is available\nfrom (*note unixtex.ftp::).\n\nIn short, here is a skeleton of the default directory structure,\nextracted from the TDS document:\n\nPREFIX/ installation root ('/usr/local' by default)\nbin/ executables\nman/ man pages\ninclude/ C header files\ninfo/ GNU info files\nlib/ libraries ('libkpathsea.*')\nshare/ architecture-independent files\ntexmf/ TDS root\nbibtex/ BibTeX input files\nbib/ BibTeX databases\nbase/ base distribution (e.g., 'xampl.bib')\nmisc/ single-file databases\nPKG/ name of a package\nbst/ BibTeX style files\nbase/ base distribution (e.g., 'plain.bst', 'acm.bst')\nmisc/ single-file styles\nPKG/ name of a package\ndoc/ additional documentation\ndvips/ '.pro', '.ps', 'psfonts.map'\nfonts/ font-related files\nTYPE/ file type (e.g., 'tfm', 'pk')\nMODE/ type of output device (types 'pk' and 'gf' only)\nSUPPLIER/ name of a font supplier (e.g., 'public')\nTYPEFACE/ name of a typeface (e.g., 'cm')\ndpiNNN/ font resolution (types 'pk' and 'gf' only)\nmetafont/ Metafont (non-font) input files\nbase/ base distribution (e.g., 'plain.mf')\nmisc/ single-file packages (e.g., 'modes.mf')\nPKG/ name of a package (e.g., 'mfpic')\nmetapost/ MetaPost input files\nbase/ base distribution (e.g., 'plain.mp')\nmisc/ single-file packages\nPKG/ name of a package\nsupport/ support files for MetaPost-related utilities (e.g., 'trfonts.map')\nmft/ 'MFT' inputs (e.g., 'plain.mft')\ntex/ TeX input files\nFORMAT/ name of a format (e.g., 'plain')\nbase/ base distribution for FORMAT (e.g., 'plain.tex')\nmisc/ single-file packages (e.g., 'webmac.tex')\nlocal/ local additions to or local configuration files for FORMAT\nPKG/ name of a package (e.g., 'graphics', 'mfnfss')\ngeneric/ format-independent packages\nhyphen/ hyphenation patterns (e.g., 'hyphen.tex')\nimages/ image input files (e.g., Encapsulated PostScript)\nmisc/ single-file format-independent packages (e.g., 'null.tex').\nPKG/ name of a package (e.g., 'babel')\nweb2c/ implementation-dependent files ('.pool', '.fmt', 'texmf.cnf', etc.)\n\nSome concrete examples for most file types:\n\n/usr/local/bin/tex\n/usr/local/man/man1/xdvi.1\n/usr/local/info/kpathsea.info\n/usr/local/lib/libkpathsea.a\n/usr/local/share/texmf/bibtex/bst/base/plain.bst\n/usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk\n/usr/local/share/texmf/fonts/source/public/pandora/pnr10.mf\n/usr/local/share/texmf/fonts/tfm/public/cm/cmr10.tfm\n/usr/local/share/texmf/fonts/type1/adobe/utopia/putr.pfa\n/usr/local/share/texmf/metafont/base/plain.mf\n/usr/local/share/texmf/metapost/base/plain.mp\n/usr/local/share/texmf/tex/plain/base/plain.tex\n/usr/local/share/texmf/tex/generic/hyphen/hyphen.tex\n/usr/local/share/texmf/web2c/tex.pool\n/usr/local/share/texmf/web2c/tex.fmt\n/usr/local/share/texmf/web2c/texmf.cnf\n", "subsections": [] }, "File: kpathsea.info, Node: Path searching, Next: TeX support, Prev: TeX directory structure, Up: Top": { "content": "", "subsections": [] }, "5 Path searching": { "content": "", "subsections": [] }, "This chapter describes the generic path searching mechanism Kpathsea": { "content": "provides. For information about searching for particular file types\n(e.g., TeX fonts), see the next chapter.\n\nThis section, with minor differences, has been translated into\nseveral other languages (Chinese, Spanish, Russian, Japanese, French,", "subsections": [] }, "German, ...) as part of the TeX Live guide; see": { "content": " for links.\n\n* Menu:\n\n* Searching overview:: Basic scheme for searching.\n* Path sources:: Where search paths can be defined.\n* Path expansion:: Special constructs in search paths.\n* Casefolding search:: Fallback to case-insensitive search.\n* Filename database:: Using an externally-built list to search.\n* Invoking kpsewhich:: Standalone path lookup.\n", "subsections": [] }, "File: kpathsea.info, Node: Searching overview, Next: Path sources, Up: Path searching": { "content": "", "subsections": [ { "name": "5.1 Searching overview", "content": "A \"search path\" is a colon-separated list of \"path elements\", which are\ndirectory names with a few extra frills. A search path can come from (a\ncombination of) many sources; see below. To look up a file 'foo' along\na path '.:/dir', Kpathsea checks each element of the path in turn: first\n'./foo', then '/dir/foo', returning the first match (or possibly all\nmatches).\n\nThe \"colon\" and \"slash\" mentioned here aren't necessarily ':' and '/'\non non-Unix systems. Kpathsea tries to adapt to other operating\nsystems' conventions.\n\nTo check a particular path element E, Kpathsea first sees if a\nprebuilt database (*note Filename database::) applies to E, i.e., if the\ndatabase is in a directory that is a prefix of E. If so, the path\nspecification is matched against the contents of the database.\n\nIf the database does not exist, or does not apply to this path\nelement, or contains no matches, the filesystem is searched (if this was\nnot forbidden by the specification with '!!' and if the file being\nsearched for must exist). Kpathsea constructs the list of directories\nthat correspond to this path element, and then checks in each for the\nfile being searched for. (To help speed future lookups of files in the\nsame directory, the directory in which a file is found is floated to the\ntop of the directory list.)\n\nThe \"file must exist\" condition comes into play with VF files and\ninput files read by the TeX '\\openin' command. These files might very\nwell not exist (consider 'cmr10.vf'), and so it would be wrong to search\nthe disk for them. Therefore, if you fail to update 'ls-R' when you\ninstall a new VF file, it will not be found.\n\nEach path element is checked in turn: first the database, then the\ndisk. If a match is found, the search stops and the result is returned\n(unless the search explicitly requested all matches). This avoids\npossibly-expensive processing of path specifications that are never\nneeded on a particular run.\n\nOn Unix-like systems, if no match is found by any of the above, and\nthe path element allows checking the filesystem (per the above), a final\ncheck is made for a case-insensitive match. Thus, looking for a name\nlike './FooBar.TeX' will match a file './foobar.tex', and vice versa.\nThis is not done on Windows. *Note Casefolding search::.\n\nAlthough the simplest and most common path element is a directory\nname, Kpathsea supports additional features in search paths: layered\ndefault values, environment variable names, config file values, users'\nhome directories, and recursive subdirectory searching. Thus, we say\nthat Kpathsea \"expands\" a path element, meaning transforming all the\nmagic specifications into the basic directory name or names. This\nprocess is described in the sections below. It happens in the same\norder as the sections.\n\nException to all of the above: If the filename being searched for is\nabsolute or explicitly relative, i.e., starts with '/' or './' or '../'," } ] }, "Kpathsea simply checks if that file exists, with a fallback to a": { "content": "casefolding match if needed and enabled, as described above.\n\nOrdinarily, if Kpathsea tries to access a file or directory that\ncannot be read, it gives a warning. This is so you will be alerted to\ndirectories or files that accidentally lack any read permission (for\nexample, a 'lost+found' directory). If you prefer not to see these\nwarnings, include the value 'readable' in the 'TEXHUSH' environment\nvariable or config file value.\n\nThis generic path searching algorithm is implemented in\n'kpathsea/pathsearch.c'. It is employed by a higher-level algorithm\nwhen searching for a file of a particular type (*note File lookup::, and\n*note Glyph lookup::).\n", "subsections": [] }, "File: kpathsea.info, Node: Path sources, Next: Path expansion, Prev: Searching overview, Up: Path searching": { "content": "", "subsections": [ { "name": "5.2 Path sources", "content": "A search path or other configuration value can come from many sources.\nIn the order in which Kpathsea looks for them:\n\n1. A command-line option such as '--cnf-line', available in\n'kpsewhich' and most TeX engines. *Note Path searching options::.\n\nA user-set environment variable, e.g., 'TEXINPUTS'. Environment\nvariables with an underscore and the program name appended\noverride; for example, 'TEXINPUTSlatex' overrides 'TEXINPUTS' if\nthe program being run is named 'latex'.\n\n2. A program-specific configuration file, e.g., an 'S /a:/b' line in\nDvips' 'config.ps' (*note (dvips)Config files::).\n\n3. A line in a Kpathsea configuration file 'texmf.cnf', e.g.,\n'TEXINPUTS=/c:/d' (see below).\n\n4. The compile-time default (specified in 'kpathsea/paths.h').\n\nYou can see each of these values for a given search path by using the\ndebugging options (*note Debugging::).\n\nThese sources may be combined via default expansion (*note Default\nexpansion::).\n\n* Menu:\n\n* Config files:: Kpathsea's runtime config files (texmf.cnf).\n" } ] }, "File: kpathsea.info, Node: Config files, Up: Path sources": { "content": "As mentioned above, Kpathsea reads \"runtime configuration files\" named\n'texmf.cnf' for search path and other definitions. The search path used\nto look for these configuration files is named 'TEXMFCNF', and is\nconstructed in the usual way, as described above, except that\nconfiguration files cannot be used to define the path, naturally; also,\nan 'ls-R' database is not used to search for them.\n\nKpathsea reads all 'texmf.cnf' files in the search path, not just\nthe first one found; definitions in earlier files override those in\nlater files. Thus, if the search path is '.:$TEXMF', values from\n'./texmf.cnf' override those from '$TEXMF/texmf.cnf'.\n\nIf Kpathsea cannot find any 'texmf.cnf' file, it reports a warning\nincluding all the directories it checked. If you don't want to see this\nwarning, set the environment variable 'KPATHSEAWARNING' to the single\ncharacter '0' (zero, not oh).\n\nWhile (or instead of) reading this description, you may find it\nhelpful to look at the distributed 'texmf.cnf', which uses or at least\nmentions most features. The format of 'texmf.cnf' files follows:\n\n* Comments start with '%', either at the beginning of a line or\npreceded by whitespace, and continue to the end of the line. That\nis, similar to most shells, a '%' in the \"middle\" of a value does\nnot start a comment. Examples:\n\n% this is a comment\nvar = a%b % but the value of var will be \"a%b\"\n\n* Blank lines are ignored.\n\n* A '\\' at the end of a line acts as a continuation character, i.e.,\nthe next line is appended. Whitespace at the beginning of\ncontinuation lines is not ignored.\n\n* Each remaining line will look like:\n\nVARIABLE [. PROGNAME] [=] VALUE\n\nwhere the '=' and surrounding whitespace is optional.\n\n* The VARIABLE name may contain any character other than whitespace,\n'=', or '.', but sticking to 'A-Za-z' is safest.\n\n* If '.PROGNAME' is present (preceding spaces are ignored), the\ndefinition only applies if the program that is running is named\n(i.e., the last component of 'argv[0]' is) PROGNAME or\n'PROGNAME.{exe,bat,cmd,...}'. Most notably, this allows different\nflavors of TeX to have different search paths. The PROGNAME value\nis used literally, without variable or other expansions.\n\n* Considered as strings, VALUE may contain any character. However,\nin practice most 'texmf.cnf' values are related to path expansion,\nand since various special characters are used in expansion, such as\nbraces and commas, they cannot be used in directory names.\n\nThe '$VAR.PROG' feature is not available on the right-hand side;\ninstead, you must use an additional variable (see below for\nexample).\n\nA ';' in VALUE is translated to ':' if running under Unix, in order\nto have a single 'texmf.cnf' that can support both Unix and Windows\nsystems. This translation happens with any value, not just search\npaths, but fortunately in practice ';' is not needed in other\nvalues.\n\n* All definitions are read before anything is expanded, so you can\nuse variables before they are defined (like Make, unlike most other\nprograms).\n\nHere is a configuration file fragment illustrating most of these points:\n\n% TeX input files -- i.e., anything to be found by \\input or \\openin ...\nlatex209inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex//\nlatex2einputs = .:$TEXMF/tex/latex//:$TEXMF/tex//\nTEXINPUTS = .:$TEXMF/tex//\nTEXINPUTS.latex209 = $latex209inputs\nTEXINPUTS.latex2e = $latex2einputs\nTEXINPUTS.latex = $latex2einputs\n\nThis format has some similarity to Bourne shell scripts--change the\ncomment character to '#', disallow spaces around the '=', and get rid of\nthe '.NAME' convention, and it could be run through the shell. However,\nthere seemed little advantage in this, since all the information would\nhave to passed back to Kpathsea and parsed there anyway, since the 'sh'\nprocess couldn't affect its parent's environment.\n\nThe combination of spaces being ignored before the '.' of a program\nname qualifer and the optional '=' for the assignment has an unexpected\nconsequence: if the value begins with a literal '.' and the '=' is\nomitted, the intended value is interpreted as a program name. For\nexample, a line 'var .;/some/path' is taken as an empty value for 'var'\nrunning under the program named ';/some/path'. To diagnose this,", "subsections": [] }, "Kpathsea warns if the program name contains a path separator or other": { "content": "special character. The simplest way to avoid the problem is to use the\n'='.\n\nExactly when a character will be considered special or act as itself\ndepends on the context in which it is used. The rules are inherent in\nthe multiple levels of interpretation of the configuration (parsing,\nexpansion, search, ...) and so cannot be concisely stated,\nunfortunately. There is no general escape mechanism; in particular, '\\'\nis not an \"escape character\" in 'texmf.cnf' files. When it comes\nchoosing directory names for installation, it is safest to avoid them\nall.\n\nThe implementation of all this is in 'kpathsea/cnf.c'.\n", "subsections": [] }, "File: kpathsea.info, Node: Path expansion, Next: Casefolding search, Prev: Path sources, Up: Path searching": { "content": "", "subsections": [ { "name": "5.3 Path expansion", "content": "" } ] }, "Kpathsea recognizes certain special characters and constructions in": { "content": "search paths, similar to that in shells. As a general example:\n'~$USER/{foo,bar}//baz' expands to all subdirectories under directories\n'foo' and 'bar' in $USER's home directory that contain a directory or\nfile 'baz'.\n\nThese expansions are explained in the sections below.\n\n* Menu:\n\n* Default expansion:: a: or :a or a::b expands to a default.\n* Variable expansion:: $foo and ${foo} expand to environment values.\n* Tilde expansion:: ~ and ~user expand to home directories.\n* Brace expansion:: a{foo,bar}b expands to afoob abarb.\n* KPSEDOT expansion:: . is replaced with $KPSEDOT if it is defined.\n* Subdirectory expansion:: a// and a//b recursively expand to subdirs.\n", "subsections": [] }, "File: kpathsea.info, Node: Default expansion, Next: Variable expansion, Up: Path expansion": { "content": "If the highest-priority search path (*note Path sources::) contains an\n\"extra colon\" (i.e., leading, trailing, or doubled), Kpathsea inserts at\nthat point the next-highest-priority search path that is defined. If\nthat inserted path has an extra colon, the same happens with the\nnext-highest. (An extra colon in the compile-time default value has\nunpredictable results, so installers beware.)\n\nFor example, given an environment variable setting\n\nsetenv TEXINPUTS /home/karl:\n\nand a 'TEXINPUTS' value from 'texmf.cnf' of\n\n.:$TEXMF//tex\n\nthen the final value used for searching will be:\n\n/home/karl:.:$TEXMF//tex\n\nPut another way, default expansion works on \"formats\" (search paths),\nand not directly on environment variables. Example, showing the\ntrailing ':' ignored in the first case and expanded in the second:\n\n$ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS'\n/tmp\n$ env TTFONTS=/tmp: kpsewhich --show-path=.ttf\n/tmp:.:/home/olaf/texmf/fonts/truetype//:...\n\nSince Kpathsea looks for multiple configuration files, it would be\nnatural to expect that (for example) an extra colon in './texmf.cnf'\nwould expand to the path in '$TEXMF/texmf.cnf'. Or, with Dvips'\nconfiguration files, that an extra colon in 'config.$PRINTER' would\nexpand to the path in 'config.ps'. This doesn't happen. It's not clear\nthis would be desirable in all cases, and trying to devise a way to\nspecify the path to which the extra colon should expand seemed truly\nbaroque.\n\nTechnicality: Since it would be useless to insert the default value\nin more than one place, Kpathsea changes only one extra ':' and leaves\nany others in place (they will eventually be ignored). Kpathsea checks\nfirst for a leading ':', then a trailing ':', then a doubled ':'.\n\nYou can trace this by debugging \"paths\" (*note Debugging::). Default\nexpansion is implemented in the source file 'kpathsea/kdefault.c'.\n", "subsections": [] }, "File: kpathsea.info, Node: Variable expansion, Next: Tilde expansion, Prev: Default expansion, Up: Path expansion": { "content": "'$foo' or '${foo}' in a path element is replaced by (1) the value of an\nenvironment variable 'foo' (if defined); (2) the value of 'foo' from\n'texmf.cnf' (if defined); (3) the empty string.\n\nIf the character after the '$' is alphanumeric or '', the variable\nname consists of all consecutive such characters. If the character\nafter the '$' is a '{', the variable name consists of everything up to\nthe next '}' (braces may not be nested around variable names).\nOtherwise, Kpathsea gives a warning and ignores the '$' and its\nfollowing character.\n\nYou must quote the $'s and braces as necessary for your shell.", "subsections": [] }, "Shell variable values cannot be seen by Kpathsea, i.e., ones defined": { "content": "by 'set' in C shells and without 'export' in Bourne shells.\n\nFor example, given\nsetenv tex /home/texmf\nsetenv TEXINPUTS .:$tex:${tex}prev\nthe final 'TEXINPUTS' path is the three directories:\n.:/home/texmf:/home/texmfprev\n\nThe '.PROGNAME' suffix on variables and 'PROGNAME' on environment\nvariable names are not implemented for general variable expansions.\nThese are only recognized when search paths are initialized (*note Path\nsources::).\n\nVariable expansion is implemented in the source file\n'kpathsea/variable.c'.\n", "subsections": [] }, "File: kpathsea.info, Node: Tilde expansion, Next: Brace expansion, Prev: Variable expansion, Up: Path expansion": { "content": "A leading '~' in a path element is replaced by the value of the\nenvironment variable 'HOME', or '.' if 'HOME' is not set. On Windows,\nthe environment variable 'USERPROFILE' is checked instead of 'HOME'.\n\nA leading '~USER' in a path element is replaced by USER's home\ndirectory from the system 'passwd' database.\n\nFor example,\nsetenv TEXINPUTS ~/mymacros:\n\nwill prepend a directory 'mymacros' in your home directory to the\ndefault path.\n\nAs a special case, if a home directory ends in '/', the trailing\nslash is dropped, to avoid inadvertently creating a '//' construct in\nthe path. For example, if the home directory of the user 'root' is '/',\nthe path element '~root/mymacros' expands to just '/mymacros', not\n'//mymacros'.\n\nTilde expansion is implemented in the source file 'kpathsea/tilde.c'.\n", "subsections": [] }, "File: kpathsea.info, Node: Brace expansion, Next: KPSEDOT expansion, Prev: Tilde expansion, Up: Path expansion": { "content": "'x{A,B}y' expands to 'xAy:xBy'. For example:\n\nfoo/{1,2}/baz\n\nexpands to 'foo/1/baz:foo/2/baz'. ':' is the path separator on the\ncurrent system; e.g., on a Windows system, it's ';'.\n\nBraces can be nested; for example, 'x{A,B{1,2}}y' expands to\n'xAy:xB1y:xB2y'.\n\nMultiple non-nested braces are expanded from right to left; for\nexample, 'x{A,B}{1,2}y' expands to 'x{A,B}1y:x{A,B}2y', which expands to\n'xA1y:xB1y:xA2y:xB2y'.\n\nThis feature can be used to implement multiple TeX hierarchies, by\nassigning a brace list to '$TEXMF', as mentioned in 'texmf.in'.\n\nYou can also use the path separator instead of the comma. The last\nexample could have been written 'x{A:B}{1:2}y' (on Unix).\n\nBrace expansion is implemented in the source file\n'kpathsea/expand.c'.\n", "subsections": [] }, "File: kpathsea.info, Node: KPSEDOT expansion, Next: Subdirectory expansion, Prev: Brace expansion, Up: Path expansion": { "content": "", "subsections": [] }, "When 'KPSEDOT' is defined in the environment, it names a directory that": { "content": "should be considered the current directory for the purpose of looking up\nfiles in the search paths. This feature is needed by the 'mktex...'\nscripts *note mktex scripts::, because these change the working\ndirectory. You should not ever define it yourself.\n", "subsections": [] }, "File: kpathsea.info, Node: Subdirectory expansion, Prev: KPSEDOT expansion, Up: Path expansion": { "content": "", "subsections": [] }, "Two or more consecutive slashes in a path element following a directory": { "content": "D is replaced by all subdirectories of D: first those subdirectories\ndirectly under D, then the subsubdirectories under those, and so on. At\neach level, the order in which the directories are searched is\nunspecified. (It's \"directory order\", and definitely not alphabetical.)\n\nIf you specify any filename components after the '//', only\nsubdirectories which match those components are included. For example,\n'/a//b' would expand into directories '/a/1/b', '/a/2/b', '/a/1/1/b',\nand so on, but not '/a/b/c' or '/a/1'.\n\nYou can include multiple '//' constructs in the path.\n\n'//' at the beginning of a path is ignored; you didn't really want to\nsearch every directory on the system, did you?\n\nI should mention one related implementation trick, which I took from\nGNU find. Matthew Farwell suggested it, and David MacKenzie implemented\nit.\n\nThe trick is that in every real Unix implementation (as opposed to\nthe POSIX specification), a directory which contains no subdirectories\nwill have exactly two links (namely, one for '.' and one for '..').", "subsections": [] }, "That is to say, the 'stnlink' field in the 'stat' structure will be": { "content": "two. Thus, we don't have to stat everything in the bottom-level (leaf)\ndirectories--we can just check 'stnlink', notice it's two, and do no\nmore work.\n\nBut if you have a directory that contains a single subdirectory and\n500 regular files, 'stnlink' will be 3, and Kpathsea has to stat every\none of those 501 entries. Therein lies slowness.\n\nYou can disable the trick by undefining 'STNLINKTRICK' in\n'kpathsea/config.h'. (It is undefined by default except under Unix.)\n\nUnfortunately, in some cases files in leaf directories are 'stat''d:\nif the path specification is, say, '$TEXMF/fonts//pk//', then files in a\nsubdirectory '.../pk', even if it is a leaf, are checked. The reason\ncannot be explained without reference to the implementation, so read\n'kpathsea/elt-dirs.c' (search for 'may descend') if you are curious.\nAnd if you find a way to solve the problem, please let me know.\n\nSubdirectory expansion is implemented in the source file\n'kpathsea/elt-dirs.c'.\n", "subsections": [] }, "File: kpathsea.info, Node: Casefolding search, Next: Filename database, Prev: Path expansion, Up: Path searching": { "content": "", "subsections": [ { "name": "5.4 Casefolding search", "content": "" } ] }, "In Kpathsea version 6.3.0 (released with TeX Live 2018), a new fallback": { "content": "search was implemented on Unix-like systems, including Macs: for each\npath element in turn, if no match is found by the normal search, and the\npath element allows for checking the filesystem, a second check is made\nfor a case-insensitive match.\n\nThis is enabled at compile-time on Unix systems, and enabled at\nruntime by setting the configuration variable 'texmfcasefoldsearch',\nto a true value, e.g., '1'; this is done by default in TeX Live.\n\n* Menu:\n\n* Rationale: Casefolding rationale.\n* Examples: Casefolding examples.\n", "subsections": [] }, "File: kpathsea.info, Node: Casefolding rationale, Next: Casefolding examples, Up: Casefolding search": { "content": "", "subsections": [] }, "The purpose of the fallback casefolding search is to ease moving complex": { "content": "documents between case-insensitive (file)systems and case-sensitive\nones. In particular, Apple decided to make the default filesystem on", "subsections": [] }, "Macs be case-insensitive some years ago, and this has exacerbated a": { "content": "problem of people creating documents that use, say, an image under the\nname 'foo.jpg', while the actual file is named 'foo.JPG' or 'Foo.jpg'.", "subsections": [] }, "It works on the Mac but if the document is transferred and run on a": { "content": "standard case-sensitive Unix (file)system, the file can't be found, due\nonly to differences in case.\n\nThis same problematic scenario has always existed on Windows, but for\nwhatever reason, it has become much more common since Apple also went to\na case-insensitive filesystem. Hence the relatively late change to the\nKpathsea behavior.\n\nThe fallback case-insensitive search is omitted at compile-time on", "subsections": [] }, "Windows, where (for practical purposes) all file names are": { "content": "case-insensitive at the kernel level, and so the normal search will\nalready have definitively matched or not. Therefore, search results in\nunusual cases can be different on Windows and Unix--but this has always\nbeen true.\n", "subsections": [] }, "File: kpathsea.info, Node: Casefolding examples, Prev: Casefolding rationale, Up: Casefolding search": { "content": "", "subsections": [] }, "The casefolding implementation prefers exact matches to casefolded": { "content": "matches within a given path element, so as to retain most compatibility.", "subsections": [] }, "Backward compatibility is not perfect, however, as a casefolded match": { "content": "may be found in an earlier path element than an exact match was\npreviously found (see example #4 below). Still, preferring the match in\nthe earlier element seemed potentially less confusing than otherwise,\nand is in fact consistent with past behavior on Windows. Since case\nmismatches are rare to begin with, and name collisions with respect only\nto case thus even more rare, the hope is that it will not cause\ndifficulties in practice.\n\nIf it's desirable in a given situation to have the exact same search\nbehavior as previously, that can be accomplished by setting the\nconfiguration variable 'texmfcasefoldsearch' to '0' (*note Path\nsources::).\n\nSome examples to illustrate the new behavior follow.\n\nExample #1: suppose the file './foobar.tex' exists. Now, searching\nfor './FooBar.TeX' (or any other case variation) will succeed, returning\n'./foobar.tex'--the name as stored on disk. In previous releases, or if\n'texmfcasefoldsearch' is false, the search would fail.\n\nExample #2: suppose we are using a case-sensitive (file)system, and\nthe search path is '.:/somedir', and the files './foobar.tex' and\n'/somedir/FooBar.TeX' both exist. Both now and previously, searching\nfor 'foobar.tex' returns './foobar.tex'. However, searching for\n'FooBar.TeX' now returns './foobar.tex' instead of\n'/somedir/FooBar.TeX'; this is the incompatibility mentioned above.", "subsections": [] }, "Also (as expected), searching for 'FOOBAR.TEX' (or whatever variation)": { "content": "will now return './foobar.tex', whereas before it would fail. Searching\nfor all ('kpsewhich --all') 'foobar.tex' will return both matches.\n\nExample #3: same as example #2, but on a case-insensitive\n(file)system: both now and previously, searching for 'FooBar.TeX'\nreturns './foobar.tex', since the system considers that a match. The\nKpathsea casefolding never comes into play.\n\nExample #4: if we have (on a case-sensitive system) both\n'./foobar.tex' and './FOOBAR.TEX', searching with the exact case returns\nthat exact match, now and previously. Searching for 'FooBar.tex' will\nnow return one or the other (chosen arbitrarily), rather than failing.", "subsections": [] }, "Perhaps unexpectedly, searching for all 'foobar.tex' or 'FooBar.tex'": { "content": "will also return only one or the other, not both (see more below).\n\nExample #5: the font file 'STIX-Regular.otf' is included in TeX Live\nin the system directory 'texmf-dist/fonts/opentype/public/stix'.", "subsections": [] }, "Because Kpathsea never searches the disk in the big system directory,": { "content": "the casefolding is not done, and a search for 'stix-regular.otf' will\nfail (on case-sensitive systems), as it always has.\n\nThe caveat about not searching the disk amounts to saying that\ncasefolding does not happen in the trees specified with '!!' (*note\nls-R::), that is, where only database ('ls-R') searching is done. In", "subsections": [] }, "TeX Live, that is the 'texmf-local' and 'texmf-dist' trees (also": { "content": "'$TEXMFSYSCONFIG' and '$TEXMFSYSVAR', but those are rarely noticed).", "subsections": [] }, "The rationale for this is that in practice, case mangling happens with": { "content": "user-created files, not with packages distributed as part of the TeX\nsystem.\n\nOne more caveat: the purpose of 'kpsewhich' is to exercise the path\nsearching in Kpathsea as it is actually done. Therefore, as shown\nabove, 'kpsewhich --all' will not return all matches regardless of case\nwithin a given path element. If you want to find all matches in all\ndirectories, 'find' is the best tool, although the setup takes a couple\nsteps:\n\nkpsewhich -show-path=tex >/tmp/texpath # search path specification\nkpsewhich -expand-path=\"`cat /tmp/texpath`\" >/tmp/texdirs # all dirs\ntr ':' '\\n' /tmp/texdirlist # colons to newlines\nfind `cat /tmp/texdirlist` -iname somefile.tex -print .\n\nThe casefolding search is implemented in the source file\n'kpathsea/pathsearch.c'. Two implementation points:\n\n* Kpathsea never tries to check if a given directory resides on a\ncase-insensitive filesystem, because there is no efficient and\nportable way to do so. All it does is try to see if a potential\nfile name is a readable normal file (with, usually, the 'access'\nsystem call).\n\n* Kpathsea does not do any case-insensitive matching of the\ndirectories along the path. It's not going to find\n'/Some/Random/file.tex' when looking for '/some/random/file.tex'.\nThe casefolding only happens with the elements of the leaf\ndirectory.\n", "subsections": [] }, "File: kpathsea.info, Node: Filename database, Next: Invoking kpsewhich, Prev: Casefolding search, Up: Path searching": { "content": "", "subsections": [ { "name": "5.5 Filename database ('ls-R')", "content": "" } ] }, "Kpathsea goes to some lengths to minimize disk accesses for searches": { "content": "(*note Subdirectory expansion::). Nevertheless, in practice searching\nevery possible directory in typical TeX installations takes an\nexcessively long time.\n\nTherefore, Kpathsea can use an externally-built \"filename database\"\nfile named 'ls-R' that maps files to directories, thus avoiding the need\nto exhaustively search the disk.\n\nA second database file 'aliases' allows you to give additional names\nto the files listed in 'ls-R'.\n\nThe 'ls-R' and 'aliases' features are implemented in the source file\n'kpathsea/db.c'.\n\n* Menu:\n\n* ls-R:: The main filename database.\n* Filename aliases:: Aliases for those names.\n* Database format:: Syntax details of the database file.\n", "subsections": [] }, "File: kpathsea.info, Node: ls-R, Next: Filename aliases, Up: Filename database": { "content": "As mentioned above, you must name the main filename database 'ls-R'.", "subsections": [] }, "You can put one at the root of each TeX installation hierarchy you wish": { "content": "to search ('$TEXMF' by default, which expands to a braced list of\nseveral hierarchies in TeX Live).\n\nKpathsea looks for 'ls-R' files along the 'TEXMFDBS' path. It is\nbest for this to contain all and only those hierarchies from '$TEXMF'\nwhich are specified with '!!'--and also to specify them with '!!' in\n'TEXMFDBS'. (See the end of this section for more on '!!'.)\n\nThe recommended way to create and maintain 'ls-R' is to run the\n'mktexlsr' script, which is installed in '$(bindir)' ('/usr/local/bin'\nby default). That script goes to some trouble to follow symbolic links\nas necessary, etc. It's also invoked by the distributed 'mktex...'\nscripts.\n\nAt its simplest, though, you can build 'ls-R' with the command\ncd /YOUR/TEXMF/ROOT && ls -LAR ./ >ls-R\n\npresuming your 'ls' produces the right output format (see the section\nbelow). GNU 'ls', for example, outputs in this format. Also presuming\nyour 'ls' hasn't been aliased in a system file (e.g., '/etc/profile') to\nsomething problematic, e.g., 'ls --color=tty'. In that case, you will\nhave to disable the alias before generating 'ls-R'. For the precise\ndefinition of the file format, see *note Database format::.\n\nRegardless of whether you use the supplied script or your own, you\nwill almost certainly want to invoke it via 'cron', so when you make\nchanges in the installed files (say if you install a new LaTeX package),\n'ls-R' will be automatically updated. However, for those using TeX Live\nor system distributions, the package managers should run 'mktexlsr' as\nneeded.\n\nThe '-A' option to 'ls' includes files beginning with '.' (except for\n'.' and '..'), such as the file '.tex' included with the LaTeX tools\npackage. (On the other hand, directories whose names begin with '.'\nare always ignored.)\n\nIf your system does not support symbolic links, omit the '-L'.\n\n'ls -LAR /YOUR/TEXMF/ROOT' will also work. But using './' avoids\nembedding absolute pathnames, so the hierarchy can be easily\ntransported. It also avoids possible trouble with automounters or other\nnetwork filesystem conventions.\n\nKpathsea warns you if it finds an 'ls-R' file, but the file does not\ncontain any usable entries. The usual culprit is running plain 'ls -R'\ninstead of 'ls -LR ./' or 'ls -R /YOUR/TEXMF/ROOT'. Another possibility\nis some system directory name starting with a '.' (perhaps if you are\nusing AFS); Kpathsea ignores everything under such directories.\n\nIf a particular path element begins with '!!', only the database\nwill be searched for that element, never the disk; and if the database\ndoes not exist, nothing at all will be searched. In TeX Live, most of\nthe trees are specified with '!!'.\n\nFor path elements that do not begin with '!!', if the database\nexists, it will be used, and the disk will not be searched. However, in\nthis case, if the database does not exist, the disk will be searched.", "subsections": [] }, "In TeX Live, the most notable case of this is the 'TEXMFHOME' tree, to": { "content": "allow users to add and remove files from their own tree without having\nto worry about 'ls-R'.\n\n(Aside: there are uncommon cases where a '!!' tree will be searched\non disk even if the 'ls-R' file exists; they are too obscure to try to\nexplain here. See 'pathsearch.c' in the source if you need to know.)\n\nTo sum up: do not create an 'ls-R' file unless you also take care to\nkeep it up to date. Otherwise newly-installed files will not be found.\n", "subsections": [] }, "File: kpathsea.info, Node: Filename aliases, Next: Database format, Prev: ls-R, Up: Filename database": { "content": "In some circumstances, you may wish to find a file under several names.", "subsections": [] }, "For example, suppose a TeX document was created using a DOS system and": { "content": "tries to read 'longtabl.sty'. But now it's being run on a Unix system,\nand the file has its original name, 'longtable.sty'. The file won't be\nfound. You need to give the actual file 'longtable.sty' an alias\n'longtabl.sty'.\n\nYou can handle this by creating a file 'aliases' as a companion to\nthe 'ls-R' for the hierarchy containing the file in question. (You must\nhave an 'ls-R' for the alias feature to work.)\n\nThe format of 'aliases' is simple: two whitespace-separated words per\nline; the first is the real name 'longtable.sty', and second is the\nalias ('longtabl.sty'). These must be base filenames, with no directory\ncomponents. 'longtable.sty' must be in the sibling 'ls-R'.\n\nAlso, blank lines and lines starting with '%' or '#' are ignored in\n'aliases', to allow for comments.\n\nIf a real file 'longtabl.sty' exists, it is used regardless of any\naliases.\n", "subsections": [] }, "File: kpathsea.info, Node: Database format, Prev: Filename aliases, Up: Filename database": { "content": "The \"database\" read by Kpathsea is a line-oriented file of plain text.", "subsections": [] }, "The format is that generated by GNU (and most other) 'ls' programs given": { "content": "the '-R' option, as follows.\n\n* Blank lines are ignored.\n\n* If a line begins with '/' or './' or '../' and ends with a colon,\nit's the name of a directory. ('../' lines aren't useful, however,\nand should not be generated.)\n\n* All other lines define entries in the most recently seen directory.\n/'s in such lines will produce possibly-strange results.\n\n* Files with no preceding directory line are ignored.\n\nFor example, here's the first few lines of 'ls-R' (which totals about\n30K bytes) on my system:\n\nbibtex\ndvips\nfonts\nls-R\nmetafont\nmetapost\ntex\nweb2c\n\n./bibtex:\nbib\nbst\ndoc\n\n./bibtex/bib:\nasi.bib\nbtxdoc.bib\n...\n", "subsections": [] }, "File: kpathsea.info, Node: Invoking kpsewhich, Prev: Filename database, Up: Path searching": { "content": "", "subsections": [ { "name": "5.6 'kpsewhich': Standalone path searching", "content": "" } ] }, "The Kpsewhich program exercises the path searching functionality": { "content": "independent of any particular application. This can also be useful as a\nsort of 'find' program to locate files in your TeX hierarchies, perhaps\nin administrative scripts. It is used heavily in the distributed\n'mktex...' scripts.\n\nSynopsis:\n\nkpsewhich OPTION... FILENAME...\n\nThe options and filename(s) to look up can be intermixed. Options\ncan start with either '-' or '--', and any unambiguous abbreviation is\naccepted.\n\n* Menu:\n\n* Path searching options:: Changing the mode, resolution, etc.\n* Specially-recognized files:: Default formats for texmf.cnf, etc.\n* Auxiliary tasks:: Path and variable expansion, etc.\n* Standard options:: '--help' and '--version'.\n", "subsections": [] }, "File: kpathsea.info, Node: Path searching options, Next: Specially-recognized files, Up: Invoking kpsewhich": { "content": "", "subsections": [] }, "Kpsewhich looks up each non-option argument on the command line as a": { "content": "filename, and returns the first file found.\n\nVarious options alter the path searching behavior:\n\n'--all'\nReport all matches found, one per line. By default, if there is\nmore than one match, just one will be reported (chosen effectively\nat random). Exception: with the glyph formats ('pk', 'gf'), this\noption has no effect and only the first match is returned.\n\n'--casefold-search'\n'--no-casefold-search'\nExplicitly enable or disable the fallback to a case-insensitive\nsearch on Unix platforms (*note Casefolding search::); no effect on\nWindows. The default is enabled, set in 'texmf.cnf'. Disabling\n('--no-casefold-search') does not mean that searches magically\nbecome case-sensitive when the underlying (file)system is\ncase-insensitive, it merely means that Kpathsea does not do any\ncasefolding itself.\n\n'--cnf-line=STR'\nParse STR as if it were a line in the 'texmf.cnf' configuration\nfile (*note Config files::), overriding settings in the actual\nconfiguration files, and also in the environment (*note Path\nsources::). This is implemented by making any settings from STR in\nthe environment, overwriting any value already there. Thus, an\nextra colon in a '--cnf-line' value will refer to the value from a\nconfiguration file, not a user-set environment variable.\n\nFurthermore, any variable set from STR will also be set with the\nprogram name suffix. For example, 'pdftex\n--cnf-line=TEXINPUTS=/foo:' will set both 'TEXINPUTS' and\n'TEXINPUTSpdftex' in the environment (and the value will be '/foo'\nfollowed by the setting from 'texmf.cnf', ignoring any user-set\n'TEXINPUTS').\n\nThis behavior is desirable because, in practice, many variables in\nthe distributed 'texmf.cnf' are program-specific, and the intuitive\nbehavior is for values set on the command line with '--cnf-line' to\noverride them.\n\n'--dpi=NUM'\nSet the resolution to NUM; this only affects 'gf' and 'pk' lookups.\n'-D' is a synonym, for compatibility with Dvips. Default is 600.\n\n'--engine=NAME'\nSet the engine name to NAME. By default it is not set. The engine\nname is used in some search paths to allow files with the same name\nbut used by different engines to coexist.\n\nIn particular, since the memory dump files ('.fmt'/'.base'/'.mem')\nare now stored in subdirectories named for the engine ('tex',\n'pdftex', 'xetex', etc.), you must specify an engine name in order\nto find them. For example, 'cont-en.fmt' typically exists for both\n'pdftex' and 'xetex'. With the default path settings, you can use\n'--engine=/' to look for any dump file, regardless of engine; if a\ndump file exists for more than one engine, it's indeterminate which\none is returned. (The '/' ends up specifying a normal recursive\nsearch along the path where the dumps are stored, namely\n'$TEXMF/web2c{/$engine,}'.)\n\n'--format=NAME'\nSet the format for lookup to NAME. By default, the format is\nguessed from the filename, with 'tex' being used if nothing else\nfits. The recognized filename extensions (including any leading\n'.') are also allowable NAMEs.\n\nAll formats also have a name, which is the only way to specify\nformats with no associated suffix. For example, for Dvips\nconfiguration files you can use '--format=\"dvips config\"'. (The\nquotes are for the sake of the shell.)\n\nHere's the current list of recognized names and the associated\nsuffixes. *Note Supported file formats::, for more information on\neach of these.\n\nThe strings in parentheses are abbreviations recognized only by\n'kpsewhich' (not the underlying library calls). They are provided\nwhen it would otherwise require an argument containing a space to\nspecify the format, to simplify quoting of calls from shells.\n\ngf: gf\npk: pk\nbitmap font (bitmapfont):\ntfm: .tfm\nafm: .afm\nbase: .base\nbib: .bib\nbst: .bst\ncnf: .cnf\nls-R: ls-R ls-r\nfmt: .fmt\nmap: .map\nmem: .mem\nmf: .mf\nmfpool: .pool\nmft: .mft\nmp: .mp\nmppool: .pool\nMetaPost support (mpsupport):\nocp: .ocp\nofm: .ofm .tfm\nopl: .opl .pl\notp: .otp\novf: .ovf .vf\novp: .ovp .vpl\ngraphic/figure: .eps .epsi\ntex: .tex .sty .cls .fd .aux .bbl .def .clo .ldf\nTeX system documentation (doc):\ntexpool: .pool\nTeX system sources (source): .dtx .ins\nPostScript header: .pro\nTroff fonts (trofffont):\ntype1 fonts: .pfa .pfb\nvf: .vf\ndvips config (dvipsconfig):\nist: .ist\ntruetype fonts: .ttf .ttc .TTF .TTC .dfont\ntype42 fonts: .t42 .T42\nweb2c files (web2c):\nother text files (othertext):\nother binary files (otherbin):\nmisc fonts (miscfont):\nweb: .web .ch\ncweb: .w .web .ch\nenc files: .enc\ncmap files (cmap):\nsubfont definition files: .sfd\nopentype fonts: .otf\npdftex config (pdftexconfig):\nlig files: .lig\ntexmfscripts:\nlua: .lua .luatex .luc .luctex .texlua .texluc .tlu\nfont feature files: .fea\ncid maps: .cid .cidmap\nmlbib: .mlbib .bib\nmlbst: .mlbst .bst\nclua: .dll .so\nris: .ris\nbltxml: .bltxml\n\nThis option and '--path' are mutually exclusive.\n\n'--interactive'\nAfter processing the command line, read additional filenames to\nlook up from standard input.\n\n'--mktex=FILETYPE'\n'--no-mktex=FILETYPE'\nTurn on or off the 'mktex' script associated with FILETYPE. Usual\nvalues for FILETYPE are 'pk', 'mf', 'tex', and 'tfm'. By default,\nall are off in Kpsewhich, even if they are enabled for TeX. This\noption implies setting '--must-exist'. *Note mktex scripts::.\n\n'--mode=STRING'\nSet the mode name to STRING; this also only affects 'gf' and 'pk'\nlookups. No default: any mode will be found. *Note mktex script\narguments::.\n\n'--must-exist'\nDo everything possible to find the files, notably including\nsearching the disk and running the 'mktex' scripts. By default,\nonly the 'ls-R' database is checked, in the interest of efficiency.\n\n'--path=STRING'\nSearch along the path STRING (colon-separated as usual), instead of\nguessing the search path from the filename. '//' and all the usual\nexpansions are supported (*note Path expansion::). This option and\n'--format' are mutually exclusive. To output the complete\ndirectory expansion of a path, instead of doing a one-shot lookup,\nsee '--expand-path' and '--show-path' in the following section.\n\n'--progname=NAME'\nSet the program name to NAME; default is 'kpsewhich'. This can\naffect the search paths via the '.PROGNAM' feature in configuration\nfiles (*note Config files::).\n\n'--subdir=STRING'\nReport only those matches whose directory part ends with STRING\n(compared literally, except case is ignored on a case-insensitive\noperating system). For example, suppose there are two matches for\na given name:\n\nkpsewhich foo.sty\n=> /some/where/foo.sty\n/another/place/foo.sty\n\nThen we can narrow the result to what we are interested in with\n'--subdir':\n\nkpsewhich --subdir=where foo.sty\n=> /some/where/foo.sty\n\nkpsewhich --subdir=place foo.sty\n=> /another/place/foo.sty\n\nThe string to match must be at the end of the directory part of the\nmatch, and it is taken literally, with no pattern matching:\n\nkpsewhich --subdir=another foo.sty\n=>\n\nThe string to match may cross directory components:\n\nkpsewhich --subdir=some/where foo.sty\n=> /some/where/foo.sty\n\n'--subdir' implies '--all'; if there is more than one match, they\nwill all be reported (in our example, both 'where' and 'place' end\nin 'e'):\n\nkpsewhich --subdir=e\n=> /some/where/foo.sty\n/another/place/foo.sty\n\nBecause of the above rules, the presence of a leading '/' is\nimportant, since it \"anchors\" the match to a full component name:\n\nkpsewhich --subdir=/lace foo.sty\n=>\n\nHowever, a trailing '/' is immaterial (and ignored), since the\nmatch always takes place at the end of the directory part:\n\nkpsewhich --subdir=lace/ foo.sty\n=> /another/place/foo.sty\n\nThe purpose of these rules is to make it convenient to find results\nonly within a particular area of the tree. For instance, a given\nscript named 'foo.lua' might exist within both\n'texmf-dist/scripts/pkg1/' and 'texmf-dist/scripts/pkg2/'. By\nspecifying, say, '--subdir=/pkg1', you can be sure of getting the\none you are interested in.\n\nWe only match at the end because a site might happen to install TeX\nin '/some/coincidental/pkg1/path/', and we wouldn't want to match\n'texmf-dist/scripts/pkg2/' that when searching for '/pkg1'.\n", "subsections": [] }, "File: kpathsea.info, Node: Specially-recognized files, Next: Auxiliary tasks, Prev: Path searching options, Up: Invoking kpsewhich": { "content": "'kpsewhich' recognizes a few special filenames on the command line and\ndefaults to using the 'known' file formats for them, merely to save the\ntime and trouble of specifying the format. This is only a feature of\n'kpsewhich'; when using the Kpathsea library itself, none of these\nspecial filenames are recognized, and it's still up to the caller to\nspecify the desired format.\n\nHere is the list of special filenames to 'kpsewhich', along with\ntheir corresponding format:\n\n'config.ps'\n'dvips config'\n\n'dvipdfmx.cfg'\n'other text files'\n\n'fmtutil.cnf'\n'web2c files'\n\n'glyphlist.txt'\n'map'\n\n'mktex.cnf'\n'web2c files'\n\n'pdfglyphlist.txt'\n'map'\n\n'pdftex.cfg'\n'pdftex config' (although 'pdftex.cfg' is not used any more; look\nfor the file 'pdftexconfig.tex' instead.)\n\n'texmf.cnf'\n'cnf'\n\n'XDvi'\n'other text files'\n\nA user-specified format will override the above defaults.\n\nAnother useful configuration file in this regard is 'tcfmgr.map',\nfound in 'texmf/texconfig/tcfmgr.map', which records various information\nabout the above configuration files (among others).\n", "subsections": [] }, "File: kpathsea.info, Node: Auxiliary tasks, Next: Standard options, Prev: Specially-recognized files, Up: Invoking kpsewhich": { "content": "Kpsewhich provides some features in addition to path lookup as such:\n\n'--debug=NUM'\nSet debugging options to NUM. *Note Debugging::.\n\n'--expand-braces=STRING'\nOutput variable, tilde, and brace expansion of STRING, which is\nassumed to be a single path element. *Note Path expansion::.\n\n'--expand-path=STRING'\nOutput the complete expansion of STRING, with each element\nseparated by the usual path separator on the current system (';' on\nWindows, ':' otherwise). This may be useful to construct a custom\nsearch path for a format not otherwise supported. To retrieve the\nsearch path for a format that is already supported, see\n'--show-path'.\n\nNonexistent directories are culled from the output:\n\n$ kpsewhich --expand-path '/tmp'\n=> /tmp\n$ kpsewhich --expand-path '/nonesuch'\n=>\n\nFor one-shot uses of an arbitrary (not built in to Kpathsea) path,\nsee '--path' (*note Path searching options::).\n\n'--expand-var=STRING'\nOutput the variable and tilde expansion of STRING. For example,\nwith the usual 'texmf.cnf', 'kpsewhich --expand-var='$TEXMF''\nreturns the TeX system hierarchy root(s). *Note Path expansion::.\nThe specified STRING can contain anything, though, not just\nvariable references. This calls 'kpsevarexpand' (*note\nProgramming with config files::).\n\n'--help-formats'\nOutput information about each supported format (*note Supported\nfile formats::), including the names and abbreviations, variables\nlooked for, and the original path.\n\n'--safe-in-name=NAME'\n'--safe-out-name=NAME'\nExit successfully if NAME is safe to open for reading or writing,\nrespectively, else unsuccessfully. No output is written. These\ntests take account of the related Kpathsea configuration settings\n(*note Calling sequence::).\n\n'--show-path=NAME'\nShow the path that would be used for file lookups of file type\nNAME. Either a filename extension ('pk', '.vf', etc.) or an\ninteger can be used, just as with '--format', described in the\nprevious section.\n\n'--var-brace-value=VARIABLE'\nLike '--var-value' (next), but also expands '{...}' constructs.\n(*note Brace expansion::). Thus, the value is assumed to possibly\nbe several path elements, and '~' is expanded at the beginning of\neach. The path separator is changed to that of the current system\nin the expansion.\n\nExample: 'FOO='.;~' kpsewhich --var-brace-value=FOO' outputs (on a\nUnix-ish system) '.:/home/karl', supposing the latter is the\ncurrent user's home directory. Note that the ';' in the source\nvalue, as commonly used in 'texmf.cnf', has changed to a ':', as\nthe normal path separator on the current system. On a Windows-ish\nsystem, the ';' would remain.\n\n'--var-value=VARIABLE'\nOutputs the value of VARIABLE (a simple identifier like\n'TEXMFDIST', with no '$' or other constructs), expanding '$' (*note\nVariable expansion::) and '~' (*note Tilde expansion::) constructs\nin the value. '~' expansion happens at the beginning of the\noverall value and at the beginning of a variable expansion, but not\narbitrarily within the string. Braces are not expanded.\n\nExample: '--var-value=texmfcasefoldsearch' outputs (if the\ndefault is not changed) '1'.\n\nExample to contrast with '--var-brace-value': 'FOO='.;~' kpsewhich\n--var-value=FOO' outputs '.;~', i.e., the same as the input value,\non all systems.\n", "subsections": [] }, "File: kpathsea.info, Node: Standard options, Prev: Auxiliary tasks, Up: Invoking kpsewhich": { "content": "Kpsewhich accepts the standard GNU options:\n\n* '--help' prints a help message on standard output and exits\nsuccessfully.\n\n* '--version' prints the Kpathsea version number and exits\nsuccessfully.\n", "subsections": [] }, "File: kpathsea.info, Node: TeX support, Next: Programming, Prev: Path searching, Up: Top": { "content": "", "subsections": [] }, "6 TeX support": { "content": "", "subsections": [] }, "Although the basic features in Kpathsea can be used for any type of path": { "content": "searching, it came about, as usual, with a specific application in mind:\nI wrote Kpathsea specifically for TeX system programs. I had been\nstruggling with the programs I was using (Dvips, Xdvi, and TeX itself)\nhaving slightly different notions of how to specify paths; and debugging\nwas painful, since no code was shared.\n\nTherefore, Kpathsea provides some TeX-specific formats and features.", "subsections": [] }, "Indeed, many of the purportedly generic path searching features were": { "content": "provided because they seemed useful in that conTeXt (font lookup,\nparticularly).\n\nKpathsea provides a standard way to search for files of any of the\nsupported file types; glyph fonts are a bit different than all the rest.", "subsections": [] }, "Searches are based solely on names of files, not their contents--if a GF": { "content": "file is (mis)named 'cmr10.600pk', it will be found as a PK file.\n\n* Menu:\n\n* Supported file formats:: File types Kpathsea knows about.\n* File lookup:: Searching for most kinds of files.\n* Glyph lookup:: Searching for bitmap fonts.\n* Suppressing warnings:: Avoiding warnings via TEXHUSH.\n* mktex scripts:: Generating files at runtime.\n", "subsections": [] }, "File: kpathsea.info, Node: Supported file formats, Next: File lookup, Up: TeX support": { "content": "", "subsections": [ { "name": "6.1 Supported file formats", "content": "" } ] }, "Kpathsea has support for a number of file types. Each file type has a": { "content": "list of environment and config file variables that are checked to define\nthe search path, and most have a default suffix that plays a role in\nfinding files (see the next section). Some also define additional\nsuffixes, and/or a program to be run to create missing files on the fly.\n\nSince environment variables containing periods, such as\n'TEXINPUTS.latex', are not allowed on some systems, Kpathsea looks for\nenvironment variables with an underscore, e.g., 'TEXINPUTSlatex' (*note\nConfig files::).\n\nThe following table lists the above information. You can also get\nthe list by giving the '--help-formats' option to 'kpsewhich' (*note\nAuxiliary tasks::).\n\n'afm'\n(Adobe font metrics, *note (dvips)Metric files::) 'AFMFONTS';\nsuffix '.afm'.\n\n'base'\n(Metafont memory dump, *note (web2c)Memory dumps::) 'MFBASES',\n'TEXMFINI'; suffix '.base'.\n\n'bib'\n(BibTeX bibliography source, *note (web2c)bibtex invocation::)\n'BIBINPUTS', 'TEXBIB'; suffix '.bib'.\n\n'bltxml'\n(BibLaTeXML bibliography files for Biber,\n) 'BLTXMLINPUTS' suffix '.bltxml'.\n\n'bst'\n(BibTeX style, *note Basic BibTeX style files: (web2c)Basic BibTeX\nstyle files.) 'BSTINPUTS'; suffix '.bst'.\n\n'clua'\n(dynamic libraries for Lua, )\n'CLUAINPUTS' suffixes '.dll' and '.so'.\n\n'cmap'\n(character map files) 'CMAPFONTS'; suffix '.cmap'.\n\n'cnf'\n(Runtime configuration files, *note Config files::) 'TEXMFCNF';\nsuffix '.cnf'.\n\n'cweb'\n(CWEB input files) 'CWEBINPUTS'; suffixes '.w', '.web'; additional\nsuffix '.ch'.\n\n'dvips config'\n(Dvips 'config.*' files, such as 'config.ps', *note (dvips)Config\nfiles::) 'TEXCONFIG'.\n\n'enc files'\n(encoding vectors) 'ENCFONTS'; suffix '.enc'.\n\n'fmt'\n(TeX memory dump, *note (web2c)Memory dumps::) 'TEXFORMATS',\n'TEXMFINI'; suffix '.fmt'.\n\n'font cid map'\n(CJK mapping) 'FONTCIDMAPS' suffix '.cid'.\n\n'font feature files'\n(primarily for OpenType font features) 'FONTFEATURES' suffix\n'.fea'.\n\n'gf'\n(generic font bitmap, *note (dvips)Glyph files::) 'PROGRAMFONTS',\n'GFFONTS', 'GLYPHFONTS', 'TEXFONTS'; suffix 'gf'.\n\n'graphic/figure'\n(Encapsulated PostScript figures, *note (dvips)PostScript\nfigures::) 'TEXPICTS', 'TEXINPUTS'; additional suffixes: '.eps',\n'.epsi'.\n\n'ist'\n(makeindex style files) 'TEXINDEXSTYLE', 'INDEXSTYLE'; suffix\n'.ist'.\n\n'lig files'\n(ligature definition files) 'LIGFONTS'; suffix '.lig'.\n\n'ls-R'\n(Filename databases, *note Filename database::) 'TEXMFDBS'.\n\n'map'\n(Fontmaps, *note Fontmap::) 'TEXFONTMAPS'; suffix '.map'.\n\n'mem'\n(MetaPost memory dump, *note (web2c)Memory dumps::) 'MPMEMS',\n'TEXMFINI'; suffix '.mem'.\n\n'MetaPost support'\n(MetaPost support files, used by DMP; *note (web2c)dmp\ninvocation::) 'MPSUPPORT'.\n\n'mf'\n(Metafont source, *note (web2c)mf invocation::) 'MFINPUTS'; suffix\n'.mf'; dynamic creation program: 'mktexmf'.\n\n'mfpool'\n(Metafont program strings, *note (web2c)pooltype invocation::)\n'MFPOOL', 'TEXMFINI'; suffix '.pool'.\n\n'mft'\n('MFT' style file, *note (web2c)mft invocation::) 'MFTINPUTS';\nsuffix '.mft'.\n\n'misc fonts'\n(font-related files that don't fit the other categories)\n'MISCFONTS'\n\n'mlbib'\n(MlBibTeX bibliography source) 'MLBIBINPUTS', 'BIBINPUTS',\n'TEXBIB'; suffixes '.mlbib', '.mlbib'.\n\n'mlbst'\n(MlBibTeX style) 'MLBSTINPUTS', 'BSTINPUTS'; suffixes '.mlbst',\n'.bst'.\n\n'mp'\n(MetaPost source, *note (web2c)mpost invocation::) 'MPINPUTS';\nsuffix '.mp'.\n\n'mppool'\n(MetaPost program strings, *note (web2c)pooltype invocation::)\n'MPPOOL', 'TEXMFINI'; suffix '.pool'.\n\n'ocp'\n(Omega compiled process files) 'OCPINPUTS';\nsuffix '.ocp'; dynamic creation program: 'MakeOmegaOCP'.\n\n'ofm'\n(Omega font metrics) 'OFMFONTS', 'TEXFONTS';\nsuffixes '.ofm', '.tfm'; dynamic creation program: 'MakeOmegaOFM'.\n\n'opentype fonts'\n(OpenType fonts) 'OPENTYPEFONTS'.\n\n'opl'\n(Omega property lists) 'OPLFONTS', 'TEXFONTS'; suffix '.opl'.\n\n'otp'\n(Omega translation process files) 'OTPINPUTS'; suffix '.otp'.\n\n'ovf'\n(Omega virtual fonts) 'OVFFONTS', 'TEXFONTS'; suffix '.ovf'.\n\n'ovp'\n(Omega virtual property lists) 'OVPFONTS', 'TEXFONTS'; suffix\n'.ovp'.\n\n'pdftex config'\n(PDFTeX-specific configuration files) 'PDFTEXCONFIG'.\n\n'pk'\n(packed bitmap fonts, *note (dvips)Glyph files::) 'PROGRAMFONTS'\n(PROGRAM being 'XDVI', etc.), 'PKFONTS', 'TEXPKS', 'GLYPHFONTS',\n'TEXFONTS'; suffix 'pk'; dynamic creation program: 'mktexpk'.\n\n'PostScript header'\n(downloadable PostScript, *note (dvips)Header files::)\n'TEXPSHEADERS', 'PSHEADERS'; additional suffix '.pro'.\n\n'ris'\n(RIS bibliography files, primarily for Biber,\n) 'RISINPUTS' suffix '.ris'.\n\n'subfont definition files'\n(subfont definition files) 'SFDFONTS' suffix '.sfd'.\n\n'tex'\n(TeX source, *note (web2c)tex invocation::) 'TEXINPUTS'; suffix\n'.tex'; additional suffixes: none, because such a list cannot be\ncomplete; dynamic creation program: 'mktextex'.\n\n'TeX system documentation'\n(Documentation files for the TeX system) 'TEXDOCS'.\n\n'TeX system sources'\n(Source files for the TeX system) 'TEXSOURCES'.\n\n'texmfscripts'\n(Architecture-independent executables distributed in the texmf\ntrees) 'TEXMFSCRIPTS'.\n\n'texpool'\n(TeX program strings, *note (web2c)pooltype invocation::)\n'TEXPOOL', 'TEXMFINI'; suffix '.pool'.\n\n'tfm'\n(TeX font metrics, *note (dvips)Metric files::) 'TFMFONTS',\n'TEXFONTS'; suffix '.tfm'; dynamic creation program: 'mktextfm'.\n\n'Troff fonts'\n(Troff fonts, used by DMP; *note (web2c)DMP invocation::)\n'TRFONTS'.\n\n'truetype fonts'\n(TrueType outline fonts) 'TTFONTS'; suffixes '.ttf' and '.TTF',\n'.ttc' and '.TTC', '.dfont'.\n\n'type1 fonts'\n(Type 1 PostScript outline fonts, *note (dvips)Glyph files::)\n'T1FONTS', 'T1INPUTS', 'TEXPSHEADERS', 'DVIPSHEADERS'; suffixes\n'.pfa', '.pfb'.\n\n'type42 fonts'\n(Type 42 PostScript outline fonts) 'T42FONTS'.\n\n'vf'\n(virtual fonts, *note (dvips)Virtual fonts::) 'VFFONTS',\n'TEXFONTS'; suffix '.vf'.\n\n'web'\n(WEB input files) 'WEBINPUTS'; suffix '.web'; additional suffix\n'.ch'.\n\n'web2c files'\n(files specific to the web2c implementation) 'WEB2C'.\n\nThere are two special cases, because the paths and environment\nvariables always depend on the name of the program: the variable name is\nconstructed by converting the program name to upper case, and then\nappending 'INPUTS'. Assuming the program is called 'foo', this gives us\nthe following table.\n\n'other text files'\n(text files used by 'foo') 'FOOINPUTS'.\n\n'other binary files'\n(binary files used by 'foo') 'FOOINPUTS'.\n\nIf an environment variable by these names are set, the corresponding\n'texmf.cnf' definition won't be looked at (unless, as usual, the\nenvironment variable value has an extra ':'). *Note Default\nexpansion::.\n\nFor the font variables, the intent is that:\n* 'TEXFONTS' is the default for everything.\n\n* 'GLYPHFONTS' is the default for bitmap (or, more precisely,\nnon-metric) files.\n\n* Each font format has a variable of its own.\n\n* Each program has its own font override path as well; e.g.,\n'DVIPSFONTS' for Dvipsk. Again, this is for bitmaps, not metrics.\n", "subsections": [] }, "File: kpathsea.info, Node: File lookup, Next: Glyph lookup, Prev: Supported file formats, Up: TeX support": { "content": "", "subsections": [ { "name": "6.2 File lookup", "content": "" } ] }, "This section describes how Kpathsea searches for most files (bitmap font": { "content": "searches are the exception, as described in the next section).\n\nHere is the search strategy for a file NAME:\n\n1. If the file format defines default suffixes, and the suffix of NAME\nname is not already a known suffix for that format, try the name\nwith each default appended, and use alternative names found in the\nfontmaps if necessary. Example: given 'foo.bar', look for\n'foo.bar.tex'.\n\n2. Search for NAME, and if necessary for alternative names found in\nthe fontmaps. Example: given 'foo.bar', we also look for\n'foo.bar'.\n\n3. If the file format defines a program to invoke to create missing\nfiles, run it (*note mktex scripts::).\n\nThe order in which we search for \"suffixed\" name (item 1) or the\n\"as-is\" name (item 2) is controlled by the 'trystdextensionfirst'\nconfiguration value. The default set in 'texmf.cnf' is true, since\ncommon suffixes are already recognized: 'babel.sty' will only look for\n'babel.sty', not 'babel.sty.tex', regardless of this setting.\n\nWhen the suffix is unknown (e.g., 'foo.bar'), both names are always\ntried; the difference is the order in which they are tried.\n\n'trystdextensionfirst' only affects names being looked up which\n*already* have an extension. A name without an extension (e.g., 'tex\nstory') will always have an extension added first.\n\nThis algorithm is implemented in the function 'kpathseafindfile' in\nthe source file 'kpathsea/tex-file.c'. You can watch it in action with\nthe debugging options (*note Debugging::).\n", "subsections": [] }, "File: kpathsea.info, Node: Glyph lookup, Next: Suppressing warnings, Prev: File lookup, Up: TeX support": { "content": "", "subsections": [ { "name": "6.3 Glyph lookup", "content": "" } ] }, "This section describes how Kpathsea searches for a bitmap font in GF or": { "content": "PK format (or either) given a font name (e.g., 'cmr10') and a resolution\n(e.g., 600).\n\nHere is an outline of the search strategy (details in the sections\nbelow) for a file NAME at resolution DPI. The search stops at the first\nsuccessful lookup.\n\n1. Look for an existing file NAME.DPIFORMAT in the specified\nformat(s).\n\n2. If NAME is an alias for a file F in the fontmap file\n'texfonts.map', look for F.DPI.\n\n3. Run an external program (typically named 'mktexpk') to generate the\nfont (*note mktex scripts::)\n\n4. Look for FALLBACK.DPI, where FALLBACK is some last-resort font\n(typically 'cmr10').\n\nThis is implemented in 'kpathseafindglyph' in\n'kpathsea/tex-glyph.c'.\n\n* Menu:\n\n* Basic glyph lookup:: Features common to all glyph lookups.\n* Fontmap:: Aliases for fonts.\n* Fallback font:: Resolutions and fonts of last resort.\n", "subsections": [] }, "File: kpathsea.info, Node: Basic glyph lookup, Next: Fontmap, Up: Glyph lookup": { "content": "", "subsections": [] }, "When Kpathsea looks for a bitmap font NAME at resolution DPI in a format": { "content": "FORMAT, it first checks each directory in the search path for a file\n'NAME.DPIFORMAT'; for example, 'cmr10.600pk'. Kpathsea looks for a PK\nfile first, then a GF file.\n\nIf that fails, Kpathsea looks for 'dpiDPI/NAME.FORMAT'; for example,\n'dpi600/cmr10.pk'. This is how fonts are typically stored on\nfilesystems (such as DOS) that permit only three-character extensions.\n\nIf that fails, Kpathsea looks for a font with a close-enough DPI.\n\"Close enough\" is defined by the macro 'KPSEBITMAPTOLERANCE' in\n'kpathsea/tex-glyph.h' to be 'DPI / 500 + 1'. This is slightly more\nthan the 0.2% minimum allowed by the DVI standard\n().\n", "subsections": [] }, "File: kpathsea.info, Node: Fontmap, Next: Fallback font, Prev: Basic glyph lookup, Up: Glyph lookup": { "content": "", "subsections": [] }, "If a bitmap font or metric file is not found with the original name (see": { "content": "the previous section), Kpathsea looks through any \"fontmap\" files for an\n\"alias\" for the original font name. These files are named\n'texfonts.map' and searched for along the 'TEXFONTMAPS'\nenvironment/config file variable. All 'texfonts.map' files that are\nfound are read; earlier definitions override later ones.\n\nThis feature is intended to help in two respects:\n\n1. An alias name is limited in length only by available memory, not by\nyour filesystem. Therefore, if you want to ask for 'Times-Roman'\ninstead of 'ptmr', you can (you get 'ptmr8r').\n\n2. A few fonts have historically had multiple names: specifically,\nLaTeX's \"circle font\" has variously been known as 'circle10',\n'lcircle10', and 'lcirc10'. Aliases can make all the names\nequivalent, so that it no longer matters what the name of the\ninstalled file is; TeX documents will find their favorite name.\n\nThe format of fontmap files is straightforward:\n\n* Comments start with the last '%' on a line and continue to the end\nof the line. (This provides for names that include a %,\nill-advised as that may be.)\n\n* Blank lines are ignored.\n\n* Each nonblank line is broken up into a series of \"words\": a\nsequence of non-whitespace characters.\n\n* If the first word is 'include', the second word is used as a\nfilename, and it is searched for and read.\n\n* Otherwise, the first word on each line is the true filename;\n\n* the second word is the alias;\n\n* subsequent words are ignored.\n\nIf an alias has an extension, it matches only those files with that\nextension; otherwise, it matches anything with the same root, regardless\nof extension. For example, an alias 'foo.tfm' matches only when\n'foo.tfm' is being searched for; but an alias 'foo' matches 'foo.vf',\n'foo.600pk', etc.\n\nAs an example, here is an excerpt from the 'texfonts.map' in the", "subsections": [] }, "Web2c distribution. It makes the old and new names of the LaTeX circle": { "content": "fonts equivalent.\n\ncircle10 lcircle10\ncircle10 lcirc10\nlcircle10 circle10\nlcircle10 lcirc10\nlcirc10 circle10\nlcirc10 lcircle10\n...\n\nFontmaps are implemented in the file 'kpathsea/fontmap.c'. The\nFontname distribution has much more information on font naming (*note\n(fontname)::).\n", "subsections": [] }, "File: kpathsea.info, Node: Fallback font, Prev: Fontmap, Up: Glyph lookup": { "content": "", "subsections": [] }, "If a bitmap font cannot be found or created at the requested size,": { "content": "Kpathsea looks for the font at a set of \"fallback resolutions\". You\nspecify these resolutions as a colon-separated list (like search paths).", "subsections": [] }, "Kpathsea looks first for a program-specific environment variable (e.g.,": { "content": "'DVIPSSIZES' for Dvipsk), then the environment variable 'TEXSIZES', then\na default specified at compilation time (the Make variable\n'defaulttexsizes'). You can set this list to be empty if you prefer to\nfind fonts at their stated size or not at all.\n\nFinally, if the font cannot be found even at the fallback\nresolutions, Kpathsea looks for a fallback font, typically 'cmr10'.\nPrograms must enable this feature by calling 'kpathseainitprog' (*note\nCalling sequence::); the default is no fallback font.\n", "subsections": [] }, "File: kpathsea.info, Node: Suppressing warnings, Next: mktex scripts, Prev: Glyph lookup, Up: TeX support": { "content": "", "subsections": [ { "name": "6.4 Suppressing warnings", "content": "" } ] }, "Kpathsea provides a way to suppress selected usually-harmless warnings;": { "content": "this is useful at large sites where most users are not administrators,\nand thus the warnings are merely a source of confusion, not a help. To\ndo this, you set the environment variable or configuration file value\n'TEXHUSH' to a colon-separated list of values. Here are the\npossibilities:\n\n'all'\nSuppress everything possible.\n\n'checksum'\nSuppress mismatched font checksum warnings.\n\n'lostchar'\nSuppress warnings when a character is missing from a font that a\nDVI or VF file tries to typeset.\n\n'none'\nDon't suppress any warnings.\n\n'readable'\nSuppress warnings about attempts to access a file whose permissions\nrender it unreadable.\n\n'special'\nSuppresses warnings about an unimplemented or unparsable '\\special'\ncommand.\n\n'tex-hush.c' defines the function that checks the variable value. Each\ndriver implements its own checks where appropriate.\n", "subsections": [] }, "File: kpathsea.info, Node: mktex scripts, Prev: Suppressing warnings, Up: TeX support": { "content": "", "subsections": [ { "name": "6.5 'mktex' scripts", "content": "" } ] }, "If Kpathsea cannot otherwise find a file, for some file types it is": { "content": "configured by default to invoke an external program to create it\ndynamically (*note mktex configuration::). These are collectively known\nas \"'mktex' scripts\", since most of them are named 'mktex...'.\n\nFor example, this is useful for fonts (bitmaps, TFM's, and\narbitrarily-sizable Metafont sources such as the Sauter and EC fonts),\nsince any given document can use fonts never before referenced.", "subsections": [] }, "Building all fonts in advance is therefore impractical, if not": { "content": "impossible.\n\nIt is also useful for the TeX '.fmt' (and Metafont '.base' and\nMetapost '.mem' files, *note (Web2c)Memory dumps::), where\npre-generating every format consumes a lot of both time and space.\n\nThe script is passed the name of the file to create and possibly\nother arguments, as explained below. It must echo the full pathname of\nthe file it created (and nothing else) to standard output; it can write\ndiagnostics to standard error.\n\n* Menu:\n\n* config: mktex configuration.\n* names: mktex script names.\n* args: mktex script arguments.\n", "subsections": [] }, "File: kpathsea.info, Node: mktex configuration, Next: mktex script names, Up: mktex scripts": { "content": "", "subsections": [] }, "The list of file types and program names that can run an external": { "content": "program to create missing files is listed in the next section. In the\nabsence of 'configure' options specifying otherwise, everything but\n'mktextex' will be enabled by default. The 'configure' options to\nchange the defaults are:\n", "subsections": [ { "name": "--without-mktexfmt-default", "content": "", "long": "--without-mktexfmt-default" }, { "name": "--without-mktexmf-default", "content": "", "long": "--without-mktexmf-default" }, { "name": "--without-mktexocp-default", "content": "", "long": "--without-mktexocp-default" }, { "name": "--without-mktexofm-default", "content": "", "long": "--without-mktexofm-default" }, { "name": "--without-mktexpk-default", "content": "", "long": "--without-mktexpk-default" }, { "name": "--without-mktextfm-default", "content": "", "long": "--without-mktextfm-default" }, { "name": "--with-mktextex-default", "content": "The 'configure' setting is overridden if the environment variable or\nconfiguration file value named for the script is set; e.g., 'MKTEXPK'\n(*note mktex script arguments::).\n\n'mktexfmt' reads a file 'fmtutil.cnf', typically located in\n'texmf/web2c/' to glean its configuration information. The rest of the\nfiles and features in this section are primarily intended for the font\ngeneration scripts.\n\nAs distributed, all the scripts source a file 'texmf/web2c/mktex.cnf'\nif it exists, so you can override various defaults. See 'mktex.opt',\nfor instance, which defines the default mode, resolution, some special\ndirectory names, etc. If you prefer not to change the distributed\nscripts, you can simply create 'mktex.cnf' with the appropriate\ndefinitions (you do not need to create it if you have nothing to put in\nit). 'mktex.cnf' has no special syntax; it's an arbitrary Bourne shell\nscript. The distribution contains a sample 'mktex.cnf' for you to copy\nand modify as you please (it is not installed anywhere).\n\nIn addition, you can configure a number of features with the\n'MTFEATURES' variable, which you can define:\n\n* in 'mktex.opt', as just mentioned;\n\n* by editing the file 'mktex.opt', either before 'make install' (in\nthe source hierarchy) or after (in the installed hierarchy);\n\n* or in the environment.\n\nIf none of the options below are enabled, 'mktexpk', 'mktextfm', and\n'mktexmf' follow the following procedure to decide where fonts should be\ninstalled. Find the tree where the font's sources are, and test the\npermissions of the 'fonts' directory of that tree to determine whether\nit is writable. If it is, put the files in the tree in appropriate\nlocations. If it isn't writable, see whether the tree is a system tree\n(named in 'SYSTEXMF'). If so, the 'VARTEXFONTS' tree is used. In all\nother cases the working directory is used.\n\nThe 'appendonlydir' option is enabled by default.\n\n'appendonlydir'\nTell 'mktexdir' to create directories append-only, i.e., set their\nsticky bit (*note (coreutils)Mode Structure::). This feature is\nsilently ignored on non-Unix platforms (e.g. Windows/NT and\nMS-DOS) which don't support similar functionality. This feature is\nenabled by default.\n\n'dosnames'\nUse 8.3 names; e.g., 'dpi600/cmr10.pk' instead of 'cmr10.600pk'.\nNote that this feature only affects filenames that would otherwise\nclash with other TeX-related filenames; 'mktex' scripts do nothing\nabout filenames which exceed the 8+3 MS-DOS limits but remain\nunique when truncated (by the OS) to these limits, and nether do\nthe scripts care about possible clashes with files which aren't\nrelated with TeX. For example, 'cmr10.600pk' would clash with\n'cmr10.600gf' and is therefore changed when 'dosnames' is in\neffect, but 'mf.pool' and 'mp.base' don't clash with any\nTeX-related files and are therefore unchanged.\n\nThis feature is turned on by default on MS-DOS. If you do not wish\n'dosnames' to be set on an MS-DOS platform, you need to set the\n'MTFEATURES' environment variable to a value that doesn't include\n'dosnames'. You can also change the default setting by editing\n'mktex.opt', but only if you use the 'mktex' shell scripts; the\nemulation programs don't consult 'mktex.opt'.\n\n'fontmaps'\nInstead of deriving the location of a font in the destination tree\nfrom the location of the sources, the aliases and directory names\nfrom the Fontname distribution are used. (*note Introduction:\n(fontname)Top.).\n\n'nomfdrivers'\nLet mktexpk and mktextfm create metafont driver files in a\ntemporary directory. These will be used for just one metafont run\nand not installed permanently.\n\n'nomode'\nOmit the directory level for the mode name; this is fine as long as\nyou generate fonts for only one mode.\n\n'stripsupplier'\nOmit the font supplier name directory level.\n\n'striptypeface'\nOmit the font typeface name directory level.\n\n'strip'\nOmit the font supplier and typeface name directory levels. This\nfeature is deprecated in favour of 'stripsupplier' and\n'striptypeface'.\n\n'varfonts'\nWhen this option is enabled, fonts that would otherwise be written\nin system texmf tree go to the 'VARTEXFONTS' tree instead. The\ndefault value in 'kpathsea/Makefile.in' is '/var/tmp/texfonts'.\nThe 'Linux File System Standard' recommends '/var/tex/fonts'.\n\nThe 'varfonts' setting in 'MTFEATURES' is overridden by the\n'USEVARTEXFONTS' environment variable: if set to '1', the feature\nis enabled, and if set to '0', the feature is disabled.\n\n'texmfvar'\nForce generated files that would go into a system tree (as defined\nby 'SYSTEXMF') into 'TEXMFVAR'. Starting with teTeX-3.0, the\nvariable 'TEXMFVAR' is always set. The 'varfonts' feature takes\nprecedence if also set.\n\nThe 'texmfvar' setting in 'MTFEATURES' is overridden by the\n'USETEXMFVAR' environment variable: if set to '1', the feature is\nenabled, and if set to '0', the feature is disabled.\n", "long": "--with-mktextex-default" } ] }, "File: kpathsea.info, Node: mktex script names, Next: mktex script arguments, Prev: mktex configuration, Up: mktex scripts": { "content": "", "subsections": [] }, "The following table shows the default name of the script for each of the": { "content": "file types which support runtime generation.\n\n'mktexfmt'\n('.fmt', '.base', '.mem') TeX/Metafont/MetaPost formats. This\nscript is also named 'fmtutil', and reads 'fmtutil.cnf' for\nconfiguration information.\n\n'mktexmf'\n('.mf') Metafont input files.\n\n'mkocp'\n('.ocp') Omega compiled process files.\n\n'mkofm'\n('.ofm') Omega font metric files.\n\n'mktexpk'\n('pk') Glyph fonts.\n\n'mktextex'\n('.tex') TeX input files (disabled by default).\n\n'mktextfm'\n('.tfm') TFM files.\n", "subsections": [] }, "These names can be overridden by an environment variable specific to the": { "content": "program--for example, 'DVIPSMAKEPK' for Dvipsk.\n\nIf a 'mktex...' script fails, the invocation is appended to a file\n'missfont.log' (by default) in the current directory. You can then\nexecute the log file to create the missing files after fixing the\nproblem.\n\nIf the current directory is not writable and the environment variable\nor configuration file value 'TEXMFOUTPUT' is set, its value is used.", "subsections": [] }, "Otherwise, nothing is written. The name 'missfont.log' is overridden by": { "content": "the 'MISSFONTLOG' environment variable or configuration file value.\n", "subsections": [] }, "File: kpathsea.info, Node: mktex script arguments, Prev: mktex script names, Up: mktex scripts": { "content": "", "subsections": [] }, "The first argument to a 'mktex' script is always the name of the file to": { "content": "be created.\n\nIn the default 'mktexpk' implementation, additional arguments may\nalso be passed:\n\n'--dpi NUM'\nSets the resolution of the generated font to NUM.\n'--mfmode NAME'\nSets the Metafont mode to NAME.\n'--bdpi NUM'\nSets the \"base dpi\" for the font. This must match the mode being\nused.\n'--mag STRING'\nA \"magstep\" string suitable for the Metafont 'mag' variable. This\nmust match the combination of BDPI and DPI being used.\n'--destdir STRING'\nA directory name. If the directory is absolute, it is used as-is.\nOtherwise, it is appended to the root destination directory set in\nthe script.\n", "subsections": [] }, "File: kpathsea.info, Node: Programming, Next: Reporting bugs, Prev: TeX support, Up: Top": { "content": "", "subsections": [] }, "7 Programming": { "content": "This chapter is for programmers who wish to use Kpathsea. *Note", "subsections": [] }, "Introduction::, for the conditions under which you may do so (in short,": { "content": "it is released under LGPLv2.1 or later).\n\n* Menu:\n\n* Overview: Programming overview. Introduction.\n* Calling sequence:: Specifics of what to call.\n* Program-specific files:: How to handle these.\n* Config: Programming with config files. Getting info from texmf.cnf.\n", "subsections": [] }, "File: kpathsea.info, Node: Programming overview, Next: Calling sequence, Up: Programming": { "content": "", "subsections": [ { "name": "7.1 Programming overview", "content": "" } ] }, "Aside from this manual, your best source of information is the source to": { "content": "the programs that use Kpathsea (*note Introduction::). First, Kpsewhich\nis a small utility program whose sole purpose is to exercise the main\npath-searching functionality. Of the drivers, Dviljk is probably the\nsimplest full application program. Xdvik adds VF support and the\ncomplication of X resources. Dvipsk adds the complication of its own\nconfig files. Web2c is source code I also maintain, so it uses Kpathsea\nrather straightforwardly, but is of course complicated by the Web to C\ntranslation.\n\nWhen looking at these program sources, you should know that previous\nversions of the library had a different programming interface; the\ncurrent interface supports re-entrancy. Historically, the library\nfunction names were prefixed with 'kpse' instead of 'kpathsea', and\nthey did not need an instance variable as first argument. This change\nwas made in 2009. The old functions will never disappear, and can\nreliably continue to be used when they suffice, as they do for the\nprograms above. The main application using the re-entrant API is the\nMetaPost library used by MetaPost and LuaTeX.\n\nBeyond these examples, the '.h' files in the Kpathsea source describe\nthe interfaces and functionality (and of course the '.c' files define\nthe actual routines, which are the ultimate documentation).\n'pathsearch.h' declares the basic searching routine. 'tex-file.h' and\n'tex-glyph.h' define the interfaces for looking up particular kinds of\nfiles. In view of the way the headers depend on each other, it is\nrecommended to use '#include ', which includes\nevery Kpathsea header.\n\nIf you want to include only specific headers, you should still\nconsider including 'kpathsea/config.h' before including any other", "subsections": [] }, "Kpathsea header, as it provides symbols used in the other headers. Note": { "content": "that 'kpathsea/config.h' includes 'kpathsea/c-auto.h', which is\ngenerated by Autoconf.\n\nThe library provides no way for an external program to register new\nfile types: 'tex-file.[ch]' must be modified to do this. For example,", "subsections": [] }, "Kpathsea has support for looking up Dvips config files, even though no": { "content": "program other than Dvips will likely ever want to do so. I felt this\nwas acceptable, since along with new file types should also come new\ndefaults in 'texmf.cnf' (and its descendant 'paths.h'), since it's\nsimplest for users if they can modify one configuration file for all\nkinds of paths.\n\nKpathsea does not parse any formats itself; it barely opens any\nfiles. Its primary purpose is to return filenames. The GNU font\nutilities does contain libraries to read TFM, GF, and PK files, as do\nthe programs above, of course.\n", "subsections": [] }, "File: kpathsea.info, Node: Calling sequence, Next: Program-specific files, Prev: Programming overview, Up: Programming": { "content": "", "subsections": [ { "name": "7.2 Calling sequence", "content": "" } ] }, "The typical way to use Kpathsea in your program goes something like": { "content": "this:\n\n1. Call 'kpathseanew' to create a new library instance. This\nvariable must be passed as the first argument to all the following\nlibrary functions. The rest of this manual will be using 'kpse' as\na placeholder for the name of this variable.\n\n2. Call 'kpathseasetprogramname' with 'argv[0]' as the second\nargument; the third argument is a string or 'NULL'. The third\nargument is used by Kpathsea as the program name for the '.PROGRAM'\nfeature of config files (*note Config files::). If the third\nargument is 'NULL', the value of the second argument is used. This\nfunction must be called before any other use of the Kpathsea\nlibrary.\n\n'kpathseasetprogramname' always sets the variables\n'kpse->invocationname' and 'kpse->invocationshortname'. These\nvariables are used in the error message macros defined in\n'kpathsea/lib.h'. It sets the variable 'kpse->programname' to the\nprogram name it uses.\n\nIt also initializes debugging options based on the environment\nvariable 'KPATHSEADEBUG' (if that is set).\n\nFinally, it sets the environment variables 'SELFAUTOLOC',\n'SELFAUTODIR' and 'SELFAUTOPARENT' to the location, parent and\ngrandparent directory of the executable, removing '.' and '..' path\nelements and resolving symbolic links. These are used in the\ndefault configuration file to allow people to invoke TeX from\nanywhere. You can use 'kpsewhich --expand-var=\\$SELFAUTOLOC',\netc., to see the values.\n\n3. Set debugging options. *Note Debugging::. If your program doesn't\nhave a debugging option already, you can define one and set\n'kpse->debug' to the number that the user supplies (as in Dviljk\nand Web2c), or you can just omit this altogether (people can always\nset 'KPATHSEADEBUG'). If you do have runtime debugging already,\nyou need to merge Kpathsea's options with yours (as in Dvipsk and\nXdvik).\n\n4. If your program has its own configuration files that can define\nsearch paths, you should assign those paths to the 'clientpath'\nmember in the appropriate element of the 'kpse->formatinfo' array.\n(This array is indexed by file type; see 'tex-file.h'.) See\n'resident.c' in Dvipsk for an example.\n\n5. Call 'kpathseainitprog' (see 'proginit.c'). It's useful for the\nDVI drivers, at least, but for other programs it may be simpler to\nextract the parts of it that actually apply. This does not\ninitialize any paths, it just looks for (and sets) certain\nenvironment variables and other random information. (A search path\nis always initialized at the first call to find a file of that\ntype; this eliminates much useless work, e.g., initializing the\nBibTeX search paths in a DVI driver.)\n\n6. The routine to actually find a file of type FORMAT is\n'kpathseafindfile'. You can call 'kpathseafindfile' after\ndoing only the first and second of the initialization steps\nabove--Kpathsea automatically reads the 'texmf.cnf' generic config\nfiles, looks for environment variables, and does expansions at the\nfirst lookup.\n\n7. To find PK and/or GF bitmap fonts, the routine is\n'kpathseafindglyph', defined in 'tex-glyph.h'. This returns a\nstructure in addition to the resultant filename, because fonts can\nbe found in so many ways. See the documentation in the source.\n\n8. To actually open a file, not just return a filename, call\n'kpathseaopenfile'. This function takes the name to look up and\na Kpathsea file format as arguments, and returns the usual 'FILE\n*'. It always assumes the file must exist, and thus will search\nthe disk if necessary (unless the search path specified '!!',\netc.). In other words, if you are looking up a VF or some other\nfile that need not exist, don't use this.\n\n9. TeX can write output files, via the '\\openout' primitive; this\nopens a security hole vulnerable to Trojan horse attack: an\nunwitting user could run a TeX program that overwrites, say,\n'~/.rhosts'. Analogous security holes exist for many other\nprograms. To alleviate this, there is a configuration variable\n'openoutany', which selects one of three levels of security. When\nit is set to 'a' (for \"any\"), no restrictions are imposed. When it\nis set to 'r' (for \"restricted\"), filenames beginning with '.' are\ndisallowed (except '.tex' because LaTeX needs it). When it is set\nto 'p' (for \"paranoid\") additional restrictions are imposed: an\nabsolute filename must refer to a file in (a subdirectory) of\n'TEXMFOUTPUT', and any attempt to go up a directory level is\nforbidden (that is, paths may not contain a '..' component). The\nparanoid setting is the default. (For backwards compatibility, 'y'\nand '1' are synonyms of 'a', while 'n' and '0' are synonyms for\n'r'.) The function 'kpathseaoutnameok', with a filename as\nsecond argument, returns 'true' if that filename is acceptable to\nbe opend for output or 'false' otherwise.\n\n10. Similarly, the function 'kpathseainnameok', with a filename as\nsecond argument, returns 'true' if that filename is acceptable to\nbe opend for input or 'false' otherwise, depending on the value of\nthe configuration variable 'openinany' (with 'a' as default).\n\n11. To close the kpathsea library instance you are using, call\n'kpathseafinish'. This function closes any open log files and\nfrees the memory used by the instance.\n\nKpathsea also provides many utility routines. Some are generic: hash\ntables, memory allocation, string concatenation and copying, string\nlists, reading input lines of arbitrary length, etc. Others are\nfilename-related: default path, tilde, and variable expansion, 'stat'\ncalls, etc. (Perhaps someday I'll move the former to a separate\nlibrary.)\n\nThe 'c-*.h' header files can also help your program adapt to many\ndifferent systems. You will almost certainly want to use Autoconf and\nprobably Automake for configuring and building your software if you use\nKpathsea; I strongly recommend using Autoconf and Automake regardless.\nThey are available from .\n", "subsections": [] }, "File: kpathsea.info, Node: Program-specific files, Next: Programming with config files, Prev: Calling sequence, Up: Programming": { "content": "", "subsections": [ { "name": "7.3 Program-specific files", "content": "" } ] }, "Many programs will need to find some configuration files. Kpathsea": { "content": "contains some support to make it easy to place them in their own\ndirectories. The Standard TeX directory structure (*note Introduction:\n(tds)Top.), specifies that such files should go into a subdirectory\nnamed after the program, like 'texmf/ttf2pk'.\n\nTwo formats, 'kpseprogramtextformat' and\n'kpseprogrambinaryformat', use '.:$TEXMF/PROGRAM//' as their\ncompiled-in search path. To override this default, you can use the\nvariable 'PROGRAMINPUTS' in the environment and/or 'texmf.cnf'. That is\nto say, the name of the variable is constructed by converting the name\nof the program to upper case, and appending 'INPUTS'.\n\nThe only difference between these two formats is whether\n'kpathseaopenfile' will open the files it finds in text or binary\nmode.\n", "subsections": [] }, "File: kpathsea.info, Node: Programming with config files, Prev: Program-specific files, Up: Programming": { "content": "", "subsections": [ { "name": "7.4 Programming with config files", "content": "" } ] }, "You can (and probably should) use the same 'texmf.cnf' configuration": { "content": "file that Kpathsea uses for your program. This helps installers by\nkeeping all configuration in one place.\n\nTo retrieve a value for a configuration variable VAR, the best way is\nto call 'kpathseavarvalue' on the string 'VAR'. This will look first\nfor an environment variable VAR, then a config file value. The result\nwill be the value found or 'NULL'. This function is declared in\n'kpathsea/variable.h'. For an example, see the 'shellescape' code in\n'web2c/lib/texmfmp.c'.\n\nThe routine to do full variable and tilde expansion of an arbitrary\nstring in the context of a search path (as opposed to simply retrieving\na value) is 'kpathseavarexpand', also declared in\n'kpathsea/variable.h'. However, it's generally only necessary to set\nthe search path structure components as explained in the previous\nsection instead of using this directly. Because of its usage with any\ninput string, undefined '$FOO' constructs in the argument to\n'kpathseavarexpand' are returned literally ('\"$FOO\"'), while undefined\n'${FOO}' constructs are expanded to the empty string.\n\nIf for some reason you want to retrieve a value only from a config\nfile, not automatically looking for a corresponding environment\nvariable, call 'kpathseacnfget' (declared in 'kpathsea/cnf.h') with\nthe string VAR.\n\nNo initialization calls are needed.\n", "subsections": [] }, "File: kpathsea.info, Node: Reporting bugs, Next: Index, Prev: Programming, Up: Top": { "content": "", "subsections": [] }, "8 Reporting bugs": { "content": "", "subsections": [] }, "If you have problems or suggestions, please report them to": { "content": " using the bug checklist below.\n\nPlease report bugs in the documentation; not only factual errors or\ninconsistent behavior, but unclear or incomplete explanations, typos,\nwrong fonts, ...\n\n* Menu:\n\n* Bug checklist:: What to include in a good bug report.\n* Mailing lists:: Joining the bugs or announcements mailing lists.\n* Debugging:: Analyzing runtime problems.\n* Logging:: Recording searches.\n* Common problems:: When things go wrong.\n", "subsections": [] }, "File: kpathsea.info, Node: Bug checklist, Next: Mailing lists, Up: Reporting bugs": { "content": "", "subsections": [ { "name": "8.1 Bug checklist", "content": "" } ] }, "Before reporting a bug, please check below to be sure it isn't already": { "content": "known (*note Common problems::).\n\nBug reports should be sent via electronic mail to .\n\nThe general principle is that a good bug report includes all the\ninformation necessary for reproduction. Therefore, to enable\ninvestigation, your report should include the following:\n\n* The version number(s) of the program(s) involved, and of Kpathsea\nitself. You can get the former by giving a sole option '--version'\nto the program, and the latter by running 'kpsewhich --version'.\nThe 'NEWS' and 'ChangeLog' files also contain the version number.\n\n* The hardware, operating system (including version), compiler, and\n'make' program you are using (the output of 'uname -a' is a start\non the first two, though incomplete).\n\n* Any options you gave to 'configure'. This is recorded in the\n'config.status' files.\n\nIf you are reporting a bug in 'configure' itself, it's probably\nsystem-dependent, and it will be unlikely the maintainers can do\nanything useful if you merely report that thus-and-such is broken.\nTherefore, you need to do some additional work: for some bugs, you\ncan look in the file 'config.log' where the test that failed should\nappear, along with the compiler invocation and source program in\nquestion. You can then compile it yourself by hand, and discover\nwhy the test failed. Other 'configure' bugs do not involve the\ncompiler; in that case, the only recourse is to inspect the\n'configure' shell script itself, or the Autoconf macros that\ngenerated 'configure'.\n\n* The log of all debugging output, if the bug is in path searching.\nYou can get this by setting the environment variable\n'KPATHSEADEBUG' to '-1' before running the program. Please look\nat the log yourself to make sure the behavior is really a bug\nbefore reporting it; perhaps \"old\" environment variable settings\nare causing files not to be found, for example.\n\n* The contents of any input files necessary to reproduce the bug.\nFor bugs in DVI-reading programs, for example, this generally means\na DVI file (and any EPS or other files it uses)--TeX source files\nare helpful, but the DVI file is required, because that's the\nactual program input.\n\n* If you are sending a patch (do so if you can!), please do so in the\nform of a context diff ('diff -c') against the original\ndistribution source. Any other form of diff is either not as\ncomplete or harder for me to understand. Please also include a\n'ChangeLog' entry.\n\n* If the bug involved is an actual crash (i.e., core dump), it is\neasy and useful to include a stack trace from a debugger (I\nrecommend the GNU debugger GDB ().\nIf the cause is apparent (a 'NULL' value being dereferenced, for\nexample), please send the details along. If the program involved\nis TeX or Metafont, and the crash is happening at apparently-sound\ncode, however, the bug may well be in the compiler, rather than in\nthe program or the library (*note TeX or Metafont failing: TeX or\nMetafont failing.).\n\n* Any additional information that will be helpful in reproducing,\ndiagnosing, or fixing the bug.\n", "subsections": [] }, "File: kpathsea.info, Node: Mailing lists, Next: Debugging, Prev: Bug checklist, Up: Reporting bugs": { "content": "", "subsections": [ { "name": "8.2 Mailing lists", "content": "" } ] }, "Web2c and Kpathsea in general are discussed on the mailing list": { "content": ". You can subscribe and peruse the archives on the web\n.\n\nYou do not need to join to submit a report, nor will it affect\nwhether you get a response. Be aware that large data files are\nsometimes included in bug reports. If this is a problem for you, do not\njoin the list.\n\nIf you are looking for general TeX help, such as how to install a\nfull TeX system or how to use LaTeX, please see\n.\n", "subsections": [] }, "File: kpathsea.info, Node: Debugging, Next: Logging, Prev: Mailing lists, Up: Reporting bugs": { "content": "", "subsections": [ { "name": "8.3 Debugging", "content": "" } ] }, "Kpathsea provides a number of runtime debugging options, detailed below": { "content": "by their names and corresponding numeric values. When the files you\nexpect aren't being found, the thing to do is enable these options and\nexamine the output.\n\nYou can set these with some runtime argument (e.g., '-d') to the\nprogram; in that case, you should use the numeric values described in\nthe program's documentation (which, for Dvipsk and Xdvik, are different\nthan those below). It's best to give the '-d' (or whatever) option\nfirst, for maximal output. Dvipsk and Xdvik have additional\nprogram-specific debugging options as well.\n\nYou can also set the environment variable 'KPATHSEADEBUG'; in this\ncase, you should use the numbers below. If you run the program under a\ndebugger and set the instance variable 'kpse->debug', also use the\nnumbers below.\n\nIn any case, by far the simplest value to use is '-1', which will\nturn on all debugging output. This is usually better than guessing\nwhich particular values will yield the output you need.\n\nDebugging output always goes to standard error, so you can redirect\nit easily. For example, in Bourne-compatible shells:\ndvips -d -1 ... 2>/tmp/debug\n\nIt is sometimes helpful to run the standalone Kpsewhich utility\n(*note Invoking kpsewhich::), instead of the original program.\n\nIn any case, you cannot use the names below; you must always use\nsomebody's numbers. (Sorry.) To set more than one option, just sum the\ncorresponding numbers.\n\n'KPSEDEBUGSTAT (1)'\nReport 'stat'(2) calls. This is useful for verifying that your\ndirectory structure is not forcing Kpathsea to do many additional\nfile tests (*note Slow path searching::, and *note Subdirectory\nexpansion::). If you are using an up-to-date 'ls-R' database\n(*note Filename database::), this should produce no output unless a\nnonexistent file that must exist is searched for.\n\n'KPSEDEBUGHASH (2)'\nReport lookups in all hash tables: 'ls-R' and 'aliases' (*note\nFilename database::); font aliases (*note Fontmap::); and config\nfile values (*note Config files::). Useful when expected values\nare not being found, e.g.., file searches are looking at the disk\ninstead of using 'ls-R'.\n\n'KPSEDEBUGFOPEN (4)'\nReport file openings and closings. Especially useful when your\nsystem's file table is full, for seeing which files have been\nopened but never closed. In case you want to set breakpoints in a\ndebugger: this works by redefining 'fopen' ('fclose') to be\n'kpsefopentrace' ('kpsefclosetrace').\n\n'KPSEDEBUGPATHS (8)'\nReport general path information for each file type Kpathsea is\nasked to search. This is useful when you are trying to track down\nhow a particular path got defined--from 'texmf.cnf', 'config.ps',\nan environment variable, the compile-time default, etc. This is\nthe contents of the 'kpseformatinfotype' structure defined in\n'tex-file.h'.\n\n'KPSEDEBUGEXPAND (16)'\nReport the directory list corresponding to each path element\nKpathsea searches. This is only relevant when Kpathsea searches\nthe disk, since 'ls-R' searches don't look through directory lists\nin this way.\n\n'KPSEDEBUGSEARCH (32)'\nReport on each file search: the name of the file searched for, the\npath searched in, whether or not the file must exist (when drivers\nsearch for 'cmr10.vf', it need not exist), and whether or not we\nare collecting all occurrences of the file in the path (as with,\ne.g., 'texmf.cnf' and 'texfonts.map'), or just the first (as with\nmost lookups). This can help you correlate what Kpathsea is doing\nwith what is in your input file.\n\n'KPSEDEBUGVARS (64)'\nReport the value of each variable Kpathsea looks up. This is\nuseful for verifying that variables do indeed obtain their correct\nvalues.\n\n'GSFTOPKDEBUG (128)'\nActivates debugging printout specific to 'gsftopk' program.\n\n'MAKETEXDEBUG (512)'\nIf you use the optional 'mktex' programs instead of the traditional\nshell scripts, this will report the name of the site file\n('mktex.cnf' by default) which is read, directories created by\n'mktexdir', the full path of the 'ls-R' database built by\n'mktexlsr', font map searches, 'MTFEATURES' in effect, parameters\nfrom 'mktexnam', filenames added by 'mktexupd', and some subsidiary\ncommands run by the programs.\n\n'MAKETEXFINEDEBUG (1024)'\nWhen the optional 'mktex' programs are used, this will print\nadditional debugging info from functions internal to these\nprograms.\n\nDebugging output from Kpathsea is always written to standard error,\nand begins with the string 'kdebug:'. (Except for hash table buckets,\nwhich just start with the number, but you can only get that output\nrunning under a debugger. See comments at the 'hashsummaryonly'\nvariable in 'kpathsea/db.c'.)\n", "subsections": [] }, "File: kpathsea.info, Node: Logging, Next: Common problems, Prev: Debugging, Up: Reporting bugs": { "content": "", "subsections": [ { "name": "8.4 Logging", "content": "" } ] }, "Kpathsea can record the time and filename found for each successful": { "content": "search. This may be useful in finding good candidates for deletion when\nyour filesystem is full, or in discovering usage patterns at your site.\n\nTo do this, define the environment or config file variable\n'TEXMFLOG'. The value is the name of the file to append the information\nto. The file is created if it doesn't exist, and appended to if it\ndoes.\n\nEach successful search turns into one line in the log file: two words\nseparated by a space. The first word is the time of the search, as the\ninteger number of seconds since \"the epoch\", i.e., UTC midnight 1\nJanuary 1970 (more precisely, the result of the 'time' system call).\nThe second word is the filename.\n\nFor example, after 'setenv TEXMFLOG /tmp/log', running Dvips on\n'story.dvi' appends the following lines:\n\n774455887 /usr/local/share/texmf/dvips/config.ps\n774455887 /usr/local/share/texmf/dvips/psfonts.map\n774455888 /usr/local/share/texmf/dvips/texc.pro\n774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk\n774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk\n774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk\n774455889 /usr/local/share/texmf/dvips/texc.pro\n", "subsections": [] }, "Only filenames that are absolute are recorded, to preserve some": { "content": "semblance of privacy.\n\nIn addition to this Kpathsea-specific logging, 'pdftex' provides an\noption '-recorder' to write the names of all files accessed during a run\nto the file 'BASEFILE.fls'.\n\nFinally, most systems provide a general tool to output each system\ncall, thus including opening and closing files. It might be named\n'strace', 'truss', 'struss', or something else.\n", "subsections": [] }, "File: kpathsea.info, Node: Common problems, Prev: Logging, Up: Reporting bugs": { "content": "", "subsections": [ { "name": "8.5 Common problems", "content": "" } ] }, "Here are some common problems with configuration, compilation, linking,": { "content": "execution, ...\n\n* Menu:\n\n* Unable to find files:: If your program can't find fonts (or whatever).\n* Slow path searching:: If it takes forever to find anything.\n* Unable to generate fonts:: If mktexpk fails.\n* TeX or Metafont failing:: Likely compiler bugs.\n", "subsections": [] }, "File: kpathsea.info, Node: Unable to find files, Next: Slow path searching, Up: Common problems": { "content": "", "subsections": [] }, "If a program complains it cannot find fonts (or other input files), any": { "content": "of several things might be wrong. In any case, you may find the\ndebugging options helpful. *Note Debugging::.\n\n* Perhaps you simply haven't installed all the necessary files; the\nbasic fonts and input files are distributed separately from the\nprograms. *Note unixtex.ftp::.\n\n* You have (perhaps unknowingly) told Kpathsea to use search paths\nthat don't reflect where the files actually are. One common cause\nis having environment variables set from a previous installation,\nthus overriding what you carefully set in 'texmf.cnf' (*note\nSupported file formats::). System '/etc/profile' or other files\nsuch may be the culprit.\n\n* Your files reside in a directory that is only pointed to via a\nsymbolic link, in a leaf directory and is not listed in 'ls-R'.\n\nUnfortunately, Kpathsea's subdirectory searching has an\nirremediable deficiency: If a directory D being searched for\nsubdirectories contains plain files and symbolic links to other\ndirectories, but no true subdirectories, D will be considered a\nleaf directory, i.e., the symbolic links will not be followed.\n*Note Subdirectory expansion::.\n\nYou can work around this problem by creating an empty dummy\nsubdirectory in D. Then D will no longer be a leaf, and the\nsymlinks will be followed.\n\nThe directory immediately followed by the '//' in the path\nspecification, however, is always searched for subdirectories, even\nif it is a leaf. Presumably you would not have asked for the\ndirectory to be searched for subdirectories if you didn't want it\nto be.\n\n* If the fonts (or whatever) don't already exist, 'mktexpk' (or\n'mktexmf' or 'mktextfm') will try to create them. If these rather\ncomplicated shell scripts fail, you'll eventually get an error\nmessage saying something like 'Can't find font FONTNAME'. The best\nsolution is to fix (or at least report) the bug in 'mktexpk'; the\nworkaround is to generate the necessary fonts by hand with\nMetafont, or to grab them from a CTAN site (*note unixtex.ftp::).\n\n* There is a bug in the library. *Note Reporting bugs::.\n", "subsections": [] }, "File: kpathsea.info, Node: Slow path searching, Next: Unable to generate fonts, Prev: Unable to find files, Up: Common problems": { "content": "", "subsections": [] }, "If your program takes an excessively long time to find fonts or other": { "content": "input files, but does eventually succeed, here are some possible\nculprits:\n\n* Most likely, you just have a lot of directories to search, and that\ntakes a noticeable time. The solution is to create and maintain a\nseparate 'ls-R' file that lists all the files in your main TeX\nhierarchy. *Note Filename database::. Kpathsea always uses 'ls-R'\nif it's present; there's no need to recompile or reconfigure any of\nthe programs.\n\n* Your recursively-searched directories (e.g.,\n'/usr/local/share/texmf/fonts//'), contain a mixture of files and\ndirectories. This prevents Kpathsea from using a useful\noptimization (*note Subdirectory expansion::).\n\nIt is best to have only directories (and perhaps a 'README') in the\nupper levels of the directory structure, and it's very important to\nhave only files, and no subdirectories, in the leaf directories\nwhere the dozens of TFM, PK, or whatever files reside.\n\nIn any case, you may find the debugging options helpful in\ndetermining precisely when the disk or network is being pounded. *Note\nDebugging::.\n", "subsections": [] }, "File: kpathsea.info, Node: Unable to generate fonts, Next: TeX or Metafont failing, Prev: Slow path searching, Up: Common problems": { "content": "", "subsections": [] }, "Metafont outputs fonts in bitmap format, tuned for a particular device": { "content": "at a particular resolution, in order to allow for the highest-possible\nquality of output. Some DVI-to-whatever programs, such as Dvips, try to\ngenerate these on the fly when they are needed, but this generation may\nfail in several cases.\n\nIf 'mktexpk' runs, but fails with this error:\nmktexpk: Can't guess mode for NNN dpi devices.\nmktexpk: Use a config file to specify the mode, or update me.\nyou need to ensure the resolution and mode match; just specifying the\nresolution, as in '-D 360', is not enough.\n\nYou can specify the mode name with the '-mode' option on the Dvips\ncommand line, or in a Dvips configuration file (*note (dvips)Config\nfiles::), such as 'config.ps' in your document directory, '~/.dvipsrc'\nin your home directory, or in a system directory (again named\n'config.ps'). (Other drivers use other files, naturally.)\n\nFor example, if you need 360dpi fonts, you could include this in a\nconfiguration file:\nD 360\nM lqmed\n\nIf Metafont runs, but generates fonts at the wrong resolution or for\nthe wrong device, most likely 'mktexpk''s built-in guess for the mode is\nwrong, and you should override it as above.\n\nSee for a list of resolutions and mode\nnames for most devices (additional submissions are welcome).\n\nIf Metafont runs but generates fonts at a resolution of 2602dpi (and\nprints out the name of each character as well as just a character\nnumber, and maybe tries to display the characters), then your Metafont\nbase file probably hasn't been made properly. (It's using the default\n'proof' mode, instead of an actual device mode.) To make a proper\n'plain.base', assuming the local mode definitions are contained in a\nfile 'modes.mf', run the following command (assuming Unix):\n\ninimf \"plain; input modes; dump\"\n", "subsections": [] }, "Then copy the 'plain.base' file from the current directory to where the": { "content": "base files are stored on your system ('/usr/local/share/texmf/web2c' by\ndefault), and make a link (either hard or soft) from 'plain.base' to\n'mf.base' in that directory. *Note (web2c)inimf invocation::.\n\nIf 'mf' is a command not found at all by 'mktexpk', then you need to\ninstall Metafont (*note unixtex.ftp::).\n", "subsections": [] }, "File: kpathsea.info, Node: TeX or Metafont failing, Prev: Unable to generate fonts, Up: Common problems": { "content": "", "subsections": [] }, "If TeX or Metafont get a segmentation fault or otherwise fail while": { "content": "running a normal input file, the problem is usually a compiler bug\n(unlikely as that may sound). Even if the trip and trap tests are\npassed, problems may lurk. Optimization occasionally causes trouble in\nprograms other than TeX and Metafont themselves, too.\n\nFor a workaround, if you enabled any optimization flags, it's best to\nomit optimization entirely. In any case, the way to find the facts is\nto run the program under the debugger and see where it's failing.\n\nAlso, if you have trouble with a system C compiler, I advise trying\nthe GNU C compiler. And vice versa, unfortunately; but in that case I\nalso recommend reporting a bug to the GCC mailing list; see *note\n(gcc)Bugs::.\n\nTo report compiler bugs effectively requires perseverance and\nperspicacity: you must find the miscompiled line, and that usually\ninvolves delving backwards in time from the point of error, checking\nthrough TeX's (or whatever program's) data structures. Good luck.\n", "subsections": [] }, "File: kpathsea.info, Node: Index, Prev: Reporting bugs, Up: Top": { "content": "", "subsections": [] }, "Index": { "content": "* Menu:\n\n* !! and casefolding: Casefolding examples.\n(line 57)\n* !! in path specifications: ls-R. (line 57)\n* !! in TEXMFDBS: ls-R. (line 11)\n* $ expansion: Variable expansion. (line 6)\n* --all: Path searching options.\n(line 12)\n* --casefold-search: Path searching options.\n(line 19)\n* --cnf-line: Path searching options.\n(line 28)\n* --cnf-line, source for path: Path sources. (line 9)\n* --color=tty: ls-R. (line 25)\n* --debug=NUM: Auxiliary tasks. (line 9)\n* --dpi=NUM: Path searching options.\n(line 49)\n* --engine=NAME: Path searching options.\n(line 53)\n* --expand-braces=STRING: Auxiliary tasks. (line 12)\n* --expand-path=STRING: Auxiliary tasks. (line 16)\n* --expand-var=STRING: Auxiliary tasks. (line 34)\n* --format=NAME: Path searching options.\n(line 69)\n* --help: Standard options. (line 8)\n* --help-formats: Auxiliary tasks. (line 42)\n* --interactive: Path searching options.\n(line 151)\n* --mktex=FILETYPE: Path searching options.\n(line 156)\n* --mode=STRING: Path searching options.\n(line 162)\n* --must-exist: Path searching options.\n(line 167)\n* --no-casefold-search: Path searching options.\n(line 19)\n* --no-mktex=FILETYPE: Path searching options.\n(line 156)\n* --path=STRING: Path searching options.\n(line 172)\n* --progname=NAME: Path searching options.\n(line 180)\n* --safe-in-name=NAME: Auxiliary tasks. (line 48)\n* --safe-out-name=NAME: Auxiliary tasks. (line 48)\n* --show-path=NAME: Auxiliary tasks. (line 54)\n* --subdir=STRING: Path searching options.\n(line 185)\n* --var-brace-value=VARIABLE: Auxiliary tasks. (line 60)\n* --var-value=VARIABLE: Auxiliary tasks. (line 74)\n* --version: Standard options. (line 11)\n* --with-mktextex-default: mktex configuration. (line 12)\n* --without-mktexfmt-default: mktex configuration. (line 12)\n* --without-mktexmf-default: mktex configuration. (line 12)\n* --without-mktexocp-default: mktex configuration. (line 12)\n* --without-mktexofm-default: mktex configuration. (line 12)\n* --without-mktexpk-default: mktex configuration. (line 12)\n* --without-mktextfm-default: mktex configuration. (line 12)\n* -1 debugging value: Debugging. (line 23)\n* -A option to ls: ls-R. (line 39)\n* -D NUM: Path searching options.\n(line 49)\n* -iname, find predicate: Casefolding examples.\n(line 78)\n* -L option to ls: ls-R. (line 44)\n* . directories, ignored: ls-R. (line 39)\n* . files: ls-R. (line 39)\n* .2602gf: Unable to generate fonts.\n(line 36)\n* .afm: Supported file formats.\n(line 22)\n* .base: Supported file formats.\n(line 26)\n* .bib: Supported file formats.\n(line 30)\n* .bltxml: Supported file formats.\n(line 34)\n* .bst: Supported file formats.\n(line 38)\n* .cid: Supported file formats.\n(line 68)\n* .cmap: Supported file formats.\n(line 46)\n* .cnf: Supported file formats.\n(line 49)\n* .dll: Supported file formats.\n(line 42)\n* .enc: Supported file formats.\n(line 61)\n* .eps: Supported file formats.\n(line 79)\n* .epsi: Supported file formats.\n(line 79)\n* .fea: Supported file formats.\n(line 71)\n* .fmt: Supported file formats.\n(line 64)\n* .ist: Supported file formats.\n(line 84)\n* .lig: Supported file formats.\n(line 88)\n* .map: Supported file formats.\n(line 94)\n* .mem: Supported file formats.\n(line 97)\n* .mf: Supported file formats.\n(line 105)\n* .mft: Supported file formats.\n(line 113)\n* .mlbib: Supported file formats.\n(line 121)\n* .mlbst: Supported file formats.\n(line 125)\n* .mp: Supported file formats.\n(line 129)\n* .ocp: Supported file formats.\n(line 137)\n* .ofm: Supported file formats.\n(line 141)\n* .opl: Supported file formats.\n(line 148)\n* .otp: Supported file formats.\n(line 151)\n* .ovf: Supported file formats.\n(line 154)\n* .ovp: Supported file formats.\n(line 157)\n* .pfa: Supported file formats.\n(line 211)\n* .pfb: Supported file formats.\n(line 211)\n* .pk: Supported file formats.\n(line 164)\n* .pool: Supported file formats.\n(line 109)\n* .pool <1>: Supported file formats.\n(line 133)\n* .pool <2>: Supported file formats.\n(line 195)\n* .pro: Supported file formats.\n(line 169)\n* .PROGNAME qualifier in texmf.cnf: Config files. (line 50)\n* .rhosts, writable by TeX: Security. (line 10)\n* .ris: Supported file formats.\n(line 173)\n* .sfd: Supported file formats.\n(line 177)\n* .so: Supported file formats.\n(line 42)\n* .tex: Supported file formats.\n(line 180)\n* .tex file, included in ls-R: ls-R. (line 39)\n* .tfm: Supported file formats.\n(line 199)\n* .ttc: Supported file formats.\n(line 207)\n* .ttf: Supported file formats.\n(line 207)\n* .vf: Supported file formats.\n(line 219)\n* .w: Supported file formats.\n(line 53)\n* .web: Supported file formats.\n(line 53)\n* .web <1>: Supported file formats.\n(line 223)\n* / may not be /: Searching overview. (line 13)\n* /, trailing in home directory: Tilde expansion. (line 19)\n* //: Subdirectory expansion.\n(line 6)\n* /etc/profile: Unable to find files.\n(line 14)\n* /etc/profile and aliases: ls-R. (line 25)\n* /var/tmp/texfonts: mktex configuration. (line 113)\n* 2602gf: Unable to generate fonts.\n(line 36)\n* 8.3 filenames, using: mktex configuration. (line 68)\n* : may not be :: Searching overview. (line 13)\n* :: expansion: Default expansion. (line 6)\n* ; translated to : in texmf.cnf: Config files. (line 66)\n* = omitted in texmf.cnf and misparsing: Config files. (line 93)\n* \\, line continuation in texmf.cnf: Config files. (line 37)\n* \\openin: Searching overview. (line 31)\n* \\special, suppressing warnings about: Suppressing warnings.\n(line 31)\n* { expansion: Brace expansion. (line 6)\n* ~ expansion: Tilde expansion. (line 6)\n* absolute filenames: Searching overview. (line 58)\n* access system call: Casefolding examples.\n(line 86)\n* access warnings: Searching overview. (line 63)\n* AFMFONTS: Supported file formats.\n(line 22)\n* aliases for fonts: Fontmap. (line 6)\n* aliases, for filenames: Filename aliases. (line 6)\n* all: Suppressing warnings.\n(line 13)\n* all matches, finding: Path searching options.\n(line 12)\n* alphabetical order, not: Subdirectory expansion.\n(line 6)\n* announcement mailing list: Mailing lists. (line 6)\n* API, re-entrant: Programming overview.\n(line 16)\n* append-only directories and mktexpk: Security. (line 36)\n* appendonlydir: mktex configuration. (line 60)\n* Apple filesystem, case-insensitive: Casefolding rationale.\n(line 6)\n* arguments to mktex: mktex script arguments.\n(line 6)\n* argv[0]: Calling sequence. (line 14)\n* autoconf, recommended: Calling sequence. (line 117)\n* automounter, and ls-R: ls-R. (line 46)\n* auxiliary tasks: Auxiliary tasks. (line 6)\n* Bach, Johann Sebastian: Default expansion. (line 41)\n* backslash-newline: Config files. (line 37)\n* basic glyph lookup: Basic glyph lookup. (line 6)\n* Berry, Karl: History. (line 12)\n* BIBINPUTS: Supported file formats.\n(line 30)\n* BIBINPUTS <1>: Supported file formats.\n(line 121)\n* blank lines, in texmf.cnf: Config files. (line 35)\n* BLTXMLINPUTS: Supported file formats.\n(line 34)\n* brace expansion: Brace expansion. (line 6)\n* Breitenlohner, Peter: History. (line 78)\n* BSTINPUTS: Supported file formats.\n(line 38)\n* BSTINPUTS <1>: Supported file formats.\n(line 125)\n* bug address: Reporting bugs. (line 6)\n* bug checklist: Bug checklist. (line 6)\n* bug mailing list: Mailing lists. (line 6)\n* bugs, reporting: Reporting bugs. (line 6)\n* c-*.h: Calling sequence. (line 117)\n* c-auto.h: Programming overview.\n(line 35)\n* cache of fonts, local: Security. (line 22)\n* calling sequence: Calling sequence. (line 6)\n* casefolding examples: Casefolding examples.\n(line 6)\n* casefolding fallback rationale: Casefolding rationale.\n(line 6)\n* casefolding search: Casefolding search. (line 6)\n* ChangeLog entry: Bug checklist. (line 52)\n* checklist for bug reports: Bug checklist. (line 6)\n* checksum: Suppressing warnings.\n(line 16)\n* circle fonts: Fontmap. (line 19)\n* clientpath in kpse->formatinfo: Calling sequence. (line 47)\n* CLUAINPUTS: Supported file formats.\n(line 42)\n* CMAPFONTS: Supported file formats.\n(line 46)\n* cmr10, as fallback font: Fallback font. (line 15)\n* cmr10.vf: Searching overview. (line 31)\n* cnf.c: Config files. (line 112)\n* cnf.h: Programming with config files.\n(line 27)\n* comments, in fontmap files: Fontmap. (line 27)\n* comments, in texmf.cnf: Config files. (line 27)\n* comments, making: Introduction. (line 29)\n* common features in glyph lookup: Basic glyph lookup. (line 6)\n* common problems: Common problems. (line 6)\n* compilation value, source for path: Path sources. (line 23)\n* compiler bugs: TeX or Metafont failing.\n(line 6)\n* compiler bugs, finding: TeX or Metafont failing.\n(line 21)\n* conditions for use: Introduction. (line 32)\n* config files: Config files. (line 6)\n* config files, for Kpathsea-using programs: Calling sequence.\n(line 47)\n* config files, programming with: Programming with config files.\n(line 6)\n* config.h: Programming overview.\n(line 35)\n* config.log: Bug checklist. (line 24)\n* config.ps: Specially-recognized files.\n(line 16)\n* config.ps, search path for: Supported file formats.\n(line 57)\n* config.status: Bug checklist. (line 27)\n* configuration bugs: Bug checklist. (line 27)\n* configuration file, source for path: Path sources. (line 20)\n* configuration files as shell scripts.: Config files. (line 86)\n* configuration of mktex scripts: mktex configuration. (line 6)\n* configure options for mktex scripts: mktex configuration. (line 12)\n* context diff: Bug checklist. (line 52)\n* continuation character: Config files. (line 37)\n* core dumps, reporting: Bug checklist. (line 58)\n* crashes, reporting: Bug checklist. (line 58)\n* CWEBINPUTS: Supported file formats.\n(line 53)\n* database search: Searching overview. (line 17)\n* database, for filenames: Filename database. (line 6)\n* database, format of: Database format. (line 6)\n* debug.h: Debugging. (line 6)\n* debugger: Bug checklist. (line 58)\n* debugging: Debugging. (line 6)\n* debugging options, in Kpathsea-using program: Calling sequence.\n(line 39)\n* debugging output: Debugging. (line 27)\n* default expansion: Default expansion. (line 6)\n* defaulttexsizes: Fallback font. (line 6)\n* device, wrong: Unable to generate fonts.\n(line 29)\n* directories, making append-only: mktex configuration. (line 61)\n* directory permissions: Security. (line 51)\n* directory structure, for TeX files: TeX directory structure.\n(line 6)\n* disabling mktex scripts: mktex configuration. (line 6)\n* disk search: Searching overview. (line 22)\n* disk searching, avoiding: ls-R. (line 57)\n* disk usage, reducing: Logging. (line 6)\n* doc files: Supported file formats.\n(line 185)\n* DOS compatible names: mktex configuration. (line 68)\n* dosnames: mktex configuration. (line 67)\n* dot files: ls-R. (line 39)\n* doubled colons: Default expansion. (line 6)\n* dpiNNN directories: mktex configuration. (line 68)\n* DVILJMAKEPK: mktex script names. (line 32)\n* DVILJSIZES: Fallback font. (line 6)\n* dvipdfmx.cfg: Specially-recognized files.\n(line 19)\n* DVIPSFONTS: Supported file formats.\n(line 254)\n* DVIPSHEADERS: Supported file formats.\n(line 211)\n* DVIPSMAKEPK: mktex script names. (line 32)\n* DVIPSSIZES: Fallback font. (line 6)\n* dynamic creation of files: mktex scripts. (line 6)\n* EC fonts, and dynamic source creation: mktex scripts. (line 6)\n* elt-dirs.c: Subdirectory expansion.\n(line 41)\n* elt-dirs.c <1>: Subdirectory expansion.\n(line 48)\n* enabling mktex scripts: mktex configuration. (line 6)\n* ENCFONTS: Supported file formats.\n(line 61)\n* engine name: Path searching options.\n(line 53)\n* environment variable, source for path: Path sources. (line 12)\n* environment variables for TeX: Supported file formats.\n(line 6)\n* environment variables in paths: Variable expansion. (line 6)\n* environment variables, old: Unable to find files.\n(line 14)\n* epoch, seconds since: Logging. (line 15)\n* error message macros: Calling sequence. (line 22)\n* examples, of casefolding searches: Casefolding examples.\n(line 6)\n* excessive startup time: Slow path searching. (line 6)\n* expand.c: Brace expansion. (line 26)\n* expanding symlinks: Calling sequence. (line 31)\n* expansion, default: Default expansion. (line 6)\n* expansion, path element: Searching overview. (line 49)\n* expansion, search path: Path expansion. (line 6)\n* expansion, subdirectory: Subdirectory expansion.\n(line 6)\n* expansion, tilde: Tilde expansion. (line 6)\n* expansion, variable: Variable expansion. (line 6)\n* explicitly relative filenames: Searching overview. (line 58)\n* extensions, filename: File lookup. (line 24)\n* externally-built filename database: Filename database. (line 6)\n* extra colons: Default expansion. (line 6)\n* failed mktex... script invocation: mktex script names. (line 35)\n* fallback font: Fallback font. (line 6)\n* fallback resolutions: Fallback font. (line 6)\n* FAQ, Kpathsea: Common problems. (line 6)\n* Farwell, Matthew: Subdirectory expansion.\n(line 22)\n* file formats, supported: Supported file formats.\n(line 6)\n* file lookup: File lookup. (line 6)\n* file permissions: Security. (line 47)\n* file types, registering new: Programming overview.\n(line 41)\n* filename aliases: Filename aliases. (line 6)\n* filename database: Filename database. (line 6)\n* filenames, absolute or explicitly relative: Searching overview.\n(line 58)\n* files, unable to find: Unable to find files.\n(line 6)\n* filesystem search: Searching overview. (line 22)\n* filesystem, case-(in)sensitive: Casefolding rationale.\n(line 6)\n* Findutils, GNU package: Casefolding examples.\n(line 78)\n* floating directories: Searching overview. (line 22)\n* fmtutil: mktex script names. (line 10)\n* fmtutil.cnf: Specially-recognized files.\n(line 22)\n* fmtutils.cnf: mktex configuration. (line 24)\n* font alias files: Fontmap. (line 6)\n* font generation failures: Unable to generate fonts.\n(line 6)\n* font of last resort: Fallback font. (line 6)\n* font set, infinite: mktex scripts. (line 6)\n* FONTCIDMAPS: Supported file formats.\n(line 68)\n* FONTFEATURES: Supported file formats.\n(line 71)\n* fontmap files: Fontmap. (line 6)\n* fontmaps: mktex configuration. (line 86)\n* fontmaps <1>: mktex configuration. (line 87)\n* fontname: mktex configuration. (line 87)\n* fontnames, arbitrary length: Fontmap. (line 15)\n* FOOINPUTS: Supported file formats.\n(line 236)\n* FOOINPUTS <1>: Supported file formats.\n(line 239)\n* fopen, redefined: Debugging. (line 54)\n* format of external database: Database format. (line 6)\n* ftp.cs.stanford.edu: unixtex.ftp. (line 20)\n* ftp.tug.org: unixtex.ftp. (line 6)\n* fundamental purpose of Kpathsea: Introduction. (line 6)\n* gdb, recommended: Bug checklist. (line 58)\n* gf: Supported file formats.\n(line 75)\n* GFFONTS: Supported file formats.\n(line 75)\n* globally writable directories: Security. (line 30)\n* glyph lookup: Glyph lookup. (line 6)\n* glyph lookup bitmap tolerance: Basic glyph lookup. (line 15)\n* GLYPHFONTS: Supported file formats.\n(line 75)\n* GLYPHFONTS <1>: Supported file formats.\n(line 164)\n* glyphlist.txt: Specially-recognized files.\n(line 25)\n* GNU C compiler bugs: TeX or Metafont failing.\n(line 16)\n* GNU General Public License: Introduction. (line 32)\n* group-writable directories: Security. (line 40)\n* GSFTOPKDEBUG (128): Debugging. (line 88)\n* hash table buckets, printing: Debugging. (line 105)\n* hash table routines: Calling sequence. (line 110)\n* hashsummaryonly variable for debugging: Debugging. (line 105)\n* history of Kpathsea: History. (line 6)\n* Hoekwater, Taco: History. (line 78)\n* home directories in paths: Tilde expansion. (line 6)\n* HOME, as ~ expansion: Tilde expansion. (line 6)\n* identifiers, characters valid in: Config files. (line 47)\n* include fontmap directive: Fontmap. (line 36)\n* INDEXSTYLE: Supported file formats.\n(line 84)\n* input lines, reading: Calling sequence. (line 110)\n* interactive query: Path searching options.\n(line 151)\n* interface, not frozen: Introduction. (line 29)\n* introduction: Introduction. (line 6)\n* kdebug:: Debugging. (line 105)\n* kdefault.c: Default expansion. (line 48)\n* Knuth, Donald E.: History. (line 6)\n* Knuth, Donald E., archive of programs by: unixtex.ftp. (line 20)\n* Kpathsea config file, source for path: Path sources. (line 20)\n* kpathsea.h: Programming overview.\n(line 26)\n* kpathseacnfget: Programming with config files.\n(line 27)\n* KPATHSEADEBUG: Calling sequence. (line 28)\n* KPATHSEADEBUG <1>: Debugging. (line 18)\n* kpathseafindfile: File lookup. (line 38)\n* kpathseafindfile <1>: Calling sequence. (line 62)\n* kpathseafindglyph: Glyph lookup. (line 26)\n* kpathseafinish: Calling sequence. (line 106)\n* kpathseainitprog: Fallback font. (line 15)\n* kpathseainitprog <1>: Calling sequence. (line 53)\n* kpathseainnameok: Calling sequence. (line 101)\n* kpathseanew: Calling sequence. (line 9)\n* kpathseaopenfile: Calling sequence. (line 74)\n* kpathseaoutnameok: Calling sequence. (line 82)\n* kpathseasetprogramname: Calling sequence. (line 14)\n* kpathseavarvalue: Programming with config files.\n(line 10)\n* KPATHSEAWARNING: Config files. (line 18)\n* kpse->debug: Debugging. (line 6)\n* kpse->debug <1>: Debugging. (line 18)\n* kpse->debug variable: Calling sequence. (line 39)\n* kpse->formatinfo: Calling sequence. (line 47)\n* kpse->invocationname: Calling sequence. (line 22)\n* kpse->invocationshortname: Calling sequence. (line 22)\n* kpse->programname: Calling sequence. (line 22)\n* kpsewhich: Invoking kpsewhich. (line 6)\n* Kpsewhich, and debugging: Debugging. (line 31)\n* KPSEBITMAPTOLERANCE: Basic glyph lookup. (line 15)\n* KPSEDEBUGEXPAND (16): Debugging. (line 68)\n* KPSEDEBUGFOPEN (4): Debugging. (line 53)\n* KPSEDEBUGHASH (2): Debugging. (line 46)\n* KPSEDEBUGPATHS (8): Debugging. (line 60)\n* KPSEDEBUGSEARCH (32): Debugging. (line 74)\n* KPSEDEBUGSTAT (1): Debugging. (line 38)\n* KPSEDEBUGVARS (64): Debugging. (line 83)\n* KPSEDOT expansion: KPSEDOT expansion. (line 6)\n* kpseformatinfotype: Debugging. (line 61)\n* last-resort font: Fallback font. (line 6)\n* lcircle10: Fontmap. (line 19)\n* leading colons: Default expansion. (line 6)\n* leaf directories wrongly guessed: Unable to find files.\n(line 21)\n* leaf directory trick: Subdirectory expansion.\n(line 22)\n* license for using the library: Introduction. (line 32)\n* LIGFONTS: Supported file formats.\n(line 88)\n* lines, reading arbitrary-length: Calling sequence. (line 110)\n* Linux File System Standard: mktex configuration. (line 113)\n* local cache of fonts: Security. (line 22)\n* log file: Logging. (line 6)\n* logging successful searches: Logging. (line 6)\n* lost+found directory: Searching overview. (line 63)\n* lostchar: Suppressing warnings.\n(line 19)\n* ls-R: Supported file formats.\n(line 91)\n* ls-R database file: ls-R. (line 6)\n* ls-R, simplest build: ls-R. (line 22)\n* Mac filesystem, case-insensitive: Casefolding rationale.\n(line 6)\n* MacKenzie, David: History. (line 44)\n* MacKenzie, David <1>: Subdirectory expansion.\n(line 22)\n* magic characters: Searching overview. (line 13)\n* mailing lists: Mailing lists. (line 6)\n* MAKETEXDEBUG (512): Debugging. (line 91)\n* MAKETEXFINEDEBUG (1024): Debugging. (line 100)\n* memory allocation routines: Calling sequence. (line 110)\n* metafont driver files: mktex configuration. (line 93)\n* Metafont failures: TeX or Metafont failing.\n(line 6)\n* Metafont installation: Unable to generate fonts.\n(line 51)\n* Metafont making too-large fonts: Unable to generate fonts.\n(line 36)\n* Metafont using the wrong device: Unable to generate fonts.\n(line 29)\n* MFBASES: Supported file formats.\n(line 26)\n* MFINPUTS: Supported file formats.\n(line 105)\n* MFPOOL: Supported file formats.\n(line 109)\n* MFTINPUTS: Supported file formats.\n(line 113)\n* MISCFONTS: Supported file formats.\n(line 117)\n* mismatched checksum warnings: Suppressing warnings.\n(line 17)\n* missfont.log: mktex script names. (line 35)\n* MISSFONTLOG: mktex script names. (line 40)\n* missing character warnings: Suppressing warnings.\n(line 20)\n* mkocp: mktex script names. (line 18)\n* mkofm: mktex script names. (line 21)\n* mktex script configuration: mktex configuration. (line 6)\n* mktex script names: mktex script names. (line 6)\n* mktex scripts: mktex scripts. (line 6)\n* mktex.cnf: Specially-recognized files.\n(line 28)\n* mktex.cnf <1>: mktex configuration. (line 29)\n* mktex.opt: mktex configuration. (line 29)\n* mktex.opt <1>: mktex configuration. (line 39)\n* mktexdir: mktex configuration. (line 61)\n* mktexfmt: mktex script names. (line 10)\n* mktexmf: mktex script names. (line 15)\n* mktexpk: mktex script names. (line 24)\n* mktexpk can't guess mode: Unable to generate fonts.\n(line 12)\n* mktextex: mktex script names. (line 27)\n* mktextfm: mktex script names. (line 30)\n* MLBIBINPUTS: Supported file formats.\n(line 121)\n* MLBSTINPUTS: Supported file formats.\n(line 125)\n* mode directory, omitting: mktex configuration. (line 98)\n* Morgan, Tim: History. (line 12)\n* MPINPUTS: Supported file formats.\n(line 129)\n* MPMEMS: Supported file formats.\n(line 97)\n* MPPOOL: Supported file formats.\n(line 133)\n* MPSUPPORT: Supported file formats.\n(line 101)\n* MTFEATURES: mktex configuration. (line 39)\n* multiple TeX hierarchies: Brace expansion. (line 20)\n* must exist: Searching overview. (line 31)\n* names for mktex scripts: mktex script names. (line 6)\n* Neumann, Gustaf: History. (line 56)\n* NFS and ls-R: ls-R. (line 46)\n* nomfdrivers: mktex configuration. (line 92)\n* nomode: mktex configuration. (line 97)\n* none: Suppressing warnings.\n(line 23)\n* null pointers, dereferencing: Bug checklist. (line 58)\n* numeric debugging values: Debugging. (line 34)\n* obtaining TeX: unixtex.ftp. (line 6)\n* OCPINPUTS: Supported file formats.\n(line 137)\n* OFMFONTS: Supported file formats.\n(line 141)\n* online Metafont display, spurious: Unable to generate fonts.\n(line 36)\n* OPENTYPEFONTS: Supported file formats.\n(line 145)\n* optimization caveat: TeX or Metafont failing.\n(line 12)\n* options for debugging: Debugging. (line 6)\n* OTPINPUTS: Supported file formats.\n(line 151)\n* overview of path searching: Searching overview. (line 6)\n* overview of programming with Kpathsea: Programming overview.\n(line 6)\n* OVFFONTS: Supported file formats.\n(line 154)\n* OVPFONTS: Supported file formats.\n(line 157)\n* path expansion: Path expansion. (line 6)\n* path searching: Path searching. (line 6)\n* path searching options: Path searching options.\n(line 6)\n* path searching, overview: Searching overview. (line 6)\n* path searching, standalone: Invoking kpsewhich. (line 6)\n* path sources: Path sources. (line 6)\n* pathsearch.h: Programming overview.\n(line 26)\n* pc Pascal compiler: History. (line 12)\n* pdfglyphlist.txt: Specially-recognized files.\n(line 31)\n* pdftex.cfg: Specially-recognized files.\n(line 34)\n* PDFTEXCONFIG: Supported file formats.\n(line 161)\n* pdftexconfig.tex: Specially-recognized files.\n(line 34)\n* permission denied: Searching overview. (line 63)\n* permissions, directory: Security. (line 51)\n* permissions, file: Security. (line 47)\n* PKFONTS: Supported file formats.\n(line 164)\n* plain.base: Unable to generate fonts.\n(line 46)\n* privacy, semblance of: Logging. (line 32)\n* problems, common: Common problems. (line 6)\n* proginit.h: Calling sequence. (line 53)\n* program-varying paths: Supported file formats.\n(line 12)\n* programming overview: Programming overview.\n(line 6)\n* programming with config files: Programming with config files.\n(line 6)\n* programming with Kpathsea: Calling sequence. (line 6)\n* programs using the library: Introduction. (line 13)\n* proof mode: Unable to generate fonts.\n(line 36)\n* PSHEADERS: Supported file formats.\n(line 169)\n* pxp Pascal preprocessor: History. (line 12)\n* quoting variable values: Variable expansion. (line 17)\n* rationale for casefolding fallback: Casefolding rationale.\n(line 6)\n* re-entrant API: Programming overview.\n(line 16)\n* readable: Suppressing warnings.\n(line 26)\n* reading arbitrary-length lines: Calling sequence. (line 110)\n* recording successful searches: Logging. (line 6)\n* relative filenames: Searching overview. (line 58)\n* reporting bugs: Reporting bugs. (line 6)\n* resident.c: Calling sequence. (line 47)\n* resolution, setting: Path searching options.\n(line 49)\n* resolutions, last-resort: Fallback font. (line 6)\n* retrieving TeX: unixtex.ftp. (line 6)\n* right-hand side of variable assignments: Config files. (line 57)\n* RISINPUTS: Supported file formats.\n(line 173)\n* Rokicki, Tom: History. (line 12)\n* root user: Tilde expansion. (line 19)\n* runtime configuration files: Config files. (line 6)\n* runtime debugging: Debugging. (line 6)\n* Sauter fonts, and dynamic source creation: mktex scripts. (line 6)\n* scripts for file creation: mktex scripts. (line 6)\n* search path, defined: Searching overview. (line 6)\n* search, case-insensitive: Casefolding search. (line 6)\n* searching for files: File lookup. (line 6)\n* searching for glyphs: Glyph lookup. (line 6)\n* searching overview: Searching overview. (line 6)\n* searching the database: Searching overview. (line 17)\n* searching the disk: Searching overview. (line 22)\n* security considerations: Security. (line 6)\n* SELFAUTODIR: Calling sequence. (line 31)\n* SELFAUTOLOC: Calling sequence. (line 31)\n* SELFAUTOPARENT: Calling sequence. (line 31)\n* sending patches: Bug checklist. (line 52)\n* setgid scripts: Security. (line 40)\n* SFDFONTS: Supported file formats.\n(line 177)\n* shell scripts as configuration files: Config files. (line 86)\n* shell variables: Variable expansion. (line 17)\n* shellescape, example for code: Programming with config files.\n(line 10)\n* site overrides for mktex...: mktex configuration. (line 29)\n* skeleton TeX directory: TeX directory structure.\n(line 6)\n* slow startup time: Slow path searching. (line 6)\n* source files: Supported file formats.\n(line 188)\n* sources for search paths: Path sources. (line 6)\n* special: Suppressing warnings.\n(line 30)\n* stack trace: Bug checklist. (line 58)\n* standalone path searching: Invoking kpsewhich. (line 6)\n* standard error and debugging output: Debugging. (line 27)\n* standard options: Standard options. (line 6)\n* startup time, excessive: Slow path searching. (line 6)\n* string routines: Calling sequence. (line 110)\n* strip: mktex configuration. (line 107)\n* stripsupplier: mktex configuration. (line 101)\n* striptypeface: mktex configuration. (line 104)\n* stnlink: Subdirectory expansion.\n(line 26)\n* STNLINKTRICK: Subdirectory expansion.\n(line 38)\n* subdirectory searching: Subdirectory expansion.\n(line 6)\n* suffixes, filename: File lookup. (line 24)\n* suggestions, making: Introduction. (line 29)\n* Sun 2: History. (line 12)\n* supplier directory, omitting: mktex configuration. (line 102)\n* supplier directory, omitting <1>: mktex configuration. (line 108)\n* supported file formats: Supported file formats.\n(line 6)\n* suppressing warnings: Suppressing warnings.\n(line 6)\n* symbolic links not found: Unable to find files.\n(line 21)\n* symbolic links, and ls-R: ls-R. (line 44)\n* symlinks, resolving: Calling sequence. (line 31)\n* system C compiler bugs: TeX or Metafont failing.\n(line 16)\n* system-dependent casefolding behavior: Casefolding rationale.\n(line 6)\n* T1FONTS: Supported file formats.\n(line 211)\n* T1INPUTS: Supported file formats.\n(line 211)\n* T42FONTS: Supported file formats.\n(line 216)\n* tcfmgr.map: Specially-recognized files.\n(line 46)\n* TDS: TeX directory structure.\n(line 6)\n* TeX directory structure: TeX directory structure.\n(line 6)\n* TeX environment variables: Supported file formats.\n(line 6)\n* TeX failures: TeX or Metafont failing.\n(line 6)\n* TeX file lookup: File lookup. (line 6)\n* TeX glyph lookup: Glyph lookup. (line 6)\n* TeX support: TeX support. (line 6)\n* TeX Users Group: Introduction. (line 43)\n* tex-file.c: File lookup. (line 38)\n* tex-file.h: Programming overview.\n(line 26)\n* tex-glyph.c: Glyph lookup. (line 26)\n* tex-glyph.h: Programming overview.\n(line 26)\n* tex-k@tug.org: Mailing lists. (line 6)\n* tex-k@tug.org (bug address): Reporting bugs. (line 6)\n* tex.web: unixtex.ftp. (line 20)\n* TEXBIB: Supported file formats.\n(line 30)\n* TEXBIB <1>: Supported file formats.\n(line 121)\n* TEXCONFIG: Supported file formats.\n(line 57)\n* TEXDOCS: Supported file formats.\n(line 185)\n* TEXFONTMAPS: Supported file formats.\n(line 94)\n* TEXFONTS: Supported file formats.\n(line 75)\n* TEXFONTS <1>: Supported file formats.\n(line 164)\n* TEXFONTS <2>: Supported file formats.\n(line 199)\n* TEXFONTS <3>: Supported file formats.\n(line 219)\n* texfonts.map: Fontmap. (line 6)\n* TEXFORMATS: Supported file formats.\n(line 64)\n* TEXINDEXSTYLE: Supported file formats.\n(line 84)\n* TEXINPUTS: Supported file formats.\n(line 79)\n* TEXINPUTS <1>: Supported file formats.\n(line 180)\n* TEXMF: TeX directory structure.\n(line 6)\n* texmf.cnf: Specially-recognized files.\n(line 38)\n* texmf.cnf missing, warning about: Config files. (line 18)\n* texmf.cnf, and variable expansion: Variable expansion. (line 6)\n* texmf.cnf, definition for: Config files. (line 6)\n* texmf.cnf, source for path: Path sources. (line 20)\n* TEXMFCNF: Config files. (line 6)\n* TEXMFCNF <1>: Supported file formats.\n(line 49)\n* TEXMFDBS: ls-R. (line 11)\n* TEXMFDBS <1>: Supported file formats.\n(line 91)\n* TEXMFINI: Supported file formats.\n(line 26)\n* TEXMFINI <1>: Supported file formats.\n(line 64)\n* TEXMFINI <2>: Supported file formats.\n(line 97)\n* TEXMFLOG: Logging. (line 10)\n* TEXMFOUTPUT: mktex script names. (line 40)\n* TEXMFSCRIPTS: Supported file formats.\n(line 191)\n* texmfvar: mktex configuration. (line 122)\n* TEXMFVAR: mktex configuration. (line 123)\n* texmfcasefoldsearch: Casefolding search. (line 12)\n* TEXPICTS: Supported file formats.\n(line 79)\n* TEXPKS: Supported file formats.\n(line 164)\n* TEXPOOL: Supported file formats.\n(line 195)\n* TEXPSHEADERS: Supported file formats.\n(line 169)\n* TEXPSHEADERS <1>: Supported file formats.\n(line 211)\n* TEXSIZES: Fallback font. (line 6)\n* TEXSOURCES: Supported file formats.\n(line 188)\n* TEXHUSH: Searching overview. (line 63)\n* TEXHUSH <1>: Suppressing warnings.\n(line 6)\n* TFMFONTS: Supported file formats.\n(line 199)\n* tilde expansion: Tilde expansion. (line 6)\n* tilde.c: Tilde expansion. (line 25)\n* time system call: Logging. (line 15)\n* tolerance for glyph lookup: Basic glyph lookup. (line 15)\n* trailing / in home directory: Tilde expansion. (line 19)\n* trailing colons: Default expansion. (line 6)\n* translations, of path searching description: Path searching.\n(line 10)\n* TRFONTS: Supported file formats.\n(line 203)\n* trick for detecting leaf directories: Subdirectory expansion.\n(line 22)\n* trojan horse attack: Security. (line 10)\n* trystdextensionfirst: File lookup. (line 24)\n* TTFONTS: Supported file formats.\n(line 207)\n* tug.org: unixtex.ftp. (line 6)\n* typeface directory, omitting: mktex configuration. (line 105)\n* typeface directory, omitting <1>: mktex configuration. (line 108)\n* unable to find files: Unable to find files.\n(line 6)\n* unable to generate fonts: Unable to generate fonts.\n(line 6)\n* uname: Bug checklist. (line 20)\n* unixtex.ftp: unixtex.ftp. (line 6)\n* unknown special warnings: Suppressing warnings.\n(line 31)\n* unreadable file warnings: Suppressing warnings.\n(line 27)\n* unreadable files: Searching overview. (line 63)\n* unusable ls-R warning: ls-R. (line 51)\n* usage patterns, finding: Logging. (line 6)\n* USERPROFILE, as ~ expansion: Tilde expansion. (line 6)\n* USETEXMFVAR: mktex configuration. (line 128)\n* USEVARTEXFONTS: mktex configuration. (line 118)\n* varfonts: mktex configuration. (line 112)\n* variable expansion: Variable expansion. (line 6)\n* variable.c: Variable expansion. (line 32)\n* variable.h: Programming with config files.\n(line 10)\n* VARTEXFONTS: mktex configuration. (line 113)\n* VAX 11/750: History. (line 12)\n* version numbers, determining: Bug checklist. (line 15)\n* VF files, not found: Searching overview. (line 31)\n* VFFONTS: Supported file formats.\n(line 219)\n* Vojta, Paul: History. (line 30)\n* Walsh, Norman: History. (line 56)\n* warning about unusable ls-R: ls-R. (line 51)\n* warning, about missing texmf.cnf: Config files. (line 18)\n* warnings, file access: Searching overview. (line 63)\n* warnings, suppressing: Suppressing warnings.\n(line 6)\n* WEB2C: Supported file formats.\n(line 227)\n* Weber, Olaf: History. (line 73)\n* WEBINPUTS: Supported file formats.\n(line 223)\n* whitespace, in fontmap files: Fontmap. (line 31)\n* whitespace, not ignored on continuation lines: Config files.\n(line 37)\n* Windows and casefolding: Casefolding rationale.\n(line 21)\n* www.tug.org: unixtex.ftp. (line 6)\n* XDvi: Specially-recognized files.\n(line 41)\n* XDVIFONTS: Supported file formats.\n(line 254)\n* XDVIMAKEPK: mktex script names. (line 32)\n* XDVISIZES: Fallback font. (line 6)\n* zuhn, david: History. (line 50)\n\n", "subsections": [] } } } }