diff options
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.tex | 314 |
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 |