summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/kpathsea
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-03-26 14:41:17 +0000
committerKarl Berry <karl@freefriends.org>2019-03-26 14:41:17 +0000
commit6fd5badc41b8e1fa1c009c1331554c189c8a4884 (patch)
tree3525ed46b2a7905af065e76c22fb0fd9376d10cb /Master/texmf-dist/doc/kpathsea
parent150c17fa248c060cbe214414cbd8a3a879b31fed (diff)
txi+man updates, remake all
git-svn-id: svn://tug.org/texlive/trunk@50602 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/kpathsea')
-rw-r--r--Master/texmf-dist/doc/kpathsea/kpathsea.html61
-rw-r--r--Master/texmf-dist/doc/kpathsea/kpathsea.pdfbin390501 -> 301846 bytes
2 files changed, 42 insertions, 19 deletions
diff --git a/Master/texmf-dist/doc/kpathsea/kpathsea.html b/Master/texmf-dist/doc/kpathsea/kpathsea.html
index 64fca6da621..cac5c2a91f2 100644
--- a/Master/texmf-dist/doc/kpathsea/kpathsea.html
+++ b/Master/texmf-dist/doc/kpathsea/kpathsea.html
@@ -166,7 +166,7 @@ Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a
<p>This manual documents the Kpathsea library for path searching. It
corresponds to version 6.3.1, released in
-February 2019.
+March 2019.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Introduction" accesskey="1">Introduction</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Overview and history.
@@ -209,7 +209,7 @@ Next: <a href="#unixtex_002eftp" accesskey="n" rel="next">unixtex.ftp</a>, Previ
<span id="index-fundamental-purpose-of-Kpathsea"></span>
<p>This manual corresponds to version 6.3.1 of the Kpathsea
-library, released in February 2019.
+library, released in March 2019.
</p>
<p>The library&rsquo;s fundamental purpose is to return a filename from a list of
directories specified by the user, similar to what shells do when
@@ -1352,6 +1352,7 @@ searches the disk in the big system directory, the casefolding is not
done, and a search for &lsquo;<samp>stix-regular.otf</samp>&rsquo; will fail (on
case-sensitive systems), as it always has.
</p>
+<span id="index-_0021_0021-and-casefolding"></span>
<p>The caveat about not searching the disk amounts to saying that
casefolding does not happen in the trees specified with &lsquo;<samp>!!</samp>&rsquo;
(see <a href="#ls_002dR">ls-R</a>), that is, where only database (<samp>ls-R</samp>) searching
@@ -1447,14 +1448,19 @@ Next: <a href="#Filename-aliases" accesskey="n" rel="next">Filename aliases</a>,
<span id="ls_002dR-1"></span><h4 class="subsection">5.5.1 <samp>ls-R</samp></h4>
<span id="index-ls_002dR-database-file"></span>
-<span id="index-TEXMFDBS"></span>
<p>As mentioned above, you must name the main filename database
<samp>ls-R</samp>. You can put one at the root of each TeX installation
-hierarchy you wish to search (<code>$TEXMF</code> by default); most sites have
-only one hierarchy. Kpathsea looks for <samp>ls-R</samp> files along the
-<code>TEXMFDBS</code> path, so that should presumably match the list of
-hierarchies.
+hierarchy you wish to search (<code>$TEXMF</code> by default, which expands
+to a braced list of several hierarchies in TeX Live).
+</p>
+<span id="index-TEXMFDBS"></span>
+<span id="index-_0021_0021-in-TEXMFDBS"></span>
+<p>Kpathsea looks for <samp>ls-R</samp> files along the <code>TEXMFDBS</code>
+path. It is best for this to contain all and only those hierarchies
+from <code>$TEXMF</code> which are specified with <code>!!</code>&mdash;and also to
+specify them with <code>!!</code> in <code>TEXMFDBS</code>. (See the end of this
+section for more on <code>!!</code>.)
</p>
<p>The recommended way to create and maintain &lsquo;<samp>ls-R</samp>&rsquo; is to run the
<code>mktexlsr</code> script, which is installed in &lsquo;<samp>$(bindir)</samp>&rsquo;
@@ -1478,10 +1484,12 @@ Also presuming your <code>ls</code> hasn&rsquo;t been aliased in a system file
generating <samp>ls-R</samp>. For the precise definition of the file format,
see <a href="#Database-format">Database format</a>.
</p>
-<p>Regardless of whether you use the supplied script or your own, you will
-almost certainly want to invoke it via <code>cron</code>, so when you make
-changes in the installed files (say if you install a new LaTeX
-package), <samp>ls-R</samp> will be automatically updated.
+<p>Regardless of whether you use the supplied script or your own, you
+will almost certainly want to invoke it via <code>cron</code>, so when you
+make changes in the installed files (say if you install a new LaTeX
+package), <samp>ls-R</samp> will be automatically updated. However, for
+those using TeX Live or system distributions, the package managers
+should run <code>mktexlsr</code> as needed.
</p>
<span id="index-_002dA-option-to-ls"></span>
<span id="index-dot-files"></span>
@@ -1515,16 +1523,29 @@ ignores everything under such directories.
</p>
<span id="index-_0021_0021-in-path-specifications"></span>
<span id="index-disk-searching_002c-avoiding"></span>
-<p>Because the database may be out-of-date for a particular run, if a file
-is not found in the database, by default Kpathsea goes ahead and
-searches the disk. If a particular path element begins with &lsquo;<samp>!!</samp>&rsquo;,
-however, <em>only</em> the database will be searched for that element,
-never the disk. If the database does not exist, nothing will be
-searched. Because this can surprise users (&ldquo;I see the font
-<samp>foo.tfm</samp> when I do an <code>ls</code>; why can&rsquo;t Dvips find it?&rdquo;), it
-is not in any of the default search paths.
+<p>If a particular path element begins with &lsquo;<samp>!!</samp>&rsquo;, <em>only</em> the
+database will be searched for that element, never the disk; and if the
+database does not exist, nothing at all will be searched. In TeX
+Live, most of the trees are specified with &lsquo;<samp>!!</samp>&rsquo;.
+</p>
+<p>For path elements that do not begin with &lsquo;<samp>!!</samp>&rsquo;, if the database
+exists, it will be used, and the disk will not be searched. However,
+in this case, if the database does not exist, the disk will be
+searched. In TeX Live, the most notable case of this is the
+<code>TEXMFHOME</code> tree, to allow users to add and remove files from
+their own tree without having to worry about <code>ls-R</code>.
+</p>
+<p>(Aside: there are uncommon cases where a &lsquo;<samp>!!</samp>&rsquo; tree will be
+searched on disk even if the <code>ls-R</code> file exists; they are too
+obscure to try to explain here. See <samp>pathsearch.c</samp> in the source
+if you need to know.)
+</p>
+<p>To sum up: do not create an <code>ls-R</code> file unless you also take care
+to keep it up to date. Otherwise newly-installed files will not be
+found.
</p>
+
<hr>
<span id="Filename-aliases"></span><div class="header">
<p>
@@ -4419,7 +4440,9 @@ Previous: <a href="#Reporting-bugs" accesskey="p" rel="prev">Reporting bugs</a>,
<tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Index_cp_symbol-1">!</th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#index-_0021_0021-and-casefolding"><code>!! <span class="roman">and casefolding</span></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Casefolding-examples">Casefolding examples</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_0021_0021-in-path-specifications"><code>!! <span class="roman">in path specifications</span></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ls_002dR">ls-R</a></td></tr>
+<tr><td></td><td valign="top"><a href="#index-_0021_0021-in-TEXMFDBS"><code>!! <span class="roman">in <code>TEXMFDBS</code></span></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ls_002dR">ls-R</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th id="Index_cp_symbol-2">$</th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_0024-expansion"><code>$ <span class="roman">expansion</span></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Variable-expansion">Variable expansion</a></td></tr>
diff --git a/Master/texmf-dist/doc/kpathsea/kpathsea.pdf b/Master/texmf-dist/doc/kpathsea/kpathsea.pdf
index 7e52b1d972b..cd2acf69f1b 100644
--- a/Master/texmf-dist/doc/kpathsea/kpathsea.pdf
+++ b/Master/texmf-dist/doc/kpathsea/kpathsea.pdf
Binary files differ