import (26feb20)

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

3 files changed, 90 insertions, 57 deletions

diff --git a/Master/texmf-dist/doc/latex/import/README b/Master/texmf-dist/doc/latex/import/README
new file mode 100644
index 00000000000..2a3886a5063
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/import/README
@@ -0,0 +1,15 @@
+import.sty    Version 6.0    22-Jan-2020  
+Donald Arseneau  (asnd@triumf.ca)  Vancouver, Canada.
+
+This software is in the public domain; free of any restrictions.
+All right are waived. No obligations are acknowleged.
+
+Two new LaTeX commands, "\import {<full-path>} {<file>}" and 
+"\subimport {<path-extension>} {<file>}" are defined to input 
+a file from another directory, allowing that file to find its 
+own inputs (using \input, \includegraphics etc.) in that directory.
+Alias command names are "\inputfrom" and "\subinputfrom".
+
+Also provided are \includefrom and \subincludefrom, which are
+based on the \include command, rather than \input.
+
diff --git a/Master/texmf-dist/doc/latex/import/import.pdf b/Master/texmf-dist/doc/latex/import/import.pdf
index f85e8c702f2..5f3f88f7a42 100644
--- a/Master/texmf-dist/doc/latex/import/import.pdf
+++ b/Master/texmf-dist/doc/latex/import/import.pdf
diff --git a/Master/texmf-dist/doc/latex/import/import.tex b/Master/texmf-dist/doc/latex/import/import.tex
index afa323d504a..36ff9a63d83 100644
--- a/Master/texmf-dist/doc/latex/import/import.tex
+++ b/Master/texmf-dist/doc/latex/import/import.tex
@@ -8,7 +8,7 @@
 \usepackage{textcomp}
 \usepackage{booktabs}
 \usepackage{microtype}
-\usepackage{hyperref}
+%\usepackage{hyperref}
 
 \newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}
 \newcommand*{\pkg}[1]{\textsf{#1}}
@@ -22,19 +22,13 @@
 \newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle}
 \newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}}
 \newcommand*{\oarg}[1]{\texttt{[}\meta{#1}\texttt{]}}
-\newcommand*{\BibTeX}{Bib\kern-0.08em\TeX\@\xspace}
-\newcommand*{\BigTeX}{Big\kern-0.08em\TeX\@\xspace}
+\renewcommand{\^}{\nolinebreak[2]}
+%\addtokomafont{title}{\rmfamily}
 
-\pdfstringdefDisableCommands{%
-  \def\BibTeX{BibTeX\xspace}%
-  \def\BigTeX{BigTeX\space}%
-}
-
-\addtokomafont{title}{\rmfamily}
-
-\title{The \pkg{import} package\thanks{This manual corresponds to \pkg{import}~v5.1, dated~23--Mar--2009.}}
-\author{Donald Arseneau  (\mail{asnd@triumf.ca})}
-\date{23--Mar--2009}
+\title{The import package}
+\author{Donald Arseneau  (\texttt{asnd@triumf.ca})}
+\date{Version 6.0, \quad 22--Jan--2020}
+\setlength{\parskip}{3pt plus 2pt}
 
 
 \begin{document}
@@ -43,60 +37,84 @@
 
 This software is in the public domain; free of any restrictions.
 
-Two new \LaTeX\ commands, ``\cmd{\import}\marg{full\_path}\marg{file}''\\ and
-``\cmd{\subimport}\-\marg{path\_extension}\marg{file}'' are defined to input a file 
-from another directory, allowing that file to find its own inputs
-(using ``\cmd{\input}'', ``\cmd{\includegraphics}'' etc.)\ in that directory.
+\medskip
 
-Alias command names are ``\cmd{\inputfrom}'' and ``\cmd{\subinputfrom}''.
+Two new \LaTeX\ commands:
+\begin{verse}
+ \cmd{\import} \marg{full-path} \marg{file}\hspace{8em} and\\[2pt]
+ \cmd{\subimport} \marg{path-extension} \marg{file}
+\end{verse}
+are defined to input a file from another directory, allowing that file
+to find its own inputs (using \cmd{\input}, \cmd{\includegraphics}
+etc.\@) in that directory.
 
-Also provided are ``\cmd{\includefrom}'' and ``\cmd{\subincludefrom}'', which are
-based on the ``\cmd{\include}'' command, rather than ``\cmd{\input}''.  There are
-also ``\texttt{*}'' variants described below.
+Alias command names are ``\cmd{\inputfrom}'' and ``\cmd{\subinputfrom}''.
+(If \cmd{\import} was defined previously, it will not be redefined.)
+Also provided are the similar commands ``\cmd{\includefrom}'' and
+``\cmd{\subincludefrom}'', which are based on the \cmd{\include} command,
+rather than \cmd{\input}. 
 
-For example, if a remote file ``\texttt{/usr5/friend/work/report.tex}'' has contents:
+For example, if a remote file \texttt{/user/friend/work/report.tex} has
+contents:
 %
 \begin{verbatim}
-My graph: \includegraphics{picture}
-\input{explanation}
+     My graph: \includegraphics{picture}
+     \input{explanation}
 \end{verbatim}
 %
-then you can safely input that file in your own document with the command
-``\verb+\import{/usr5/friend/work/}{report}+''; the explanation and picture will 
-be taken from the ``\texttt{/usr5/friend/work/}'' directory.
-
-The ``\cmd{\subimport}'' command takes a relative path instead of a full absolute
-file path, and it allows imported files to import files themselves, using
-their own directory as the root of another ``\meta{path\_extension}''. Do not use
-both ``\cmd{\import}'' and ``\cmd{\subimport}'' in the same file.
-
+then you can input that file to a document with 
+\verb+\import{/user/friend/+\^\verb+work/}+\^\verb+{report}+ 
+so that both the explanation and picture will be taken from the 
+\texttt{/user/friend/\^work/} directory.
+
+The \meta{full-path} argument for \cmd{\import} can be a full absolute path
+or a relative path starting from the main working directory for the document.
+The \cmd{\subimport} command facilitates nesting of file imports. It takes a
+relative \meta{path-extension} based on the location of the current imported file.
 For example, if a file is imported (using either command) from directory
-``\texttt{abc/}'' and that file contains the command ``\verb+\subimport{lmn/}{xyz}+'' then
-file ``\texttt{abc/lmn/xyz.tex}'' is input, and any ``\cmd{\input}'' commands in that file
-will read files from directory ``\texttt{abc/lmn/}''. 
-
-Note that the sub-import path is merely appended to the current import
-path.  Mistakes from this method must be rectified by ``\cmd{\import@path@fix}''.
-
-Depending on on how your \TeX\ system is configured, if a file with the 
-same name as the import file exists in the current directory or in the 
-\texttt{TEXINPUTS} path, that other file will be read in preference to one in the 
-import directory.  So here is the real behavior of the previous example:
-Given the sequence ``\verb+\import{abc/}{one}+'', ``\verb+\subimport{lmn/uvw/}{two}+'' (in
-file \texttt{one}), ``\verb+\input{three}+'' (in file \texttt{two}), \LaTeX\ first looks for \texttt{three.tex}
-in the \texttt{TEXINPUTS} search path; if not found, it tries ``\texttt{abc/lmn/uvw/three}'';
-if that doesn't exist, it tries ``\texttt{abc/three}''; if still not found, it tries
-the defined ``\cmd{\input@path}'', if there is one.
-
-To avoid searching the \texttt{TEXINPUTS} path when importing files, use the `star'
-versions of the commands: ``\cmd{\import*}'' and ``\cmd{\subimport*}''.
-
-A hook ``\cmd{\import@path@fix}'' is provided to reformat the import path
+\texttt{abc/} and that file contains the command \verb+\subimport{lmn/}{xyz}+ then
+file \texttt{abc/lmn/xyz.tex} is input, and any \cmd{\input} commands in that file
+will read files from directory \texttt{abc/lmn/}.\footnote{~Note that the sub-import
+  path is merely appended to the current import path.  Syntactical mistakes from this
+  method may be corrected by \cmd{\import@path@fix}.}
+
+Depending on on how your \TeX\ system is configured, if a file does not
+exist in the specified import directory, it will be looked for in previous
+import directories (when nesting \cmd{\subimport} files), then in any
+directory listed in the pre-existing \cmd{\input@path}, then in the current 
+working directory, and finally in the \texttt{TEXINPUTS} path. Therefore, for 
+\cmd{\import} and for other \cmd{\input} used within an imported file,
+a file found on the path of import(s) will be read in preference to others with
+the same name located elsewhere. So here is the real behavior of the previous
+example: Given the nested sequence:
+\begin{verse}
+\verb+\import{abc/}{one}+\quad (in main document);\\
+\verb+\subimport{lmn/uvw/}{two}+\quad (in file \texttt{abc/one.tex});\\
+\verb+\input{three}+\quad (in file \texttt{abc/lmn/uvw/two.tex});
+\end{verse}
+\LaTeX\ first looks for \texttt{abc/lmn/uvw/three} (or \texttt{abc/lmn/uvw/three.tex});\\
+if not found, it tries \texttt{abc/three} (or \texttt{abc/three.tex});\\
+if still not found, it looks in the \cmd{\input@path}, if there was one defined;\\
+if \cmd{\input@path} was not defined, or if the file was not found on it,
+\LaTeX\ then tries to open \texttt{three} in the main document directory;\\
+finally, if still not found, it searches the \texttt{TEXINPUTS} search path.
+
+Historically, `star' versions of the commands were defined (to avoid searching
+the \texttt{TEXINPUTS} path) but now the ``$*$'' is ignored.
+
+
+A command  ``\cmd{\import@path@fix}'' is provided to reformat the import path
 to fit the syntax of a particular operating system.  It \emph{could} be
-defined to convert unix-style path names to the local format, but 
-all it does now is remove ``\texttt{][}'' from VMS sub-import directories.
+defined to convert unix-style path names to the local format. The default
+definition ensures paths end with ``\texttt{/}'' on most systems, but
+removes ``\texttt{]\hspace{-2pt}[}'' from within sub-import directory paths
+on VMS systems.
+
+Note that the import package works by manipulating the internal `commands'
+\cmd{\input@path} and \cmd{\Ginput@path}, so may behave badly if you
+redefine them manually, or via another package, within the document.
 
-Presently, the paths are defined ``locally'' so input files must have 
+Presently, the paths are defined `locally' so input files must have 
 balanced grouping.
 
 \end{document}