From 33a91552392adacad1480db2e7ea4e966c0f4533 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Wed, 16 May 2012 23:12:50 +0000
Subject: koma-script (15may12)

git-svn-id: svn://tug.org/texlive/trunk@26455 c570f23f-e606-0410-a88d-b1316a301751
---
 .../latex/koma-script/doc/english/scrwfile.tex     | 182 ++++++++++++---------
 1 file changed, 101 insertions(+), 81 deletions(-)

(limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex')

diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex
index 0ecb1c9a7fb..baf1d38f565 100644
--- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex
+++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex
@@ -45,94 +45,101 @@
 %% 
 %%% From File: scrwfile.dtx
 \ProvidesFile{scrwfile.tex}
-  [2011/09/11 v0.1c-alpha LaTeX2e KOMA-Script package (write and clone files)]
+  [2012/03/05 v0.1d-alpha LaTeX2e KOMA-Script package (write and clone files)]
 \chapter[{Spare and Replace Files Using \Package{scrwfile}}]
 {Spare and Replace Files Using \Package{scrwfile}%
-  \footnote{This chapter has been generated from \File{scrwfile.dtx}.}%
 }
 \labelbase{scrwfile}
 
-\TeX{} supports 18 write handles only. Handle 0 is used
-by \TeX{} itself (log file). \LaTeX{} needs at least handle 1 for
-\Macro{@mainaux}, handle 2 for \Macro{@partaux}, one handle for
-\Macro{tableofcontents}, one handle for \Macro{listoffigures}, one
-handle for \Macro{listoftables}, one handle for \Macro{makeindex}. So
-there are 11 left. Seams a lot and enough. But every new float, every new
-index and several other packages, e.g., \Package{hyperref} need write
-handles, too. Loading \Package{scrwfile} minimizes the need of write
-handles for list of floats or tables of contents. Additionally it allows
-to clone entries from one file to another file.
-
-\section{The Idea}
-\label{sec:scrwfile.idea}
-
-Table of contents, list of figures, list of tables and other content
-directories make use of a small amount of \LaTeX{} kernel macros to open
-helper files, write to those helper files and read them. The first macro is
-\Macro{@starttoc}. It is used inside of \Macro{tableofcontents},
-\Macro{listoffigure}, \Macro{listoftable} and many \Macro{listof} macros of
-several packages.
-
-The primary macro \Macro{@starttoc} reads the helper file with the contents
-of the directory. But this kernel macro also calls for a new write handle
-and even opens the helper file for writing. So every call of this macro
-consumes one of the rare write handles.
-
-But while the document is processed nobody writes to that handle until
-\Macro{end}\PParameter{document}. Every write operation should be done using
-\Macro{addtocontents} or \Macro{addcontentsline}, that internally uses
-\Macro{addtocontents}, too. The macro \Macro{addtocontents} does not really
-write to the helper file, but writes a \Macro{@writefile} macro to the main
-or part \File{aux} file.
-
-At \Macro{end}\PParameter{document} the main \File{aux} file is closed and
-after closing \LaTeX{} inputs the main \File{aux} file. While this reading
-the \Macro{@writefile} macros are processed and only then the helper
-files are written.
-
-You see, there is no need to hold the helper files open while the document
-is processed. The helper files need to be opened only before reading the
-\File{aux} file at \Macro{end}\PParameter{document}. Even you do not need
-one write handle per helper file, if you only could write one after the
-other. In this case only one write handle would be needed. And that's the
-idea.
-
-\section{Using the Package}
-\label{sec:scrwfile.usage}
-
-First of all you have to load the package. This may be simply done using
-\begin{lstcode}
-  \usepackage{scrwfile}
-\end{lstcode}
-or if you are a package author by using
-\begin{lstcode}
-  \RequirePackage{scrwfile}
-\end{lstcode}
-This also activates the \emph{single file feature}.
-
-\subparagraph*{Note:} The package \Package{scrwfile} may be used with other
-files, that redefine \Macro{@starttoc}. But if these files do a complete
-new definition of \Macro{@starttoc} you should load them before
-\Package{scrwfile} to avoid errors.
-
-\subsection{The Single File Feature}
-
-To activate the single file feature, that means, that \Macro{\@starttoc}
-does not longer consumes write handles and every open and write to helper
-file action will be done at \Macro{end}\PParameter{document}, you only need
-to load package \Package{scrwfile}.
+\BeginIndex{Package}{scrwfile}
 
-See \autoref{sec:scrwfile.idea} for more information about the idea of this
-feature.
+\TeX{} supports 18 write handles only. Handle 0 is used by \TeX{} itself (log
+file). \LaTeX{} needs at least handle 1 for \Macro{@mainaux}, handle 2 for
+\Macro{@partaux}, one handle for \Macro{tableofcontents}, one handle for
+\Macro{listoffigures}, one handle for \Macro{listoftables}, one handle for
+\Macro{makeindex}. So there are 11 left. Seams a lot and enough. But every new
+type of float, every new index and several other packages, e.g.,
+\Package{hyperref} need write handles, too.
 
-\subparagraph*{Note:} Package \Package{scrwfile} uses package
-\Package{scrlfile} to redefine \Macro{@writefile} while
-\Macro{end}\PParameter{document}. Instead of directly writing to the helper
-files \Macro{@writefile} itself will write to a new helper file
-\Macro{jobname}\File{.wrt}. To write all the helper files this will file be
-input several times. One time for each helper file.
+The bottom line is, that this eventually will result in the error message:
+\begin{lstcode}
+  ! No room for a new \write .
+  \ch@ck ...\else \errmessage {No room for a new #3}
+                                                    \fi
+\end{lstcode}
 
-\subsection{The Clone File Write Feature}
+Last but not least, immediately opening one more write handle for every table
+of contents, list of figures, list of tables, and so on has one more
+disadvantage. These are not only set by the corresponding commands, they also
+couldn't not be set once more, because their helper files are empty after the
+corresponding commands until the end of the document.
+
+Package \Package{scrwfile} provides a general change of the \LaTeX{} kernel,
+that may solve both problems.
+
+\section{General Modifications of the \LaTeX{} Kernel}
+\label{sec:scrwfile.kernelpatches}
+
+\LaTeX{} classes use the \LaTeX{} kernel command
+\Macro{@starttoc}\IndexCmd{@starttoc} for output and opening of a new table of
+contents, list of float, e.\,g., \Macro{listoffigures} or
+\Macro{listoftables}, or similar. Thereby \LaTeX{} not only reads the helper
+file with the contents of the directory, but opens the helper file for writing
+also. Nevertheless, if afterwards new entries to these lists of floats will be
+made using \Macro{addcontentsline}, then this will not write immediately to
+the helper file. Instead of \LaTeX{} writes
+\Macro{@writefile}\IndexCmd{@writefile} commands into the
+\File{aux}-file. Only while reading the \File{aux}-file while the end of the
+document, those \Macro{@writefile} commands generates real write operations
+into the helper files. \LaTeX{} even doesn't close the helper files
+explicitly. Instead of \LaTeX{} counts on \TeX{} to close all open files at
+the end.
+
+This procedure means, that all the helper files are open for writing from the
+output of the contents, i.\,e. at the front matter of the document until the
+end of the document, though their content is written after the end of the
+document. \Package{scrwfile}'s basic approach is exactly this: redefinition of
+\Macro{@starttoc} and \Macro{@writefile}.
+
+Surely\textnote{Attention!}, changes of the \LaTeX{} kernel always may
+potentially result in incompatibilities with other packages. In case of
+\Package{scrwfile} this may be happen with all packages, that redefine
+\Macro{@starttoc} or \Macro{@writefile} too. Sometimes changing the order of
+loading the packages may help.
+
+In fact, such problems with \Package{scrwfile} haven't been reported currently,
+though several users have tested the package for more than a year until first
+release. Nevertheless, if you find such a problem, please contact the
+\KOMAScript{} author.
+
+\section{The Single File Feature}
+\label{sec:scrwfile.singlefilefeature}
+
+Just while loading the package using, e.\,g.,
+\begin{lstcode}[belowskip=\dp\strutbox]
+  \usepackage{scrwfile}
+\end{lstcode}
+\Package{scrwfile} will redefine \Macro{@starttoc}\IndexCmd{@starttoc} to not
+longer allocate a file handle or open any file for writing. Immediately before
+closing the \File{aux}-file in \Macro{end}\PParameter{document} it will
+redefine \Macro{@writefile} to not longer write into the usual helper files
+but into one single new file with file extension \File{wrt}. After
+reading the \File{aux}-file this \File{wrt}-file will be processed once per
+helper file. This means, that not all of the helper file have to be open at
+the same time, but only one at a time. And this single file will be closed
+afterwards and the write handle is not longer needed after it is closed. An
+internal write handle of \LaTeX{} is used for this. So \Package{scrwfile}
+doesn't need any own write handle.
+
+Because of this, even if only one table of contents should be generated, after
+loading \Package{scrwfile} one more write file handle will be available,
+e.\,g., for bibliographies, indexes, glossaries and similar, that are not
+using \Macro{@starttoc}. Additionally the number of tables of contents and
+lists of whatever, that use \Macro{@starttoc}\IndexCmd{@starttoc} won't be
+limited any longer.
+
+\section{The Clone File Write Feature}
+\label{sec:scrwfile.clonefilefeature}
 
 Sometimes it is useful to input a file not only once but several times. As
 \Macro{@starttoc} does not open files for writing any longer, this may be
@@ -165,7 +172,7 @@ because the language selection commands are part of the helper file and
 would be cloned, too.
 
 \begin{Example}
-E.g., you want a short table of contents
+Assumed, you want a short table of contents
 with only the chapter level but an additional entry with the table of
 contents:
 \begin{lstcode}
@@ -191,6 +198,19 @@ one but this entry will not be part of the detailed table of contents.
 \end{Example}
 \EndIndex{Cmd}{TOCclone}
 
+\section{State of Development Note}
+\label{sec:scrwfile.draft}
+
+Though this package has been tested by several users and even is in
+productivity usage several times, development is not finished yet. Because of
+this especially internal functionality may be changed in future. Most likely
+the package will be extended. Some code for extensions is already in the
+package. Nevertheless, currently user haven't make requests for such
+extension. So there's currently no user documentation for this.
+
+\EndIndex{Package}{scrwfile}
+
+
 \endinput
 %%
 %% End of file `scrwfile.tex'.
-- 
cgit v1.2.3

