You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
288 lines
13 KiB
288 lines
13 KiB
% ======================================================================
|
|
% scrwfile.tex
|
|
% Copyright (c) Markus Kohm, 2010-2019
|
|
%
|
|
% This file is part of the LaTeX2e KOMA-Script bundle.
|
|
%
|
|
% This work may be distributed and/or modified under the conditions of
|
|
% the LaTeX Project Public License, version 1.3c of the license.
|
|
% The latest version of this license is in
|
|
% http://www.latex-project.org/lppl.txt
|
|
% and version 1.3c or later is part of all distributions of LaTeX
|
|
% version 2005/12/01 or later and of this work.
|
|
%
|
|
% This work has the LPPL maintenance status "author-maintained".
|
|
%
|
|
% The Current Maintainer and author of this work is Markus Kohm.
|
|
%
|
|
% This work consists of all files listed in manifest.txt.
|
|
% ----------------------------------------------------------------------
|
|
% scrwfile.tex
|
|
% Copyright (c) Markus Kohm, 2010-2019
|
|
%
|
|
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
|
|
% Version 1.3c, verteilt und/oder veraendert werden.
|
|
% Die neuste Version dieser Lizenz ist
|
|
% http://www.latex-project.org/lppl.txt
|
|
% und Version 1.3c ist Teil aller Verteilungen von LaTeX
|
|
% Version 2005/12/01 oder spaeter und dieses Werks.
|
|
%
|
|
% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained"
|
|
% (allein durch den Autor verwaltet).
|
|
%
|
|
% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm.
|
|
%
|
|
% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien.
|
|
% ======================================================================
|
|
%
|
|
% Chapter about scrwfile of the KOMA-Script guide
|
|
% Maintained by Markus Kohm
|
|
%
|
|
% ----------------------------------------------------------------------
|
|
%
|
|
% Kapitel ueber scrwfile in der KOMA-Script-Anleitung
|
|
% Verwaltet von Markus Kohm
|
|
%
|
|
% ============================================================================
|
|
|
|
\KOMAProvidesFile{scrwfile.tex}%
|
|
[$Date: 2019-11-18 10:57:08 +0100 (Mon, 18 Nov 2019) $
|
|
KOMA-Script guide (chapter: scrwfile)]
|
|
|
|
% Date of the translated German file: 2019-11-18
|
|
|
|
\translator{Markus Kohm\and Jana Schubert\and Karl Hagen}
|
|
|
|
\chapter{Economising and Replacing Files with \Package{scrwfile}}
|
|
\labelbase{scrwfile}
|
|
\BeginIndexGroup
|
|
\BeginIndex{Package}{scrwfile}
|
|
|
|
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}
|
|
|
|
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}
|
|
|
|
\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}.
|
|
|
|
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 Method}
|
|
\seclabel{singlefilefeature}
|
|
|
|
As soon as the package is loaded with
|
|
\begin{lstcode}
|
|
\usepackage{scrwfile}
|
|
\end{lstcode}
|
|
\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}
|
|
|
|
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{list heading}\Parameter{source extension}%
|
|
\Parameter{destination extension}
|
|
\end{Declaration}
|
|
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}
|
|
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[Summary Contents]{toc}{stoc}
|
|
\end{lstcode}
|
|
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.
|
|
|
|
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}
|
|
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}
|
|
and this shows only the parts and chapters of the document.
|
|
|
|
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}{%
|
|
\protect\addxcontentsline
|
|
{stoc}{chapter}{\protect\contentsname}%
|
|
}
|
|
\end{lstcode}
|
|
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]{%
|
|
\addcontentslinedefault{stoc}{chapter}
|
|
{\protect\contentsname}%
|
|
}
|
|
\end{lstcode}
|
|
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
|
|
\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 the State of Development}
|
|
\seclabel{draft}
|
|
|
|
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 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 either one. This is neither an error of
|
|
\Package{titletoc} nor of \Package{scrwfile}.%
|
|
%
|
|
\EndIndexGroup
|
|
|
|
%%% Local Variables:
|
|
%%% mode: latex
|
|
%%% mode: flyspell
|
|
%%% coding: us-ascii
|
|
%%% ispell-local-dictionary: "en_GB"
|
|
%%% TeX-master: "../guide"
|
|
%%% End:
|
|
|