summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Build/source/texk/kpathsea/kpathsea.texi96
-rw-r--r--Build/source/texk/kpathsea/kpsewhich.c8
2 files changed, 97 insertions, 7 deletions
diff --git a/Build/source/texk/kpathsea/kpathsea.texi b/Build/source/texk/kpathsea/kpathsea.texi
index faf9b0d1850..aa5fcbd8312 100644
--- a/Build/source/texk/kpathsea/kpathsea.texi
+++ b/Build/source/texk/kpathsea/kpathsea.texi
@@ -1058,14 +1058,17 @@ abbreviation is accepted.
@cindex path searching options
Kpsewhich looks up each non-option argument on the command line as a
-filename, and returns the first file found. There is no option to
-return all the files with a particular name (you can run the Unix
-@samp{find} utility for that, @pxref{Invoking find,,, findutils, GNU
-find utilities}).
+filename, and returns the first file found.
Various options alter the path searching behavior:
@table @samp
+@item --all
+@opindex --all
+@cindex all matches, finding
+Report all matches found, one per line. By default, if there is more
+than one match, just one will be reported (chosen effectively at random).
+
@item --dpi=@var{num}
@opindex --dpi=@var{num}
@opindex -D @var{num}
@@ -1201,6 +1204,91 @@ directory expansion of a path, instead of doing a one-shot lookup, see
Set the program name to @var{name}; default is @samp{kpsewhich}. This
can affect the search paths via the @samp{.@var{prognam}} feature in
configuration files (@pxref{Config files}).
+
+@item --subdir=@var{string}
+@opindex --subdir=@var{string}
+Report only those matches whose directory part @emph{ends} with
+@var{string} (compared literally, except case is ignored on a
+case-insensitive operating system). For example, suppose there are
+two matches for a given name:
+
+@example
+kpsewhich foo.sty
+@result{} /some/where/foo.sty
+/another/place/foo.sty
+@end example
+
+@noindent
+Then we can narrow the result to what we are interested in with
+@option{--subdir}:
+
+@example
+kpsewhich --subdir=where foo.sty
+@result{} /some/where/foo.sty
+
+kpsewhich --subdir=place foo.sty
+@result{} /another/place/foo.sty
+@end example
+
+@noindent
+The string to match must be at the end of the directory part of the
+match, and it is taken literally, with no pattern matching:
+
+@example
+kpsewhich --subdir=another foo.sty
+@result{}
+@end example
+
+@noindent
+The string to match may cross directory components:
+
+@example
+kpsewhich --subdir=some/where foo.sty
+@result{} /some/where/foo.sty
+@end example
+
+@noindent
+@option{--subdir} implies @option{--all}; if there is more than one
+match, they will all be reported (in our example, both @samp{where}
+and @samp{place} end in @samp{e}):
+
+@example
+kpsewhich --subdir=e
+@result{} /some/where/foo.sty
+/another/place/foo.sty
+@end example
+
+@noindent
+Because of the above rules, the presence of a leading @samp{/} is
+important, since it ``anchors'' the match to a full component name:
+
+@example
+kpsewhich --subdir=/lace foo.sty
+@result{}
+@end example
+
+@noindent
+However, a trailing @samp{/} is immaterial (and ignored), since the
+match always takes place at the end of the directory part:
+
+@example
+kpsewhich --subdir=lace/ foo.sty
+@result{} /another/place/foo.sty
+@end example
+
+@noindent
+The purpose of these rules is to make it convenient to find results
+only within a particular area of the tree. For instance, a given
+script named @file{foo.lua} might exist within both
+@file{texmf-dist/scripts/pkg1/} and @file{texmf-dist/scripts/pkg2/}.
+By specifying, say, @samp{--subdir=/pkg1}, you can be sure of getting
+the one you are interested in.
+
+We only match at the end because a site might happen to install @TeX{}
+in @file{/some/coincidental/pkg1/path/}, and we wouldn't want
+@file{texmf-dist/scripts/pkg2/} to match that when searching for
+@samp{/pkg1}.
+
@end table
diff --git a/Build/source/texk/kpathsea/kpsewhich.c b/Build/source/texk/kpathsea/kpsewhich.c
index 6dc17c2f510..0ff63ab020a 100644
--- a/Build/source/texk/kpathsea/kpsewhich.c
+++ b/Build/source/texk/kpathsea/kpsewhich.c
@@ -290,9 +290,10 @@ lookup P1C(string, name)
/* Reading the options. */
-#define USAGE "\
- Standalone path lookup and expansion for Kpathsea.\n\
+#define USAGE "\n\
+Standalone path lookup and expansion for Kpathsea.\n\
\n\
+-all output all matches (one per line), not just the first.\n\
-debug=NUM set debugging flags.\n\
-D, -dpi=NUM use a base resolution of NUM; default 600.\n\
-engine=STRING set engine name to STRING.\n\
@@ -304,10 +305,11 @@ lookup P1C(string, name)
-interactive ask for additional filenames to look up.\n\
[-no]-mktex=FMT disable/enable mktexFMT generation (FMT=pk/mf/tex/tfm).\n\
-mode=STRING set device name for $MAKETEX_MODE to STRING; no default.\n\
--must-exist search the disk as well as ls-R if necessary\n\
+-must-exist search the disk as well as ls-R if necessary.\n\
-path=STRING search in the path STRING.\n\
-progname=STRING set program name to STRING.\n\
-show-path=NAME output search path for file type NAME (see list below).\n\
+-subdir=STRING only output matches whose directory part ends with STRING.\n\
-var-value=STRING output the value of variable $STRING.\n\
-version print version number and exit.\n \
"