From 8f846f8a8c7b2774059df2db0f153948e98cccf1 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Sat, 19 Feb 2011 00:37:41 +0000
Subject: FAQ-en 3.21 (18feb11)

git-svn-id: svn://tug.org/texlive/trunk@21459 c570f23f-e606-0410-a88d-b1316a301751
---
 .../doc/generic/FAQ-en/faq-bits+pieces.tex         | 118 ++++++++++++++++++++-
 1 file changed, 116 insertions(+), 2 deletions(-)

(limited to 'Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex')

diff --git a/Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex b/Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex
index 3bdf54ad03d..3f0a98bb4e3 100644
--- a/Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex
+++ b/Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex
@@ -1,4 +1,4 @@
-% $Id: faq-bits+pieces.tex,v 1.6 2010/07/18 22:32:02 rf10 Exp rf10 $
+% $Id: faq-bits+pieces.tex,v 1.8 2011/02/13 23:08:45 rf10 Exp $
 
 \section{Bits and pieces of \AllTeX{}}
 
@@ -251,6 +251,120 @@ there is no device driver around.  There \emph{is} a concept of
 \acro{PDF} specials, but in most cases \csx{special} will provoke a
 warning when used in \PDFTeX{}.
 
+\Question[Q-write]{Writing (text) files from \tex{}}
+
+\TeX{} allows you to write to output files from within your document.
+The facility is handy in many circumstances, but it is vital for
+several of the things \latex{} (and indeed almost any higher-level
+\tex{}-based macro package) does for you.
+
+The basic uses of writing to an external file are ``obvious''~---
+remembering titles of sections for a table of contents, remembering
+label names and corresponding section or figure numbers, all for a
+later run of your document.  However, the ``non-obvious'' thing is
+easy to forget: that page numbers, in \tex{}, are slippery beasts, and
+have to be captured with some care.  The trick is that \csx{write}
+operations are only executed as the page is sent to the \acro{DVI}
+or \acro{PDF} file.  Thus, if you arrange that your page-number macro
+(\csx{thepage}, in \latex{}) is not expanded until the page is
+written, then the number written is correct, since that time is where
+\tex{} guarantees the page number tallies with the page being sent
+out.
+
+Now, there are times when you want to write something straight away:
+for example, to interact with the user.  \TeX{} captures that
+requirement, too, with the primitive \csx{immediate}:
+\begin{quote}
+\begin{verbatim}
+\immediate\write\terminal{I'm waiting...}
+\end{verbatim}
+\end{quote}
+writes a ``computer-irritates-user'' message, to the terminal.
+
+Which brings us to the reason for that \csx{terminal}.  \TeX{} can
+``\csx{write}'' up to 16 streams simultaneously, and that argument to
+\csx{write} says which is to be used.  Macro packages provide the
+means of allocating streams for your use: \plaintex{} provides a macro
+\csx{newwrite}\csx{streamname}, which sets \csx{streamname} as
+the stream number.  In fact, \csx{terminal} (or its equivalent) is the
+first output stream ever set up (in most macro packages): it is never
+attached to a file, and if \tex{} is asked to write to \emph{any}
+stream that isn't attached to a file it will send the output to the
+terminal (and the log).
+
+\Question[Q-spawnprog]{Spawning programs from \AllTeX{}: \csx{write18}}
+
+The \tex{} \Qref*{\csx{write} primitive instruction}{Q-write} is used
+to write to different file `streams'; TeX refers to each open file by
+a number, not by a file name (although most of the time we hide this).
+Originally, \tex{} would write to a file connected to a stream
+numbered 0--15.  More recently, a special ``stream 18'' has been
+implemented: it is not writing to a file, but rather tells TeX to ask
+the operating system to do something.  To run a command, we put it as
+the argument to \csx{write18}.  So to run the \progname{epstopdf}
+program on a file with name stored as \csx{epsfilename}, we would
+write:
+\begin{quote}
+\begin{verbatim}
+\write18{epstopf \epsfilename}
+\end{verbatim}
+\end{quote}
+When using something like the \Package{epstopdf} package, the `stream'
+write operation is hidden away and you don't need to worry about the
+exact way it's done.
+
+However, there is a security issue. If you download some \alltex{} code from
+the Internet, can you be sure that there is not some command in it
+(perhaps in a hidden way) to do stuff that might be harmful to your
+\acro{PC} (let's say: delete everything on the hard disk!)?  In the
+face of this problem, both \miktex{} and \tex{}~Live have, for some
+time, disabled \csx{write18} by default.  To turn the facility on,
+both distributions support an additional argument when starting \tex{}
+from the command shell:
+\begin{quote}
+\begin{verbatim}
+(pdf)(la)tex --shell-escape <file>
+\end{verbatim}
+\end{quote}
+The problem with this is that many people use \alltex{} via a graphical
+editor, so to use \csx{write18} for a file the editor's settings must
+be changed.  Of course, the settings need restoring after the file is
+processed: you defeat the point of the original protection, that way.
+
+The latest \miktex{} (version 2.9), and \tex{}~Live (2010 release) get
+around this by having a special ``limited'' version of \csx{write18}
+enabled `out of the box'.  The idea is to allow only a pre-set list of
+commands (for example, \BibTeX{}, \progname{epstopdf}, \tex{} itself,
+and so on).  Those on the list are regarded as safe enough to allow,
+whereas anything else (for example deleting files) still needs to be
+authorised by the user. This seems to be a good balance: most people
+most of the time will not need to worry about \csx{write18} at all,
+but it will be available for things like \Package{epstopdf}.
+
+Note that the \tex{} system may tell you that the mechanism is in use:
+\begin{wideversion}
+\begin{quote}
+\begin{verbatim}
+This is pdfTeX, Version 3.1415926-1.40.11 (TeX Live 2010)
+ restricted \write18 enabled.
+\end{verbatim}
+\end{quote}
+\end{wideversion}
+\begin{narrowversion}
+\begin{quote}
+\begin{verbatim}
+This is pdfTeX, Version 3.1415926-1.40.11
+                              (TeX Live 2010)
+ restricted \write18 enabled.
+\end{verbatim}
+\end{quote}
+\end{narrowversion}
+when it starts.
+\begin{ctanrefs}
+\item[epstopdf.sty]Distributed with Heiko Oberdiek's packages
+  \CTANref{oberdiek}
+\end{ctanrefs}
+
 \Question[Q-hyphen]{How does hyphenation work in \TeX{}?}
 
 Everyone knows what hyphenation is: we see it in most books we read,
@@ -627,7 +741,7 @@ Adobe has specified a number of formats for files to represent fonts
 in \PS{} files; this question doesn't attempt to be encyclopaedic, so
 we only discuss the two formats most commonly encountered in the
 \AllTeX{} context, types~1 and 3.  In particular, we don't discuss the
-OpenType format, whose has many advantages have only in the last year
+OpenType format, whose many advantages have only in the last year
 or two been readily accessible to most \AllTeX{} users (by means of
 \begin{wideversion}
   the widely-used \Qref{\xetex{}}{Q-xetex} and the more experimental
-- 
cgit v1.2.3

