[latexrefman-commits] [SCM] latexrefman updated: r758 - trunk
karl at gnu.org.ua
karl at gnu.org.ua
Wed Mar 11 23:52:27 CET 2020
Author: karl
Date: 2020-03-12 00:52:27 +0200 (Thu, 12 Mar 2020)
New Revision: 758
Modified:
trunk/ChangeLog
trunk/aspell.en.pws
trunk/latex2e.texi
Log:
more details on --output-directory; mention texosquery
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2020-03-11 19:37:54 UTC (rev 757)
+++ trunk/ChangeLog 2020-03-11 22:52:27 UTC (rev 758)
@@ -1,3 +1,10 @@
+2020-03-11 Karl Berry <karl at freefriends.org>
+
+ * latex2e.texi (output directory): new anchor, for the
+ the --output-directory option. More fully describe it,
+ and reference it where needed. Mentioned by Vincent.
+ (\write18): mention the texosquery package.
+
2020-03-02 Karl Berry <karl at freefriends.org>
* latex2e.texi (filecontents): update for the new filecontents
Modified: trunk/aspell.en.pws
===================================================================
--- trunk/aspell.en.pws 2020-03-11 19:37:54 UTC (rev 757)
+++ trunk/aspell.en.pws 2020-03-11 22:52:27 UTC (rev 758)
@@ -260,3 +260,4 @@
fallbacks
guillemet
guillemets
+texosquery
Modified: trunk/latex2e.texi
===================================================================
--- trunk/latex2e.texi 2020-03-11 19:37:54 UTC (rev 757)
+++ trunk/latex2e.texi 2020-03-11 22:52:27 UTC (rev 758)
@@ -5050,7 +5050,8 @@
\end@{filecontents*@}
@end example
-Create a file named @var{filename} in the current directory and write
+Create a file named @var{filename} in the current directory (or the
+output directory, if specified; @pxref{output directory}) and write
@var{text} to it. By default, an existing file is not overwritten.
The unstarred version of the environment
@@ -5073,8 +5074,8 @@
@item nosearch
@cindex @code{nosearch} option for @code{filecontents}
-Only check the current directory for an existing file, not the entire
-search path.
+Only check the current directory (and the output directory, if
+specified) for an existing file, not the entire search path.
@end table
@@ -16172,9 +16173,10 @@
you to later say something like @code{\includegraphics@{lion.png@}}
instead of having to give its path.
- at LaTeX{} always looks for graphic files first in the current directory.
-The declaration below tells the system to then look in the subdirectory
- at file{pix}, and then @file{../pix}.
+ at LaTeX{} always looks for graphic files first in the current directory
+(and the output directory, if specified; @pxref{output directory}).
+The declaration below tells the system to then look in the
+subdirectory @file{pix}, and then @file{../pix}.
@example
\usepackage@{graphicx@} % or graphics; put in preamble
@@ -19822,8 +19824,9 @@
The ability to write files raises security issues. If you compiled a
downloaded @LaTeX{} file and it overwrote your password file then you
would be justifiably troubled. @TeX{} systems by default only allow
-you to open files for writing that are in the current directory or in
-a subdirectory. This
+you to open files for writing that are in the current directory or
+output directory, if specified (@pxref{output directory}), or in a
+subdirectory of those. So, this code
@example
\newwrite\jhfile
@@ -19942,7 +19945,9 @@
@findex \write18
@cindex external commands
- at cindex commands, run from LaTeX
+ at cindex commands, run from @LaTeX{}
+ at cindex system commands, run from @LaTeX{}
+ at cindex shell access
@c Derived from: Joseph Wright: https://tex.stackexchange.com/a/20446/121234
Synopsis:
@@ -19981,7 +19986,7 @@
You sometimes need to do a multi-step process to get the information
that you want. This will insert into the input a list of all PDF files
-in the current directory.
+in the current directory (but see @file{texosquery} below):
@example
\immediate\write18@{ls *.pdf > tmp.dat@}
@@ -20002,6 +20007,7 @@
Live or Mac at TeX{} or @code{latex --enable-write18 @var{filename}} for
MiK at TeX{} (@pxref{Command line options}).
+ at cindex restricted shell access
In the place of full shell access, modern distributions by default use a
restricted version that allows some commands to work, such as those that
run Metafont to generate missing fonts, even if you do not use the
@@ -20012,10 +20018,15 @@
Some packages need to run external system commands. For instance
@file{sagetex} allows you to have the mathematics software system
- at i{Sage} do calculations or draw graphs and then incorporate that output
-in your document. For this you must compile with full @code{\write18}
-capability turned on.
+ at i{Sage} do calculations or draw graphs and then incorporate that
+output in your document. For this you must run @LaTeX{} with full
+ at code{\write18} capability turned on.
+ at PkgIndex{texosquery} If what you need is system information, such as
+the operating system name, locale information, or directory contents,
+take a look at the @file{texosquery} package, which provides a
+convenient and secure interface for this:
+ at url{https://ctan.org/pkg/texosquery}.
@node Command line
@chapter Command line
@@ -20125,6 +20136,8 @@
@noindent
eliminates most terminal output.
+ at cindex jobname
+ at cindex filename for current job
@findex --jobname @r{command-line option}
@item -jobname=@var{string}
Set the value of @TeX{}'s @code{jobname} to the string. The log file
@@ -20139,10 +20152,23 @@
@code{jobname} option overrides that process and directly specifies the
name. @xref{Command line input} for an example of its use.
+ at anchor{output directory}
+ at cindex output directory for all external files
@findex --output-directory @r{command-line option}
@item -output-directory=@var{directory}
Write files in the directory @var{directory}. It must already exist.
+This applies to all external files created by @TeX{} or @LaTeX{}, such
+as the @file{.log} file for the run, the @file{.aux}, @file{.toc},
+etc., files created by @LaTeX{}, as well as the main @file{.pdf} or
+ at file{.dvi} output file itself.
+When specified, the output directory @var{directory} is also
+automatically checked first for any file that it is input, so that the
+external files can be read back in, if desired. The true current
+directory (in which @LaTeX{}) was run remains unchanged, and is also
+checked for input files.
+
+ at cindex shell escape
@findex --shell-escape @r{command-line option}
@findex --no-shell-escape @r{command-line option}
@findex --enable-write18 @r{command-line option}
@@ -20162,15 +20188,16 @@
graphs and then incorporate that output in your document. For this
@TeX{} provides the @code{\write18} command.
-But with this functionality enabled, security issues could happen if you
-compiled a @LaTeX{} file from the Internet. By default @code{\write18}
-is disabled. (More precisely, by default @TeX{} Live, Mac at TeX{}, and
-MiK at TeX{} only allow the execution of a limited number of @TeX{}-related
-programs, which they distribute.)
+But with this functionality enabled, security issues could happen if
+you compiled a @LaTeX{} file from the Internet. By default,
+unrestricted @code{\write18} is not allowed. (The default for @TeX{}
+Live, Mac at TeX{}, and MiK at TeX{} is to allow the execution of a limited
+number of @TeX{}-related programs, which they distribute.)
-If you invoke @LaTeX{} with the option @code{no-shell-escape}, and in
-your document you call @code{\write18@{ls -l@}}, then you do not get an
-error but the log file says @samp{runsystem(ls -l)...disabled}.
+For example, if you invoke @LaTeX{} with the option
+ at code{no-shell-escape}, and in your document you call
+ at code{\write18@{ls -l@}}, then you do not get an error but the log
+file says @samp{runsystem(ls -l)...disabled}.
@findex --halt-on-error @r{command-line option}
@item -halt-on-error
More information about the latexrefman-commits
mailing list.