diff options
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/scrwfile-en.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/doc/scrwfile-en.tex | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/scrwfile-en.tex b/macros/latex/contrib/koma-script/doc/scrwfile-en.tex new file mode 100644 index 0000000000..1782d26e65 --- /dev/null +++ b/macros/latex/contrib/koma-script/doc/scrwfile-en.tex @@ -0,0 +1,265 @@ +% ====================================================================== +% scrwfile-en.tex +% Copyright (c) Markus Kohm, 2010-2022 +% +% 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.md. +% ====================================================================== +% +% Chapter about scrwfile of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrwfile-en.tex}% + [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $ + KOMA-Script guide (chapter: scrwfile)] + +\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. It should be +explicitly noted that this only works in the document preamble. + +\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 +%%% TeX-master: "scrguide-en.tex" +%%% coding: utf-8 +%%% ispell-local-dictionary: "en_GB" +%%% eval: (flyspell-mode 1) +%%% End: |