[latexrefman-commits] [SCM] latexrefman updated: r798 - trunk
karl at gnu.org.ua
karl at gnu.org.ua
Sun Apr 19 19:51:46 CEST 2020
Author: karl
Date: 2020-04-19 20:51:46 +0300 (Sun, 19 Apr 2020)
New Revision: 798
Modified:
trunk/ChangeLog
trunk/aspell.en.pws
trunk/latex2e.texi
Log:
\write node edits and indexing; new node split off: \write and security
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2020-04-17 08:26:39 UTC (rev 797)
+++ trunk/ChangeLog 2020-04-19 17:51:46 UTC (rev 798)
@@ -1,3 +1,8 @@
+2020-04-19 Karl Berry <karl at freefriends.org>
+
+ * latex2e.texi (\write): edits throughout; more index entries.
+ (\write and security): new node.
+
2020-04-17 Vincent Belaïche <vincentb1 at users.sourceforge.net>
* latex2e-fr.texi (picture): Refresh outdated node translation,
Modified: trunk/aspell.en.pws
===================================================================
--- trunk/aspell.en.pws 2020-04-17 08:26:39 UTC (rev 797)
+++ trunk/aspell.en.pws 2020-04-19 17:51:46 UTC (rev 798)
@@ -10,6 +10,7 @@
Botway
CTAN's
CropBox
+Dietze
EE
EF
EnvIndex
@@ -31,11 +32,13 @@
TrimBox
ae
afterskip
+amscd
arabic
aring
arrayrulewidth
arraystrech
ary
+auxout
baselinestretch
bb
bbllx
@@ -52,6 +55,7 @@
bowtie
bp
builtin
+cd
cdots
cmd
columnsep
@@ -88,6 +92,7 @@
evensidemargin
executivepaper
f's
+fallbacks
fbox
fboxrule
fd
@@ -104,6 +109,8 @@
footnotesep
footskip
greek
+guillemet
+guillemets
hacek
headheight
headsep
@@ -130,6 +137,7 @@
labelitemiv
labelsep
labelwidth
+latexsym
ldots
leadsto
leftmargin
@@ -149,6 +157,7 @@
lr
lrbox
lunate
+mainaux
makeidx
makelabel
marginparpush
@@ -190,6 +199,7 @@
paperwidth
parsep
partopsep
+pasteable
pict
pixelation
printindex
@@ -218,6 +228,7 @@
tecks
texi
texinfo
+texosquery
textcase
textheight
textstyle
@@ -252,12 +263,3 @@
xindy
xyz
zet
-Dietze
-pasteable
-amscd
-cd
-latexsym
-fallbacks
-guillemet
-guillemets
-texosquery
Modified: trunk/latex2e.texi
===================================================================
--- trunk/latex2e.texi 2020-04-17 08:26:39 UTC (rev 797)
+++ trunk/latex2e.texi 2020-04-19 17:51:46 UTC (rev 798)
@@ -19730,7 +19730,7 @@
Synopsis:
@example
-\write at var{number}@{@var{string}@}
+\write @var{number}@{@var{string}@}
@end example
Write @var{string} to the log file, to the terminal, or to a file
@@ -19741,130 +19741,178 @@
@file{@var{basefile}.jh}, writes @samp{Hello World!} and a newline to
it, and closes that file.
- at findex \jobname
@example
\newwrite\myfile
-\immediate\openout\myfile=\jobname.jh % \jobname is the root file basename
- ...
+\immediate\openout\myfile=\jobname.jh % \jobname is root file basename
+...
\immediate\write\myfile@{Hello world!@}
- ...
+...
\immediate\closeout\myfile
@end example
+ at findex \newwrite
@noindent
The @code{\newwrite} allocates a stream number, giving it a symbolic
-name to make life easier, so that @code{test
-\newwrite\myfile\the\myfile} produces something like @samp{test 3}.
+name to make life easier, so that @code{stream
+\newwrite\myfile\the\myfile} produces something like @samp{stream 3}.
Then @code{\openout} associates the stream number with the given file
-name. With that, @code{\write3} puts the string in the file.
+name. @TeX{} ultimately executed @code{\write3} which puts the string
+in the file.
-Typically @var{number} is between 0 and at tie{}15 because typically
- at LaTeX{} authors follow the prior example and the number is allocated by
-the system. If @var{number} is outside the range from 0 to 15 or if it
-is not associated with an open file then @LaTeX{} writes @var{string} to
-the log file. If @var{number} is positive then in addition @LaTeX{}
-writes @var{string} to the terminal. Thus, @code{test \write-1@{Hello
-World!@}} puts @samp{Hello World!} followed by a newline in the log
-file. (This is what the @code{\wlog} command does; @pxref{\wlog}). And
- at code{\write100@{Hello World!@}} puts the same in the log file but also
-puts @samp{Hello World!} followed by a newline in the terminal output.
-(But 16, 17, and 18 are special as @var{number}; see below.)
+ at cindex log file, writing to
+ at cindex terminal, writing to
+ at cindex @math{-1}, write stream number
+Typically @var{number} is between 0 and at tie{}15, because typically
+ at LaTeX{} authors follow the prior example and the number is allocated
+by the system. If @var{number} is outside the range from 0 to 15 or
+if it is not associated with an open file then @LaTeX{} writes
+ at var{string} to the log file. If @var{number} is positive then in
+addition @LaTeX{} writes @var{string} to the terminal.
+Thus, @code{test \write-1@{Hello World!@}} puts @samp{Hello World!}
+followed by a newline in the log file. (This is what the @code{\wlog}
+command does; @pxref{\wlog}). And @code{\write100@{Hello World!@}}
+puts the same in the log file but also puts @samp{Hello World!}
+followed by a newline in the terminal output. (But 16, 17, and 18 are
+special as @var{number}; see below.)
+
+ at cindex Lua at TeX{}, 256 output streams in
In Lua at TeX{}, instead of 16 output streams there are 256
(@pxref{@TeX{} engines}).
-Write to the current @file{.aux} file, which is associated with the root
-file or with the current include file, using
- at code{\write\@@auxout@{@var{string}@}}. Write to the main @file{.aux}
-file using @code{\write\@@mainaux@{@var{string}@}}.
+ at findex \@@auxout
+ at findex \@@mainaux
+Use @code{\write\@@auxout@{@var{string}@}} to write to the current
+ at file{.aux} file, which is associated with either the root file or
+with the current include file; and use
+ at code{\write\@@mainaux@{@var{string}@}} to write to the main
+ at file{.aux}. These symbolic names are defined by @LaTeX{}.
- at c Credit: David Carlisle https://tex.stackexchange.com/a/115933/121234
-By default @LaTeX{} does not write @var{string} to the file right away.
-This is because, for example, you may use @code{\write} to save the
-current page number but when @TeX{} comes across a @code{\write} it may
-be not yet sure what page this is, since it has not yet done the page
-breaking. So you @code{\write} in one of three contexts.
+ at c credit: David Carlisle https://tex.stackexchange.com/a/115933/121234
+By default @LaTeX{} does not write @var{string} to the file right
+away. This is because, for example, you may need @code{\write} to
+save the current page number, but when @TeX{} comes across a
+ at code{\write} it typically does not know what the page number is,
+since it has not yet done the page breaking. So, you use @code{\write}
+in one of three contexts:
@example
-\immediate\write\@@auxout@{@var{string}@}
-\write\@@auxout@{@var{string}@}
-\protected@@write\@@auxout@{@}@{@var{string}@}
+\immediate\write\@@auxout@{@var{string}@} %1
+\write\@@auxout@{@var{string}@} %2
+\protected@@write\@@auxout@{@}@{@var{string}@} %3
@end example
-With the first, @LaTeX{} writes @var{string} to the file. Any macros in
- at var{string} will be expanded (just as in @code{\edef} so that to
-prevent expansion you should use @code{\noexpand} or a @code{toks},
-except that you should use @code{#} instead of @code{##}). With the
-second, @var{string} is stored on the current list of things (as a
- at TeX{} ``whatsit'') and kept until the page is shipped out and likewise
-the macros are unexpanded until shipout. The third,
- at code{\protected@@write}, is like the second except that you can use
- at code{\protect} on fragile macros. The extra first argument allows you
-to locally insert extra definitions to make more macros be safe or
-have special definition during the write.
+ at enumerate
+ at item
+ at cindex immediate @code{\write}
+ at findex \immediate\write
+With the first, @LaTeX{} writes @var{string} to the file immediately.
+Any macros in @var{string} are fully expanded (just as in
+ at code{\edef}) so to prevent expansion you must use @code{\noexpand},
+ at code{toks}, etc., except that you should use @code{#} instead of
+ at code{##}).
-Here @var{string} contains a control sequence.
+ at item
+ at cindex delayed @code{\write}
+ at cindex whatsit item
+ at findex \shipout @r{and expansion}
+With the second, @var{string} is stored on the current list of things
+(as a @TeX{} ``whatsit'' item) and kept until the page is shipped out
+and likewise the macros are unexpanded until @code{\shipout}. At
+ at code{\shipout}, @var{string} is fully expanded.
+ at item
+ at findex \protected@@write
+The third, @code{\protected@@write}, is like the second except that
+you can use @code{\protect} to avoid expansion. The extra first
+argument allows you to locally insert extra definitions to make more
+macros protected or to have some other special definition for the
+write.
+ at end enumerate
+
+As a simple example of expansion with @code{\write}, @var{string} here
+contains a control sequence @code{\triplex} which we've defined to be
+the text @samp{XYZ}:
+
@example
\newwrite\jhfile
\openout\jhfile=test.jh
-\newcommand@{\triplex@}@{XXX@}
+\newcommand@{\triplex@}@{XYZ@}
\write\jhfile@{test \triplex test@}
@end example
@noindent
-This results in the file @file{test.jh} containing @samp{test XXXtest}
-followed by a newline.
+This results in the file @file{test.jh} containing the text
+ at samp{test XYZtest} followed by a newline.
+ at cindex @code{\write} streams 16, 17, 19
The cases where @var{number} is 16, 17, or 18 are special. Because of
@code{\write}'s behavior when @var{number} is outside the range from 0
to 15 described above, in Plain at tie{}@TeX{} @code{\write16} and
@code{\write17} were sometimes used to write to the log file and the
-terminal. Note that in @LaTeX{} the natural way to do that is with
- at code{\typeout} (@pxref{\typeout}). The @code{\write18} command is even
-more special; modern @TeX{} systems use it for giving commands to the
-operating system (@pxref{\write18}).
+terminal; however, in @LaTeX{}, the natural way to do that is with
+ at code{\typeout} (@pxref{\typeout}). The @code{\write18} command is
+even more special; modern @TeX{} systems use it for giving commands to
+the operating system (@pxref{\write18}).
-Ordinarily @code{\write} outputs a single line. Put in a newline with
- at code{^^J}. Thus, this produces two lines in the log file.
+ at cindex newline, in @code{\write}
+ at cindex @code{^^J}, in @code{\write}
+Ordinarily @code{\write} outputs a single line. You can include a
+newline with @code{^^J}. Thus, this produces two lines in the log
+file:
@example
\wlog@{Parallel lines have a lot in common.^^JBut they never meet.@}
@end example
+ at PkgIndex{answers}
+A common case where authors need to write their own file is for
+answers to exercises, or another situation where you want to write
+out verbatim, without expanding the macros. CTAN has a number of
+packages for this; one is @file{answers}.
+
+ at menu
+* Security: \write and security.
+* \message:: Write text to the log file and terminal.
+* \wlog:: Write text to the log file.
+* \write18:: Run an operating system command.
+ at end menu
+
+
+ at node \write and security
+ at subsection @code{\write} and security
+
+ at cindex security and @code{\write}
+ at cindex @code{\write} and security
+
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
-output directory, if specified (@pxref{output directory}), or in a
-subdirectory of those. So, this code
+would be justifiably troubled.
+Thus, by default @TeX{} systems only allow 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
\openout\jhfile=../test.jh
@end example
@noindent
-gives an error like @samp{Not writing to ../test.jh (openout_any = p). !
-I can't write on file `../test.jh'}. Note that you can get such an
-error when trying to use commands such as @code{\include@{../filename@}}
-because @LaTeX{} will try to open @file{../filename.aux}. The simplest
-solution is to put the included files in the same directory as the
-root file, or in subdirectories.
+gives an error like:
+ at example
+Not writing to ../test.jh (openout_any = p).
+! I can't write on file `../test.jh'
+ at end example
- at PkgIndex{answers}
-A common case where authors want to write a file not already provided by
- at LaTeX{} is for answers to exercises, or some other situation where you
-want to write out verbatim, without expanding the macros. CTAN has a
-number of packages for this; one is @file{answers}.
+ at cindex parent directories, cannot write to
+You can get just such an error when using commands such as
+ at code{\include@{../filename@}} because @LaTeX{} will try to open
+ at file{../filename.aux}. The simplest solution is to put the included
+files in the same directory as the root file, or in subdirectories.
- at menu
-* \message:: Write text to the log file and terminal.
-* \wlog:: Write text to the log file.
-* \write18:: Run an operating system command.
- at end menu
-
@node \message
@subsection @code{\message}
More information about the latexrefman-commits
mailing list.