summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex')
-rw-r--r--Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex314
1 files changed, 165 insertions, 149 deletions
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 56b8569d7bf..78253e34e09 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
@@ -1,6 +1,6 @@
% ======================================================================
% scrwfile.tex
-% Copyright (c) Markus Kohm, 2010-2017
+% Copyright (c) Markus Kohm, 2010-2018
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
@@ -18,7 +18,7 @@
% This work consists of all files listed in manifest.txt.
% ----------------------------------------------------------------------
% scrwfile.tex
-% Copyright (c) Markus Kohm, 2010-2017
+% Copyright (c) Markus Kohm, 2010-2018
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
@@ -46,177 +46,190 @@
% ============================================================================
\KOMAProvidesFile{scrwfile.tex}%
- [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $
+ [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $
KOMA-Script guide (chapter: scrwfile)]
-% Date of the translated German file: 2017-01-02
+% Date of the translated German file: 2018-02-15
-\translator{Markus Kohm\and Jana Schubert}
+\translator{Markus Kohm\and Jana Schubert\and Karl Hagen}
-\chapter[{Economise and Replace Files Using \Package{scrwfile}}]
-{Economise and Replace Files Using \Package{scrwfile}%
-}
+\chapter{Economising and Replacing Files with \Package{scrwfile}}
\labelbase{scrwfile}
\BeginIndexGroup
\BeginIndex{Package}{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
-type of float, every new index and several other packages, e.g.,
-\Package{hyperref} need write handles, too.
-
-The bottom line is, that this eventually will result in the error message:
+One of the problems not solved by the introduction of \eTeX{} is the fact that
+\TeX{} can support only 18 open write handles. This number seems quite large
+at first, but many of these handles are already reserved. \TeX{} itself uses
+handle 0 for the log file. \LaTeX{} needs 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}, and one
+handle for \Macro{makeindex}. Every other such list generates another handle,
+and packages like \Package{hyperref} or \Package{minitoc} require write
+handles too.
+
+The bottom line is that eventually you may get the following error message:
\begin{lstcode}
! No room for a new \write .
\ch@ck ...\else \errmessage {No room for a new #3}
\fi
\end{lstcode}
-There is an additional disadvantage of immediately opening a new write handle
-for every table of contents, list of figures, list of tables etc. These are
-not only set by the corresponding commands, they also could 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 an amendment of the \LaTeX{} kernel,
-that solves both problems.
-
-\section{General Modifications of the \LaTeX{} Kernel}
+For some time, the simplest solution to this problem has been to use
+\mbox{Lua\LaTeX} instead of \mbox{pdf\LaTeX} or \XeLaTeX. This eliminates the
+restriction, and the maximum number of files you can have open for writing is
+then limited only by the operating system. In reality, you usually so not need
+to worry about it any more.
+
+The fact that \LaTeX{} always opens a new file for writing every table of
+contents, list of figures, list of tables, etc. has another disadvantage. Such
+lists are not only output by their respective commands, they also could not be
+output a second time because the associated auxiliary file\footnote{The term
+ \emph{auxiliary file} here refers not to the main \File{aux} file but to the
+ other internal files used indirectly via the \File{aux} file, e.\,g. the
+ \File{toc} file, the \File{lof} file, or the \File{lot} file.} is empty
+after the respective command until the end of the document.
+
+The \Package{scrwfile} package makes a fundamental change to the \LaTeX{}
+kernel, which can solve both problems not only for \mbox{Lua\LaTeX} but also
+for \mbox{pdf\LaTeX} or \XeLaTeX.
+
+\section{Fundamental Changes to the \LaTeX{} Kernel}
\seclabel{kernelpatches}
-To allocate a new file handle eg. for \Macro{listoffigures} or
-\Macro{listoftables} \LaTeX{} classes use the \LaTeX{} kernel command
-\Macro{@starttoc}\IndexCmd{@starttoc}. This command not only inputs the
-associated helper file but also allocates a new write handle for the
-associated helper file and opens it for writing. Nevertheless, if afterwards
-new entries to these lists of floats are added using \Macro{addcontentsline},
-then these file handles are not used immediately, instead \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 become real write operations
-on the helper files. Additionally \LaTeX{} does not close the helper files
-explicitly. Instead \LaTeX{} relies on \TeX{} to close all open files at
-the end.
-
-Thus all the helper files are open throughout the entire process. However the
-content is written at \Macro{end}\PParameter{document}. The basic idea of
-\Package{scrwfile} is tackling this contradiction by redefining
+\LaTeX{} classes use the \LaTeX{} kernel command
+\Macro{@starttoc}\IndexCmd{@starttoc} to allocate a new file handle, such as
+for \Macro{tableofcontents} or \Macro{listoffigures}. This command not only
+loads the associated auxiliary file but also reopens it for writing. If
+entries to these lists are added using \Macro{addcontentsline}, however, the
+system does not write directly to these auxiliary files. Instead, \LaTeX{}
+writes \Macro{@writefile}\IndexCmd{@writefile} commands to the \File{aux}
+file. Only while reading the \File{aux} file at the end of the document do
+those \Macro{@writefile} commands become actual write operations in the
+auxiliary files. Additionally, \LaTeX{} does not close the auxiliary files
+explicitly. Instead it relies on \TeX{} to close all open files at the end.
+
+This procedure ensures that the auxiliary files are only written to within
+\Macro{end}\PParameter{document}, but they remain open throughout the entire
+\LaTeX{} run. \Package{scrwfile} takes is starting point here, by redefining
\Macro{@starttoc} and \Macro{@writefile}.
-Surely\textnote{Attention!}, changes of the \LaTeX{} kernel may
-result in incompatibilities with other packages. In case of
-\Package{scrwfile}, clashes my arise with all packages also redefining
-\Macro{@starttoc} or \Macro{@writefile}. Sometimes changing the order of
-loading the packages may help.
-
-However, only few such problems have been reported eventhough several users
-have tested the package for one year before its first release. See
-\autoref{sec:scrwfile.incompatible} for more information about known
-incompatibilities. If you find such a problem, please contact the
+Of course\textnote{Attention!} changes to the \LaTeX{} kernel always have the
+potential to cause incompatibilities with other packages. Those primarily
+affected may be those which also redefine \Macro{@starttoc} or
+\Macro{@writefile}. In some cases, it may help to change the order the
+packages are loaded. If you encounter such a problem, please contact the
\KOMAScript{} author.
-\section{The Single File Feature}
+\section{The Single-File Method}
\seclabel{singlefilefeature}
-At the point the package is loaded using, e.\,g.,
+As soon as the package is loaded with
\begin{lstcode}
\usepackage{scrwfile}
\end{lstcode}
-\Package{scrwfile} will redefine \Macro{@starttoc}\IndexCmd{@starttoc} to not
-longer allocate a write 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 no 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,
-loading \Package{scrwfile} gives one extra write file handle,
-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} is not
-limited any longer.
-
-\section{The Clone File Write Feature}
+\Package{scrwfile} redefines \Macro{@starttoc}\IndexCmd{@starttoc} so that it
+no longer allocates a write handle or opens a file for writing.
+\Macro{@writefile} is redefined so that immediately before closing the
+\File{aux} file in \Macro{end}\PParameter{document}, it writes not to the
+usual auxiliary files but to a single new file with extension \File{wrt}.
+After reading the \File{aux} file, this \File{wrt} file will be processed once
+for each of the auxiliary files that \Macro{@writefile} writes information to.
+However these auxiliary files do not all have to be open at the same time.
+Instead, only one is open at a time and is explicitly closed afterwards. Since
+\LaTeX{} reuses an internal write file, \Package{scrwfile} doesn't need its
+own write handle for this type of table of contents or list of floating
+environments.
+
+Because of this behaviour, even if you have only one table of contents, once
+you load \Package{scrwfile} you will have access to a write file handle for
+bibliographies, indexes, glossaries, and similar lists that do not use
+\Macro{@starttoc}. Additionally, you can create any number of tables of
+contents and other lists that use \Macro{@starttoc}\IndexCmd{@starttoc}.
+
+\section{The File Cloning Method}
\seclabel{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 more, this can be done
-by simply using \Macro{@starttoc} several times with the same extension. But
-sometimes you may have additional entries in only some of the content
-directories. \Package{scrwfile} allows to copy all entries of a file to
-another file, too. We call this cloning.
+Since \Macro{@writefile}\IndexCmd{@writefile} has already been modified for
+the single-file method described in the previous system so that it no longer
+writes directly to the corresponding auxiliary file, a further possibility
+suggests itself. When copying the \Macro{@writefile} statements into the
+\File{wrt} file, you can also copy them to other destinations.
\begin{Declaration}
\Macro{TOCclone}%
- \OParameter{heading}\Parameter{source}\Parameter{destination}
+ \OParameter{list heading}\Parameter{source extension}%
+ \Parameter{destination extension}
\end{Declaration}
-activates the clone feature for files with extensions \PName{source} and
-\PName{destination}. All entries to the file
-\Macro{jobname}\File{.}\PName{source} will be added to
-\Macro{jobname}\File{.}\PName{destination}.
-
-If extension \PName{destination} is a new one, \PName{destination} will be
-added to the list of known extensions using the \KOMAScript{} package
-\Package{tocbasic}.
-
-If the optional argument \PName{heading} is given, a new list-of macro
-\Macro{listof}\PName{destination} is defined. \PName{heading} will be used
-as section (or chapter) heading of this list. In this case several
-\Package{tocbasic} features of the \PName{source} will be copied to
-\PName{destination}, if and only if they have been set up when
-\Macro{TOCclone} was used. Feature \PName{nobabel} will always be set,
-because the language selection commands are part of the helper file and
-would be cloned, anyway.
+This cloning of file entries copies entire tables of contents or other lists.
+For this, you only need to specify the extension of the auxiliary file whose
+entries should be copied and the extension of a destination file. The entries
+are then copied there. Of course, you can also write additional entries to
+this cloned file.
+
+You can manage the \PName{destination extention} using
+\hyperref[cha:tocbasic]{\Package{tocbasic}}%
+\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} (see
+\autoref{cha:tocbasic}). If such a file is already under the control of
+\hyperref[cha:tocbasic]{\Package{tocbasic}}, a warning will be issued.
+Otherwise, a new list for this extension will be created using
+\hyperref[cha:tocbasic]{\Package{tocbasic}}. You can set the heading for this
+list with the optional argument \PName{list heading}.
+
+You can then output this new content list, for example, with the command
+\Macro{listof\PName{destination extension}}. The content-list
+attributes\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}}
+\PValue{leveldown}, \PValue{numbered}, \PValue{onecolumn}, and \PValue{totoc}
+(see \DescRef{tocbasic.cmd.setuptoc} in \autoref{sec:tocbasic.toc},
+\DescPageRef{tocbasic.cmd.setuptoc}) are automatically copied to the
+destination list if they were already set in the source list. The
+\PValue{nobabel} attribute is always set for cloned content lists, because the
+language-selection commands in the source content list are already copied
+anyway.
\begin{Example}
-Assumed, you want a short table of contents
-with only the chapter level but an additional entry with the table of
-contents:
+ Suppose you want a short table of contents with only the chapter level in
+ addition to the normal the table of contents:
\begin{lstcode}
\usepackage{scrwfile}
- \TOCclone[Short \contentsname]{toc}{stoc}
+ \TOCclone[Summary Contents]{toc}{stoc}
\end{lstcode}
-This would create a new table of contents with the heading ``Short
-Contents''. The new table of contents uses a helper file with extension
-\File{stoc}. All entries to the helper file with extension \File{toc} will
-also be copied to this new helper file.
+ This creates a new table of contents with the heading ``Summary Contents''.
+ The new table of contents uses an auxiliary file with the extension
+ \File{stoc}. All entries to the auxiliary file with extension \File{toc}
+ will also be copied to this new auxiliary file.
-The new short table of contents should only have the chapter entries. This may
-be done using:
+ In order to have the new short table of contents display only the chapter
+ entries, we use:
\begin{lstcode}
\addtocontents{stoc}{\protect\value{tocdepth}=0}
\end{lstcode}
-Normally you cannot write into a helper file before
-\Macro{begin}\PParameter{document}. But using \Package{scrwfile} changes
-this. So the code above is correct already after loading \Package{scrwfile}.
-
-To show the new short contents of helper file extension \File{stoc} we
-use
+ Although\textnote{Attention!} normally you cannot write to an auxiliary file
+ before \Macro{begin}\PParameter{document}, the code above works in the
+ preamble after loading \Package{scrwfile}. Owing to the unconventional way
+ of changing the \DescRef{maincls.counter.tocdepth} counter within the TOC
+ file, this change only applies to this content list.
+
+ Later in the document, we then output the content list with the file
+ extension \File{stoc} with:
\begin{lstcode}[moretexcs={listofsttoc}]
\listofstoc
\end{lstcode}
-somewhere after \Macro{begin}\PParameter{document}.
+ and this shows only the parts and chapters of the document.
-If we also want an entry for the table of contents at the short contents, we
-cannot use
+ Things become a bit more difficult if the summary contents are to be
+ listed in the table of contents. This would seem to be possible with
\begin{lstcode}
- \addtocontents{toc}{% write to the Contents
- \protect\addcontentslinedefault{stoc}% write to Short Contents
- {chapter}% a chapter entry with
- {\contentsname}% the Contents' name
+ \addtocontents{toc}{%
+ \protect\addxcontentsline
+ {stoc}{chapter}{\protect\contentsname}%
}
\end{lstcode}
-because the \Macro{addcontentsline} command would be copied to \File{stoc}
-too. So we cannot add the command to the \File{toc}-file. Package
-\Package{tocbasic}\important{\Package{tocbasic}} may be used to solve this:
+However, since all entries in \File{toc} are also copied to \File{stoc}, this
+entry would also be copied from the summary contents. So we cannot generate
+the entry from the content list. Because we use the
+\Package{tocbasic}\important{\Package{tocbasic}} package, we can use the
+following:
\phantomsection\xmpllabel{cmd.BeforeStartingTOC}
\begin{lstcode}
\BeforeStartingTOC[toc]{%
@@ -224,45 +237,48 @@ too. So we cannot add the command to the \File{toc}-file. Package
{\protect\contentsname}%
}
\end{lstcode}
-However, this needs, that the file with extension \File{toc} is under control
-of package \Package{tocbasic}, which is indeed the case within all
+Of course, this assumes that the \File{toc} file is under the control
+of the \Package{tocbasic} package, which is indeed the case for all
\KOMAScript{} classes. See \autoref{sec:tocbasic.toc} on
\DescPageRef{tocbasic.cmd.BeforeStartingTOC} for more information about
-\DescPageRef{tocbasic.cmd.BeforeStartingTOC}.%
+\DescRef{tocbasic.cmd.BeforeStartingTOC}.%
\end{Example}
+Incidentally, the \DescRef{tocbasic.cmd.addxcontentsline} command used in the
+examples is also documented in \autoref{cha:tocbasic},
+\DescPageRef{tocbasic.cmd.addxcontentsline}.%
\EndIndexGroup
-\section{Note on State of Development}
+\section{Note on the State of Development}
\seclabel{draft}
-Eventhough this package has been tested by several users and even is in
-productivity usage several times it is still under construction. Therefore,
-there might be amendments especially to the internal functionality. Most likely
-the package will be extended. Some code for extensions is already in the
-package. However, there is currently no user documentation available, as up to
-now nobody has requested any of these extensions.
+Although this package has already been tested by many users and is often in
+production use, its development is still ongoing. Therefore, it is
+theoretically possible that there might be changes, especially to the internal
+functionality. It is likely that the package will be extended in the future.
+Some code for such extensions is already in the package. However, as there are
+no user commands that make use of these features, they are currently
+undocumented.
\section{Known Package Incompatibilities}
\seclabel{incompatible}
-As mentioned in \autoref{sec:scrwfile.kernelpatches},
-\Package{scrwfile} redefines some commands of the \LaTeX{} kernel. This
-happens not only while loading the package, but indeed at different times of
-processing a document, e.\,g., just before reading the
-\File{aux}-file. This\textnote{Attention!} results in incompatibility with
-packages that also redefine these commands at run-time.
+As mentioned in \autoref{sec:scrwfile.kernelpatches}, \Package{scrwfile}
+redefines some commands of the \LaTeX{} kernel. This happens not only while
+loading the package, but indeed at various times while the document is
+processed, for example just before reading the \File{aux} file.
+This\textnote{Attention!} results in incompatibility with packages that also
+redefine these commands at run time.
The \Package{titletoc}\important{Package{titletoc}}\IndexPackage{titletoc}
-package is an example for such an incompatibility. That
-package redefines \Macro{@writefile} under some conditions at run-time. If you
-use both, \Package{scrwfile} and \Package{titletoc}, there is no warranty for
-the correct behaviour of neither of them. This is neither an error of
-\Package{titletoc} nor of \Package{scrwfile}.
-
+package is an example for such an incompatibility. That package redefines
+\Macro{@writefile} under some conditions at run time. If you use both
+\Package{scrwfile} and \Package{titletoc}, there is no warranty for the
+correct behaviour of either one. This is neither an error of
+\Package{titletoc} nor of \Package{scrwfile}.%
+%
\EndIndexGroup
-
%%% Local Variables:
%%% mode: latex
%%% mode: flyspell