document special filenames for kpsewhich

git-svn-id: svn://tug.org/texlive/trunk@8317 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 172 insertions, 56 deletions

diff --git a/Build/source/texk/kpathsea/ChangeLog b/Build/source/texk/kpathsea/ChangeLog
index b9d755e310b..b7f3f572ea5 100644
--- a/Build/source/texk/kpathsea/ChangeLog
+++ b/Build/source/texk/kpathsea/ChangeLog
@@ -1,3 +1,8 @@
+2008-05-24  Karl Berry  <karl@tug.org>
+
+	* kpathsea.texi (Specially-recognized files): new node to
+	document the special filenames kpsewhich now knows about.
+
 2008-05-23  Karl Berry  <karl@tug.org>
 
 	* tex-file.c (init_path): do not free the translated env_value,
diff --git a/Build/source/texk/kpathsea/kpathsea.info b/Build/source/texk/kpathsea/kpathsea.info
index e1184e7ebe1..440b22ebf87 100644
--- a/Build/source/texk/kpathsea/kpathsea.info
+++ b/Build/source/texk/kpathsea/kpathsea.info
@@ -2636,11 +2636,12 @@ accepted.
 * Menu:
 
 * Path searching options::      Changing the mode, resolution, etc.
+* Specially-recognized files::  Default formats for texmf.cnf, etc.
 * Auxiliary tasks::             Path and variable expansion.
 * Standard options::            --help and --version.
 
 
-File: kpathsea.info,  Node: Path searching options,  Next: Auxiliary tasks,  Up: Invoking kpsewhich
+File: kpathsea.info,  Node: Path searching options,  Next: Specially-recognized files,  Up: Invoking kpsewhich
 
 3.5.1 Path searching options
 ----------------------------
@@ -2676,12 +2677,6 @@ filename, and returns the first file found.
      configuration files you can use `--format="dvips config"'.  (The
      quotes are for the sake of the shell.)
 
-     When the filename being searched for is `config.ps', the format is
-     automatically switched to `dvips config'.  Similarly, when the
-     filename is `pdftex.cfg', the format is switched to `pdftex
-     config' (although `pdftex.cfg' is not used any more; look for
-     `pdftexconfig.tex' instead.)
-
      Here's the current list of recognized names and the associated
      suffixes.  *Note Supported file formats::, for more information on
      each of these.
@@ -2838,9 +2833,57 @@ filename, and returns the first file found.
 
 
 
-File: kpathsea.info,  Node: Auxiliary tasks,  Next: Standard options,  Prev: Path searching options,  Up: Invoking kpsewhich
+File: kpathsea.info,  Node: Specially-recognized files,  Next: Auxiliary tasks,  Prev: Path searching options,  Up: Invoking kpsewhich
+
+3.5.2 Specially-recognized files for `kpsewhich'
+------------------------------------------------
+
+`kpsewhich' recognizes a few special filenames on the command line and
+defaults to using the `known' file formats for them, merely to save the
+time and trouble of specifying the format.  This is only a feature of
+`kpsewhich'; when using the Kpathsea library itself, none of these
+special filenames are recognized, and it's still up to the caller to
+specify the desired format.
+
+   Here is the list of special filenames to `kpsewhich', along with
+their corresponding format:
+
+`config.ps'
+     `dvips config'
+
+`dvipdfmx.cfg'
+     `other text files'
+
+`fmtutil.cnf'
+     `web2c files'
+
+`glyphlist.txt'
+     `map'
+
+`mktex.cnf'
+     `web2c files'
+
+`pdfglyphlist.txt'
+     `map'
+
+`pdftex.cfg'
+     `pdftex config' (although `pdftex.cfg' is not used any more; look
+     for the file `pdftexconfig.tex' instead.)
+
+`texmf.cnf'
+     `cnf'
+
+
+   A user-specified format will override the above defaults.
+
+   Another useful configuration file in this regard is `tcfmgr.map',
+found in `texmf/texconfig/tcfmgr.map', which records various
+information about the above configuration files (among others).
+
+
+File: kpathsea.info,  Node: Auxiliary tasks,  Next: Standard options,  Prev: Specially-recognized files,  Up: Invoking kpsewhich
 
-3.5.2 Auxiliary tasks
+3.5.3 Auxiliary tasks
 ---------------------
 
 Kpsewhich provides some additional features not strictly related to path
@@ -2887,7 +2930,7 @@ lookup:
 
 File: kpathsea.info,  Node: Standard options,  Prev: Auxiliary tasks,  Up: Invoking kpsewhich
 
-3.5.3 Standard options
+3.5.4 Standard options
 ----------------------
 
 Kpsewhich accepts the standard GNU options:
@@ -3167,6 +3210,7 @@ This section describes how Kpathsea searches for most files (bitmap font
 searches are the exception, as described in the next section).
 
    Here is the search strategy for a file NAME:
+
   1. If the file format defines default suffixes, and the suffix of
      NAME name is not already a known suffix for that format, try the
      name with each default appended, and use alternative names found in
@@ -3622,20 +3666,20 @@ Index
                                                               (line  27)
 * --help:                                Standard options.    (line   8)
 * --interactive:                         Path searching options.
-                                                              (line 101)
+                                                              (line  95)
 * --mode=STRING:                         Path searching options.
-                                                              (line 112)
+                                                              (line 106)
 * --must-exist:                          Path searching options.
-                                                              (line 117)
+                                                              (line 111)
 * --path=STRING:                         Path searching options.
-                                                              (line 122)
+                                                              (line 116)
 * --progname=NAME:                       Path searching options.
-                                                              (line 131)
+                                                              (line 125)
 * --show-path=NAME:                      Auxiliary tasks.     (line  41)
 * --srcdir, for building multiple architectures: configure scenarios.
                                                               (line  18)
 * --subdir=STRING:                       Path searching options.
-                                                              (line 136)
+                                                              (line 130)
 * --var-value=VARIABLE:                  Auxiliary tasks.     (line  12)
 * --version:                             Standard options.    (line  10)
 * --with options:                        configure options.   (line  16)
@@ -3656,9 +3700,9 @@ Index
 * -g, compiling without:                 configure scenarios. (line  32)
 * -L option to ls:                       ls-R.                (line  38)
 * -mktex=FILETYPE:                       Path searching options.
-                                                              (line 106)
+                                                              (line 100)
 * -no-mktex=FILETYPE:                    Path searching options.
-                                                              (line 106)
+                                                              (line 100)
 * -O, compiling with:                    configure scenarios. (line  32)
 * -static:                               ShellWidgetClass.    (line  43)
 * . directories, ignored:                ls-R.                (line  33)
@@ -3877,8 +3921,8 @@ Index
 * config.h:                              Programming overview.
                                                               (line  25)
 * config.log:                            Bug checklist.       (line  28)
-* config.ps:                             Path searching options.
-                                                              (line  37)
+* config.ps:                             Specially-recognized files.
+                                                              (line  16)
 * config.ps, search path for:            Supported file formats.
                                                               (line  47)
 * config.status:                         Bug checklist.       (line  31)
@@ -3967,6 +4011,8 @@ Index
                                                               (line  12)
 * DVILJMAKEPK:                           mktex script names.  (line  32)
 * DVILJSIZES:                            Fallback font.       (line   6)
+* dvipdfmx.cfg:                          Specially-recognized files.
+                                                              (line  19)
 * DVIPSFONTS:                            Supported file formats.
                                                               (line 227)
 * DVIPSHEADERS:                          Supported file formats.
@@ -4005,7 +4051,7 @@ Index
 * expansion, tilde:                      Tilde expansion.     (line   6)
 * expansion, variable:                   Variable expansion.  (line   6)
 * explicitly relative filenames:         Searching overview.  (line  52)
-* extensions, filename:                  File lookup.         (line  23)
+* extensions, filename:                  File lookup.         (line  24)
 * externally-built filename database:    Filename database.   (line   6)
 * extra colons:                          Default expansion.   (line   6)
 * extraclean Make target:                Cleaning up.         (line  23)
@@ -4036,6 +4082,8 @@ Index
 * filesystem search:                     Searching overview.  (line  22)
 * floating directories:                  Searching overview.  (line  22)
 * fmtutil:                               mktex script names.  (line  10)
+* fmtutil.cnf:                           Specially-recognized files.
+                                                              (line  22)
 * fmtutils.cnf:                          mktex configuration. (line  24)
 * font alias files:                      Fontmap.             (line   6)
 * font generation failures:              Unable to generate fonts.
@@ -4075,6 +4123,8 @@ Index
 * glyph lookup bitmap tolerance:         Basic glyph lookup.  (line  15)
 * GLYPHFONTS:                            Supported file formats.
                                                               (line  58)
+* glyphlist.txt:                         Specially-recognized files.
+                                                              (line  25)
 * GNU C compiler bugs:                   TeX or Metafont failing.
                                                               (line  19)
 * GNU General Public License:            Introduction.        (line  31)
@@ -4114,7 +4164,7 @@ Index
 * installation, simple:                  Simple installation. (line   6)
 * installing files:                      Installing files.    (line   6)
 * interactive query:                     Path searching options.
-                                                              (line 101)
+                                                              (line  95)
 * interface, not frozen:                 Introduction.        (line  27)
 * introduction:                          Introduction.        (line   6)
 * kdebug::                               Debugging.           (line 105)
@@ -4153,7 +4203,7 @@ Index
 * kpse_fallback_font:                    Fallback font.       (line  15)
 * kpse_find_*:                           Calling sequence.    (line  60)
 * kpse_find_file <1>:                    Calling sequence.    (line  60)
-* kpse_find_file:                        File lookup.         (line  36)
+* kpse_find_file:                        File lookup.         (line  37)
 * kpse_find_glyph_format:                Glyph lookup.        (line  26)
 * kpse_format_info:                      Calling sequence.    (line  45)
 * kpse_format_info_type:                 Debugging.           (line  61)
@@ -4261,6 +4311,8 @@ Index
 * mktex script configuration:            mktex configuration. (line   6)
 * mktex script names:                    mktex script names.  (line   6)
 * mktex scripts:                         mktex scripts.       (line   6)
+* mktex.cnf <1>:                         Specially-recognized files.
+                                                              (line  28)
 * mktex.cnf:                             mktex configuration. (line  29)
 * mktex.opt:                             mktex configuration. (line  29)
 * mktexdir:                              mktex configuration. (line  62)
@@ -4364,12 +4416,14 @@ Index
                                                               (line  13)
 * PDF generation:                        Kpathsea application distributions.
                                                               (line  16)
-* pdftex.cfg:                            Path searching options.
-                                                              (line  37)
+* pdfglyphlist.txt:                      Specially-recognized files.
+                                                              (line  31)
+* pdftex.cfg:                            Specially-recognized files.
+                                                              (line  34)
 * PDFTEXCONFIG:                          Supported file formats.
                                                               (line 136)
-* pdftexconfig.tex:                      Path searching options.
-                                                              (line  37)
+* pdftexconfig.tex:                      Specially-recognized files.
+                                                              (line  34)
 * permission denied:                     Searching overview.  (line  56)
 * permissions, directory:                Security.            (line  51)
 * permissions, file:                     Security.            (line  47)
@@ -4483,7 +4537,7 @@ Index
 * striptypeface:                         mktex configuration. (line 105)
 * subdirectory searching:                Subdirectory expansion.
                                                               (line   6)
-* suffixes, filename:                    File lookup.         (line  23)
+* suffixes, filename:                    File lookup.         (line  24)
 * suggestions, making:                   Introduction.        (line  27)
 * Sun 2:                                 History.             (line  12)
 * Sun OpenWin patches:                   ShellWidgetClass.    (line  29)
@@ -4508,6 +4562,8 @@ Index
                                                               (line 184)
 * T42FONTS:                              Supported file formats.
                                                               (line 189)
+* tcfmgr.map:                            Specially-recognized files.
+                                                              (line  44)
 * TDS:                                   TeX directory structure.
                                                               (line   6)
 * testing, post-installation:            Installation testing.
@@ -4529,7 +4585,7 @@ Index
 * TeX support:                           TeX support.         (line   6)
 * TeX Users Group:                       Introduction.        (line  39)
 * tex-archive@math.utah.edu:             Mailing lists.       (line  25)
-* tex-file.c:                            File lookup.         (line  36)
+* tex-file.c:                            File lookup.         (line  37)
 * tex-file.h:                            Programming overview.
                                                               (line  16)
 * tex-glyph.c:                           Glyph lookup.        (line  26)
@@ -4559,6 +4615,8 @@ Index
                                                               (line  62)
 * TEXMF:                                 TeX directory structure.
                                                               (line   6)
+* texmf.cnf:                             Specially-recognized files.
+                                                              (line  38)
 * texmf.cnf missing, warning about:      Config files.        (line  18)
 * texmf.cnf, and variable expansion:     Variable expansion.  (line   6)
 * texmf.cnf, creating:                   Running make.        (line   6)
@@ -4611,7 +4669,7 @@ Index
 * trick for detecting leaf directories:  Subdirectory expansion.
                                                               (line  22)
 * trojan horse attack:                   Security.            (line  10)
-* try_std_extension_first:               File lookup.         (line  23)
+* try_std_extension_first:               File lookup.         (line  24)
 * TTFONTS:                               Supported file formats.
                                                               (line 181)
 * tug.org:                               unixtex.ftp.         (line   6)
@@ -4762,22 +4820,23 @@ Node: ls-R103807
 Node: Filename aliases106701
 Node: Database format107879
 Node: Invoking kpsewhich108892
-Node: Path searching options109769
-Node: Auxiliary tasks116418
-Node: Standard options118239
-Node: TeX support118559
-Node: Supported file formats119850
-Node: File lookup126998
-Node: Glyph lookup128725
-Node: Basic glyph lookup129852
-Node: Fontmap130731
-Node: Fallback font133348
-Node: Suppressing warnings134313
-Node: Programming135418
-Node: Programming overview135931
-Node: Calling sequence138207
-Node: Program-specific files143236
-Node: Programming with config files144274
-Node: Index145574
+Node: Path searching options109837
+Node: Specially-recognized files116190
+Node: Auxiliary tasks117514
+Node: Standard options119339
+Node: TeX support119659
+Node: Supported file formats120950
+Node: File lookup128098
+Node: Glyph lookup129826
+Node: Basic glyph lookup130953
+Node: Fontmap131832
+Node: Fallback font134449
+Node: Suppressing warnings135414
+Node: Programming136519
+Node: Programming overview137032
+Node: Calling sequence139308
+Node: Program-specific files144337
+Node: Programming with config files145375
+Node: Index146675
 
 End Tag Table
diff --git a/Build/source/texk/kpathsea/kpathsea.texi b/Build/source/texk/kpathsea/kpathsea.texi
index 3c4b785f1ac..bb3a566005a 100644
--- a/Build/source/texk/kpathsea/kpathsea.texi
+++ b/Build/source/texk/kpathsea/kpathsea.texi
@@ -1057,6 +1057,7 @@ abbreviation is accepted.
 
 @menu
 * Path searching options::      Changing the mode, resolution, etc.
+* Specially-recognized files::  Default formats for texmf.cnf, etc.
 * Auxiliary tasks::             Path and variable expansion.
 * Standard options::            --help and --version.
 @end menu
@@ -1106,15 +1107,6 @@ with no associated suffix.  For example, for Dvips configuration files
 you can use @samp{--format="dvips config"}.  (The quotes are for the
 sake of the shell.)
 
-@flindex config.ps
-@flindex pdftex.cfg
-@flindex pdftexconfig.tex
-When the filename being searched for is @file{config.ps}, the format
-is automatically switched to @samp{dvips config}.  Similarly, when the
-filename is @file{pdftex.cfg}, the format is switched to @samp{pdftex
-config} (although @file{pdftex.cfg} is not used any more; look for
-@file{pdftexconfig.tex} instead.)
-
 Here's the current list of recognized names and the associated suffixes.
 @xref{Supported file formats}, for more information on each of these.
 @example
@@ -1302,6 +1294,65 @@ in @file{/some/coincidental/pkg1/path/}, and we wouldn't want
 @end table
 
 
+@node Specially-recognized files
+@subsection Specially-recognized files for @command{kpsewhich}
+
+@command{kpsewhich} recognizes a few special filenames on the command
+line and defaults to using the `known' file formats for them, merely
+to save the time and trouble of specifying the format.  This is only a
+feature of @command{kpsewhich}; when using the Kpathsea library
+itself, none of these special filenames are recognized, and it's still
+up to the caller to specify the desired format.
+
+Here is the list of special filenames to @command{kpsewhich}, along
+with their corresponding format:
+
+@table @file
+
+@flindex config.ps
+@item config.ps
+@code{dvips config}
+
+@flindex dvipdfmx.cfg
+@item dvipdfmx.cfg
+@samp{other text files}
+
+@flindex fmtutil.cnf
+@item fmtutil.cnf
+@samp{web2c files}
+
+@flindex glyphlist.txt
+@item glyphlist.txt
+@samp{map}
+
+@flindex mktex.cnf
+@item mktex.cnf
+@samp{web2c files}
+
+@flindex pdfglyphlist.txt
+@item pdfglyphlist.txt
+@samp{map}
+
+@flindex pdftex.cfg
+@flindex pdftexconfig.tex
+@item pdftex.cfg
+@samp{pdftex config} (although @file{pdftex.cfg} is not used any more;
+look for the file @file{pdftexconfig.tex} instead.)
+
+@flindex texmf.cnf
+@item texmf.cnf
+@samp{cnf}
+
+@end table
+
+A user-specified format will override the above defaults.
+
+@flindex tcfmgr.map
+Another useful configuration file in this regard is @file{tcfmgr.map},
+found in @file{texmf/texconfig/tcfmgr.map}, which records various
+information about the above configuration files (among others).
+
+
 @node Auxiliary tasks
 @subsection Auxiliary tasks
 
@@ -1839,6 +1890,7 @@ This section describes how Kpathsea searches for most files (bitmap font
 searches are the exception, as described in the next section).
 
 Here is the search strategy for a file @var{name}:
+
 @enumerate
 @item
 If the file format defines default suffixes, and the suffix of