| 1 |
% \iffalse^^A meta-comment |
| 2 |
% ====================================================================== |
| 3 |
% scrwfile.dtx |
| 4 |
% Copyright (c) Markus Kohm, 2010-2023 |
| 5 |
% |
| 6 |
% From version 0.1 2010/10/01 up to version 0.1.11 2022/10/06 |
| 7 |
% this work was part of KOMA-Script v3.14 2014/10/28 up to |
| 8 |
% KOMA-Script v3.38 2022/10/12. |
| 9 |
% |
| 10 |
% Since version 0.1.99 2023/04/01 it has been removed from |
| 11 |
% KOMA-Script and has become a standalone package. |
| 12 |
% |
| 13 |
% This work may be distributed and/or modified under the conditions of |
| 14 |
% the LaTeX Project Public License, version 1.3c of the license. |
| 15 |
% The latest version of this license is in |
| 16 |
% http://www.latex-project.org/lppl.txt |
| 17 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 18 |
% version 2005/12/01 and of this work. |
| 19 |
% |
| 20 |
% This work has the LPPL maintenance status "unmaintained". |
| 21 |
% |
| 22 |
% The current author of this work is Markus Kohm. |
| 23 |
% |
| 24 |
% This work consists of the files `scrwfile.dtx' and `README.md'. |
| 25 |
% |
| 26 |
% For repository, issues etc. see: |
| 27 |
% <https://github.com/komascript/scrwfile>. |
| 28 |
% |
| 29 |
% Earlier versions of this work can be found in the KOMA-Script |
| 30 |
% repository on SourceForge, see: |
| 31 |
% <https://sourceforge.net/p/koma-script/code/>. |
| 32 |
% ====================================================================== |
| 33 |
%%% From File: $Id: scrwfile.dtx 4018 2023-03-31 07:31:04Z kohm $ |
| 34 |
%<*dtx> |
| 35 |
\ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi |
| 36 |
\ProvidesFile{scrwfile.dtx} |
| 37 |
%</dtx> |
| 38 |
%<package|driver>\NeedsTeXFormat{LaTeX2e}[1995/06/01] |
| 39 |
%<package>\ProvidesPackage{scrwfile} |
| 40 |
%<driver>\ProvidesFile{scrwfile.drv} |
| 41 |
%<*dtx|package|driver> |
| 42 |
[2023-03-31 v0.1.99 KOMA-Script package (write and clone files)] |
| 43 |
%</dtx|package|driver> |
| 44 |
%<*dtx> |
| 45 |
\ifx\documentclass\undefined |
| 46 |
\input docstrip.tex |
| 47 |
\generate{\usepreamble\defaultpreamble |
| 48 |
\file{scrwfile.sty}{% |
| 49 |
\from{scrwfile.dtx}{package}% |
| 50 |
}% |
| 51 |
} |
| 52 |
\else |
| 53 |
\let\endbatchfile\relax |
| 54 |
\fi |
| 55 |
\endbatchfile |
| 56 |
%</dtx> |
| 57 |
%<*driver> |
| 58 |
\documentclass[USenglish,ngerman]{koma-script-source-doc} |
| 59 |
\usepackage[main=USenglish]{babel} |
| 60 |
\usepackage{hvlogos} |
| 61 |
\usepackage{listings} |
| 62 |
\setcounter{StandardModuleDepth}{2} |
| 63 |
\let\Macro\cs |
| 64 |
\let\Package\pkg |
| 65 |
\let\PName\meta |
| 66 |
\newcommand*{\PParameter}[1]{{\ttfamily\char`\{\mbox{#1}\char`\}}} |
| 67 |
\let\File\file |
| 68 |
\let\IndexCmd\SpecialMacroIndex |
| 69 |
\newcommand*{\seclabel}[1]{\label{sec-\languagename:scrwfile.#1}} |
| 70 |
\newcommand*{\textnote}[1]{} |
| 71 |
\let\important\textnote |
| 72 |
\newcommand*{\PValue}[1]{{\ttfamily\mbox{#1}}} |
| 73 |
\newenvironment{Example}{% |
| 74 |
\setkomafont{labelinglabel}{\sffamily\bfseries}% |
| 75 |
\labeling{\examplename:} |
| 76 |
\item[\examplename:] |
| 77 |
}{\endlabeling} |
| 78 |
\newcaptionname{USenglish}{\examplename}{Example} |
| 79 |
\newcaptionname{ngerman}{\examplename}{Beispiel} |
| 80 |
\renewcaptionname{USenglish}{\contentsname}{Contents\,/\,Inhalt} |
| 81 |
\lstnewenvironment{lstcode}[1][]{% |
| 82 |
\lstset{language=[LaTeX]TeX,basicstyle=\ttfamily\small,% |
| 83 |
keywordstyle=\color{blue}, |
| 84 |
commentstyle=\color{green}, |
| 85 |
breaklines,prebreak=\mbox{$\hookleftarrow$},% |
| 86 |
moretexcs={TOCclone,addxcontentsline,contentsname}, |
| 87 |
literate=% |
| 88 |
{Ö}{{\"O}}1 |
| 89 |
{Ä}{{\"A}}1 |
| 90 |
{Ü}{{\"U}}1 |
| 91 |
{ß}{{\ss}}1 |
| 92 |
{ü}{{\"u}}1 |
| 93 |
{ä}{{\"a}}1 |
| 94 |
{ö}{{\"o}}1, |
| 95 |
#1}% |
| 96 |
}{} |
| 97 |
\lstnewenvironment{lstoutput}[1][]{% |
| 98 |
\lstset{basicstyle=\ttfamily\small,% |
| 99 |
breaklines,prebreak=\mbox{$\hookleftarrow$}, |
| 100 |
#1}% |
| 101 |
}{}% |
| 102 |
\DeclareTOCStyleEntry[beforeskip=0pt,numwidth=2em,entryformat=\textsf]{section}{section} |
| 103 |
\begin{document} |
| 104 |
\DocInput{scrwfile.dtx} |
| 105 |
\end{document} |
| 106 |
%</driver> |
| 107 |
% \fi |
| 108 |
% |
| 109 |
% \changes{v0.1}{2010/10/01}{start of new package} |
| 110 |
% \changes{v0.1.7}{2014/10/13}{manual moved to \KOMAScript{} manual} |
| 111 |
% \changes{v0.1.9}{2021/05/30}{version number scheme changed} |
| 112 |
% \changes{v0.1.10}{2022/02/05}{switch over from \cls*{scrdoc} to |
| 113 |
% \cls*{koma-script-source-doc}} |
| 114 |
% \changes{v0.1.99}{2023/04/01}{\KOMAScript{} spin-off} |
| 115 |
% |
| 116 |
% \GetFileInfo{scrwfile.dtx} |
| 117 |
% \title{% |
| 118 |
% Saving Write Handles with the Experimental Package |
| 119 |
% \pkg{scrwfile}\\\medskip |
| 120 |
% \foreignlanguage{ngerman}{Write-Handles sparen mit dem experimentellen |
| 121 |
% Paket \pkg{scrwfile}}% |
| 122 |
% } |
| 123 |
% \author{\href{mailto:[email protected]}{Markus Kohm}} |
| 124 |
% \date{Version \fileversion{} \filedate} |
| 125 |
% \maketitle |
| 126 |
% \begin{abstract} |
| 127 |
% The \TeX{} engines \TeX, \pdfTeX, and \XeTeX{} (but not \LuaTeX) do |
| 128 |
% provide only 16 handles for simultaneously write open files. Some of them |
| 129 |
% are already used by \LaTeX. Moreover, for every file using |
| 130 |
% \cs{@starttoc} \LaTeX{} keeps a write file open from usage of |
| 131 |
% \cs{@starttoc}, e.g., inside \cs{tableofcontents}, \cs{listoffigures} |
| 132 |
% etc., until the end of the document. Additional write files are used for |
| 133 |
% the index, glossary etc. So sometimes it happens, that there are not |
| 134 |
% enough handles to open another one. \pkg*{scrwfile} was made to change the |
| 135 |
% \LaTeX{} internal handling of all the helper files bases on \cs{@starttoc} |
| 136 |
% to not keep them open simultaneously, but use only one file handle for all |
| 137 |
% of them. So you should almost never run out of write file handles. |
| 138 |
% \end{abstract} |
| 139 |
% \foreignlanguage{ngerman}{% |
| 140 |
% \begin{abstract} |
| 141 |
% Die \TeX-Engines \TeX, \pdfTeX und \XeTeX{} (nicht jedoch \LuaTeX) bieten |
| 142 |
% lediglich 16 Handles, die gleichzeitig zum Schreiben geöffnet sind. Einige |
| 143 |
% davon werden bereits von \LaTeX{} selbst benötigt. Darüber hinaus hält |
| 144 |
% \LaTeX{} jede Datei, die per \cs{@starttoc} geöffnet wird, vom verwendeten |
| 145 |
% \cs{@starttoc} bis zum Ende des Dokuments zum Schreiben offen. Das |
| 146 |
% betrifft beispielsweise \cs{tableofcontents}, \cs{listoffigure} |
| 147 |
% etc. Weitere Dateien werden gegebenenfalls für Index, Glossar und ähnliche |
| 148 |
% Verzeichnisse benötigt. Daher kann es manchmal geschehen, dass keine |
| 149 |
% weitere Datei mehr zum Schreiben geöffnet werden kann. \pkg*{scrwfile} |
| 150 |
% wurde entwickelt, um \LaTeX-Interna bei der Verwendung von \cs{@starttoc} |
| 151 |
% so abzuändern, dass nicht mehr alle Dateien gleichzeitig offen bleiben |
| 152 |
% müssen. Stattdessen wird nur noch ein Handle für all diese Dateien |
| 153 |
% benötigt. Damit sollte der Fall, dass keine weiteren Dateien zum Schreiben |
| 154 |
% geöffnet werden können, kaum noch auftreten.% |
| 155 |
% \end{abstract} |
| 156 |
% } |
| 157 |
% |
| 158 |
% \tableofcontents |
| 159 |
% |
| 160 |
% \part{English User Manual} |
| 161 |
% |
| 162 |
% \noindent\textbf{This is an experimental package. Usage of this package is |
| 163 |
% on your own risk. There is no support, if you are using this package, not |
| 164 |
% only for this package but also for the class you are using or other |
| 165 |
% packages, that use \cs{@starttoc} or \cs{@writefile} like \pkg{caption}, |
| 166 |
% \pkg{float}, \pkg{tocbasic}, \pkg{listings} and many more.} |
| 167 |
% |
| 168 |
% \section{Background} |
| 169 |
%\iffalse^^A |
| 170 |
%<*docen> |
| 171 |
%\fi^^A |
| 172 |
|
| 173 |
One of the problems not solved by the introduction of \eTeX{} is the fact that |
| 174 |
\TeX{} can support only 18 open write handles. This number seems quite large |
| 175 |
at first, but many of these handles are already reserved. \TeX{} itself uses |
| 176 |
handle 0 for the log file. \LaTeX{} needs handle 1 for \cs{@mainaux}, |
| 177 |
handle 2 for \Macro{@partaux}, one handle for \Macro{tableofcontents}, one |
| 178 |
handle for \Macro{listoffigures}, one handle for \Macro{listoftables}, and one |
| 179 |
handle for \Macro{makeindex}. Every other such list generates another handle, |
| 180 |
and packages like \Package{hyperref} or \Package{minitoc} require write |
| 181 |
handles too. |
| 182 |
|
| 183 |
The bottom line is that eventually you may get the following error message: |
| 184 |
\begin{lstoutput} |
| 185 |
! No room for a new \write . |
| 186 |
\ch@ck ...\else \errmessage {No room for a new #3} |
| 187 |
\fi |
| 188 |
\end{lstoutput} |
| 189 |
|
| 190 |
For some time, the simplest solution to this problem has been to use |
| 191 |
\mbox{\LuaLaTeX} instead of \mbox{pdf\LaTeX} or \XeLaTeX. This eliminates the |
| 192 |
restriction, and the maximum number of files you can have open for writing is |
| 193 |
then limited only by the operating system. In reality, you usually so not need |
| 194 |
to worry about it any more. |
| 195 |
|
| 196 |
The fact that \LaTeX{} always opens a new file for writing every table of |
| 197 |
contents, list of figures, list of tables, etc. has another disadvantage. Such |
| 198 |
lists are not only output by their respective commands, they also could not be |
| 199 |
output a second time because the associated auxiliary file\footnote{The term |
| 200 |
\emph{auxiliary file} here refers not to the main \File{aux} file but to the |
| 201 |
other internal files used indirectly via the \File{aux} file, e.\,g. the |
| 202 |
\File{toc} file, the \File{lof} file, or the \File{lot} file.} is empty |
| 203 |
after the respective command until the end of the document. |
| 204 |
|
| 205 |
The \Package{scrwfile} package makes a fundamental change to the \LaTeX{} |
| 206 |
kernel, which can solve both problems not only for \mbox{\LuaLaTeX} but also |
| 207 |
for \mbox{pdf\LaTeX} or \XeLaTeX. |
| 208 |
|
| 209 |
\section{Fundamental Changes to the \LaTeX{} Kernel} |
| 210 |
\seclabel{kernelpatches} |
| 211 |
|
| 212 |
\LaTeX{} classes use the \LaTeX{} kernel command |
| 213 |
\Macro{@starttoc}\IndexCmd{@starttoc} to allocate a new file handle, such as |
| 214 |
for \Macro{tableofcontents} or \Macro{listoffigures}. This command not only |
| 215 |
loads the associated auxiliary file but also reopens it for writing. If |
| 216 |
entries to these lists are added using \Macro{addcontentsline}, however, the |
| 217 |
system does not write directly to these auxiliary files. Instead, \LaTeX{} |
| 218 |
writes \Macro{@writefile}\IndexCmd{@writefile} commands to the \File{aux} |
| 219 |
file. Only while reading the \File{aux} file at the end of the document do |
| 220 |
those \Macro{@writefile} commands become actual write operations in the |
| 221 |
auxiliary files. Additionally, \LaTeX{} does not close the auxiliary files |
| 222 |
explicitly. Instead it relies on \TeX{} to close all open files at the end. |
| 223 |
|
| 224 |
This procedure ensures that the auxiliary files are only written to within |
| 225 |
\Macro{end}\PParameter{document}, but they remain open throughout the entire |
| 226 |
\LaTeX{} run. \Package{scrwfile} takes is starting point here, by redefining |
| 227 |
\Macro{@starttoc} and \Macro{@writefile}. |
| 228 |
|
| 229 |
Of course\textnote{Attention!} changes to the \LaTeX{} kernel always have the |
| 230 |
potential to cause incompatibilities with other packages. Those primarily |
| 231 |
affected may be those which also redefine \Macro{@starttoc} or |
| 232 |
\Macro{@writefile}. In some cases, it may help to change the order the |
| 233 |
packages are loaded. If you encounter such a problem, please contact the |
| 234 |
\KOMAScript{} author. |
| 235 |
|
| 236 |
\section{The Single-File Method} |
| 237 |
\seclabel{singlefilefeature} |
| 238 |
|
| 239 |
As soon as the package is loaded with |
| 240 |
\begin{lstcode} |
| 241 |
\usepackage{scrwfile} |
| 242 |
\end{lstcode} |
| 243 |
\Package{scrwfile} redefines \Macro{@starttoc}\IndexCmd{@starttoc} so that it |
| 244 |
no longer allocates a write handle or opens a file for writing. |
| 245 |
\Macro{@writefile} is redefined so that immediately before closing the |
| 246 |
\File{aux} file in \Macro{end}\PParameter{document}, it writes not to the |
| 247 |
usual auxiliary files but to a single new file with extension \File{wrt}. |
| 248 |
After reading the \File{aux} file, this \File{wrt} file will be processed once |
| 249 |
for each of the auxiliary files that \Macro{@writefile} writes information to. |
| 250 |
However these auxiliary files do not all have to be open at the same time. |
| 251 |
Instead, only one is open at a time and is explicitly closed afterwards. Since |
| 252 |
\LaTeX{} reuses an internal write file, \Package{scrwfile} doesn't need its |
| 253 |
own write handle for this type of table of contents or list of floating |
| 254 |
environments. |
| 255 |
|
| 256 |
Because of this behaviour, even if you have only one table of contents, once |
| 257 |
you load \Package{scrwfile} you will have access to a write file handle for |
| 258 |
bibliographies, indexes, glossaries, and similar lists that do not use |
| 259 |
\Macro{@starttoc}. Additionally, you can create any number of tables of |
| 260 |
contents and other lists that use \Macro{@starttoc}\IndexCmd{@starttoc}. |
| 261 |
|
| 262 |
\section{The File Cloning Method} |
| 263 |
\seclabel{clonefilefeature} |
| 264 |
|
| 265 |
Since \Macro{@writefile}\IndexCmd{@writefile} has already been modified for |
| 266 |
the single-file method described in the previous system so that it no longer |
| 267 |
writes directly to the corresponding auxiliary file, a further possibility |
| 268 |
suggests itself. When copying the \Macro{@writefile} statements into the |
| 269 |
\File{wrt} file, you can also copy them to other destinations. It should be |
| 270 |
explicitly noted that this only works in the document preamble. |
| 271 |
|
| 272 |
%\iffalse^^A |
| 273 |
\begin{Declaration} |
| 274 |
\Macro{TOCclone}% |
| 275 |
\OParameter{list heading}\Parameter{source extension}% |
| 276 |
\Parameter{destination extension} |
| 277 |
\end{Declaration} |
| 278 |
%\fi^^A |
| 279 |
% \medskip |
| 280 |
% \noindent\DescribeCommand{\TOCclone}\hspace*{-\marginparsep}^^A |
| 281 |
% \oarg{list heading}\marg{source extension}\marg{destination extension}^^A |
| 282 |
% \hfil\\ |
| 283 |
%\iffalse^^A |
| 284 |
%\fi^^A |
| 285 |
This cloning of file entries copies entire tables of contents or other lists. |
| 286 |
For this, you only need to specify the extension of the auxiliary file whose |
| 287 |
entries should be copied and the extension of a destination file. The entries |
| 288 |
are then copied there. Of course, you can also write additional entries to |
| 289 |
this cloned file. |
| 290 |
|
| 291 |
You can manage the \PName{destination extention} using |
| 292 |
\hyperref[cha:tocbasic]{\Package{tocbasic}}% |
| 293 |
\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}}%^^A |
| 294 |
%\iffalse^^A |
| 295 |
\ (see \autoref{cha:tocbasic})% |
| 296 |
%\fi^^A |
| 297 |
\unskip. If such a file is already under the control of |
| 298 |
\hyperref[cha:tocbasic]{\Package{tocbasic}}, a warning will be issued. |
| 299 |
Otherwise, a new list for this extension will be created using |
| 300 |
\hyperref[cha:tocbasic]{\Package{tocbasic}}. You can set the heading for this |
| 301 |
list with the optional argument \PName{list heading}. |
| 302 |
|
| 303 |
% \DescribeCommand[noindex]{\listof\meta{destination extension}}^^A |
| 304 |
% \SpecialCommandIndex{\listof...}^^A |
| 305 |
You can then output this new content list, for example, with the command |
| 306 |
\Macro{listof\PName{destination extension}}. The content-list |
| 307 |
attributes\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} |
| 308 |
\PValue{leveldown}, \PValue{numbered}, \PValue{onecolumn}, and \PValue{totoc} |
| 309 |
%\iffalse |
| 310 |
(see \DescRef{tocbasic.cmd.setuptoc} in \autoref{sec:tocbasic.toc}, |
| 311 |
\DescPageRef{tocbasic.cmd.setuptoc}) |
| 312 |
%\fi |
| 313 |
% (see \cs{setuptoc} in the \pkg{tocbasic} chapter of the \KOMAScript{} |
| 314 |
% manual) |
| 315 |
are automatically copied to the destination list if they were already set in |
| 316 |
the source list. The \PValue{nobabel} attribute is always set for cloned |
| 317 |
content lists, because the language-selection commands in the source content |
| 318 |
list are already copied anyway. |
| 319 |
|
| 320 |
\begin{Example} |
| 321 |
Suppose you want a short table of contents with only the chapter level in |
| 322 |
addition to the normal the table of contents: |
| 323 |
\begin{lstcode} |
| 324 |
\usepackage{scrwfile} |
| 325 |
\TOCclone[Summary Contents]{toc}{stoc} |
| 326 |
\end{lstcode} |
| 327 |
This creates a new table of contents with the heading ``Summary Contents''. |
| 328 |
The new table of contents uses an auxiliary file with the extension |
| 329 |
\File{stoc}. All entries to the auxiliary file with extension \File{toc} |
| 330 |
will also be copied to this new auxiliary file. |
| 331 |
|
| 332 |
In order to have the new short table of contents display only the chapter |
| 333 |
entries, we use: |
| 334 |
\begin{lstcode} |
| 335 |
\addtocontents{stoc}{\protect\value{tocdepth}=0} |
| 336 |
\end{lstcode} |
| 337 |
Although\textnote{Attention!} normally you cannot write to an auxiliary file |
| 338 |
before \Macro{begin}\PParameter{document}, the code above works in the |
| 339 |
preamble after loading \Package{scrwfile}. Owing to the unconventional way |
| 340 |
of changing the |
| 341 |
%\iffalse^^A |
| 342 |
\DescRef{maincls.counter.tocdepth} |
| 343 |
%\fi^^A |
| 344 |
% \cnt{tocdepth} |
| 345 |
counter within the TOC file, this change only applies to this content list. |
| 346 |
|
| 347 |
Later in the document, we then output the content list with the file |
| 348 |
extension \File{stoc} with: |
| 349 |
\begin{lstcode}[moretexcs={listofstoc}] |
| 350 |
\listofstoc |
| 351 |
\end{lstcode} |
| 352 |
and this shows only the parts and chapters of the document. |
| 353 |
|
| 354 |
Things become a bit more difficult if the summary contents are to be |
| 355 |
listed in the table of contents. This would seem to be possible with |
| 356 |
\begin{lstcode} |
| 357 |
\addtocontents{toc}{% |
| 358 |
\protect\addxcontentsline |
| 359 |
{stoc}{chapter}{\protect\contentsname}% |
| 360 |
} |
| 361 |
\end{lstcode} |
| 362 |
However, since all entries in \File{toc} are also copied to \File{stoc}, this |
| 363 |
entry would also be copied from the summary contents. So we cannot generate |
| 364 |
the entry from the content list. Because we use the |
| 365 |
\Package{tocbasic}\important{\Package{tocbasic}} package, we can use the |
| 366 |
following: |
| 367 |
%\iffalse^^A |
| 368 |
\phantomsection\xmpllabel{cmd.BeforeStartingTOC} |
| 369 |
%\fi^^A |
| 370 |
\begin{lstcode} |
| 371 |
\BeforeStartingTOC[toc]{% |
| 372 |
\addcontentslinedefault{stoc}{chapter} |
| 373 |
{\protect\contentsname}% |
| 374 |
} |
| 375 |
\end{lstcode} |
| 376 |
Of course, this assumes that the \File{toc} file is under the control |
| 377 |
of the \Package{tocbasic} package, which is indeed the case for all |
| 378 |
\KOMAScript{} classes. See |
| 379 |
%\iffalse^^A |
| 380 |
\autoref{sec:tocbasic.toc} on\DescPageRef{tocbasic.cmd.BeforeStartingTOC} |
| 381 |
for more information about \DescRef{tocbasic.cmd.BeforeStartingTOC}.% |
| 382 |
%\fi^^A |
| 383 |
% the \pkg{tocbasic} chapter of the \KOMAScript{} manual for more |
| 384 |
% information about \cs{BeforeStartingTOC}.^^A |
| 385 |
\end{Example} |
| 386 |
Incidentally, the |
| 387 |
%\iffalse^^A |
| 388 |
\DescRef{tocbasic.cmd.addxcontentsline} |
| 389 |
%\fi^^A |
| 390 |
% \cs{addxcontentsline} |
| 391 |
command used in the examples is also documented in |
| 392 |
%\iffalse^^A |
| 393 |
\autoref{cha:tocbasic}, \DescPageRef{tocbasic.cmd.addxcontentsline}.% |
| 394 |
%\fi^^A |
| 395 |
% the \pkg{tocbasic} chapter of the \KOMAScript{} manual.%^^A |
| 396 |
%\iffalse^^A |
| 397 |
\EndIndexGroup |
| 398 |
\ExampleEndFix |
| 399 |
%\fi^^A |
| 400 |
|
| 401 |
|
| 402 |
\section{Note on the State of Development} |
| 403 |
\seclabel{draft} |
| 404 |
|
| 405 |
Although this package has already been tested by many users and is often in |
| 406 |
production use, its development is still ongoing. Therefore, it is |
| 407 |
theoretically possible that there might be changes, especially to the internal |
| 408 |
functionality. It is likely that the package will be extended in the future. |
| 409 |
Some code for such extensions is already in the package. However, as there are |
| 410 |
no user commands that make use of these features, they are currently |
| 411 |
undocumented. |
| 412 |
|
| 413 |
\section{Known Package Incompatibilities} |
| 414 |
\seclabel{incompatible} |
| 415 |
|
| 416 |
As mentioned in |
| 417 |
%\iffalse^^A |
| 418 |
\autoref{sec:scrwfile.kernelpatches}, |
| 419 |
%\fi^^A |
| 420 |
% \autoref{sec-\languagename:scrwfile.kernelpatches} |
| 421 |
\Package{scrwfile} redefines some commands of the \LaTeX{} kernel. This |
| 422 |
happens not only while loading the package, but indeed at various times while |
| 423 |
the document is processed, for example just before reading the \File{aux} |
| 424 |
file. This\textnote{Attention!} results in incompatibility with packages that |
| 425 |
also redefine these commands at run time. |
| 426 |
|
| 427 |
The \Package{titletoc}%^^A |
| 428 |
%\iffalse^^A |
| 429 |
\important{Package{titletoc}}\IndexPackage{titletoc} |
| 430 |
%\fi^^A |
| 431 |
package is an example for such an incompatibility. That package redefines |
| 432 |
\Macro{@writefile} under some conditions at run time. If you use both |
| 433 |
\Package{scrwfile} and \Package{titletoc}, there is no warranty for the |
| 434 |
correct behaviour of either one. This is neither an error of |
| 435 |
\Package{titletoc} nor of \Package{scrwfile}.% |
| 436 |
%\iffalse^^A |
| 437 |
%</docen> |
| 438 |
%\fi^^A |
| 439 |
% |
| 440 |
% \selectlanguage{ngerman} |
| 441 |
% \part{Deutsche Benutzeranleitung} |
| 442 |
% |
| 443 |
% \noindent\textbf{Dies ist ein experimentelles Paket. Die Verwendung dieses |
| 444 |
% Pakets erfolgt auf eigene Gefahr. Es gibt keine Unterstützung, wenn Sie |
| 445 |
% dieses Paket verwenden. Das gilt nicht nur für dieses Paket, sondern auch |
| 446 |
% für die Klasse, die Sie verwenden, oder andere Pakete, die \cs{@starttoc} |
| 447 |
% oder \cs{@writefile} verwenden, beispielsweise \pkg{caption}, \pkg{float}, |
| 448 |
% \pkg{tocbasic}, \pkg{listings} und viele weitere.} |
| 449 |
% |
| 450 |
% \section{Hintergrund} |
| 451 |
%\iffalse |
| 452 |
%<*docde> |
| 453 |
%\fi |
| 454 |
% |
| 455 |
Eines der Probleme, die auch durch die Einführung von \eTeX{} nicht gelöst |
| 456 |
wurden, ist die Tatsache, dass \TeX{} nur 18 Dateien gleichzeitig zum Schreiben |
| 457 |
geöffnet haben kann. Diese Zahl erscheint zunächst recht groß. Allerdings ist |
| 458 |
zu berücksichtigen, dass bereits \LaTeX{} selbst einige dieser Dateien |
| 459 |
belegt. Inhaltsverzeichnis, Tabellenverzeichnis, Abbildungsverzeichnis, Index, |
| 460 |
Glossar und jedes weitere Verzeichnis, das von \LaTeX{} aus erzeugt wird, |
| 461 |
belegt in der Regel eine weitere Datei. Dazu kommen Hilfsdateien von Paketen |
| 462 |
wie \Package{hyperref} oder \Package{minitoc}. |
| 463 |
|
| 464 |
Im Endeffekt kann es daher geschehen, dass irgendwann die Meldung |
| 465 |
\begin{lstoutput} |
| 466 |
! No room for a new \write . |
| 467 |
\ch@ck ...\else \errmessage {No room for a new #3} |
| 468 |
\fi |
| 469 |
\end{lstoutput} |
| 470 |
erscheint. Seit einiger Zeit ist die einfachste Lösung dieses Problems die |
| 471 |
Verwendung von \LuaLaTeX{} anstelle von PDF\LaTeX{} oder \XeLaTeX. Damit |
| 472 |
entfällt die Beschränkung und die maximale Anzahl der gleichzeitig zum |
| 473 |
Schreiben geöffneten Dateien wird nur noch durch das Betriebssystem |
| 474 |
bestimmt. In der Realität braucht man sich darüber dann normalerweise keine |
| 475 |
Gedanken mehr zu machen. |
| 476 |
|
| 477 |
Dass \LaTeX{} bei Verzeichnissen wie dem Inhaltsverzeichnis, dem |
| 478 |
Tabellenverzeichnis und dem Abbildungsverzeichnis immer sofort eine neue Datei |
| 479 |
zum Schreiben öffnet, hat aber auch noch einen weiteren Nachteil. Solche |
| 480 |
Verzeichnisse werden durch deren Befehle nicht nur direkt gesetzt, sie können |
| 481 |
auch kein weiteres Mal gesetzt werden, da die zugehörige Hilfsdatei nach dem |
| 482 |
jeweiligen Befehl bis zum Ende des Dokuments leer ist. |
| 483 |
|
| 484 |
Das Paket \Package{scrwfile} bietet hier eine grundsätzliche Änderung im |
| 485 |
\LaTeX-Kern, durch die beide Probleme nicht nur für \LuaLaTeX{} sondern auch |
| 486 |
bei Verwendung von PDF\LaTeX{} oder \XeLaTeX{} gelöst werden können. |
| 487 |
|
| 488 |
|
| 489 |
\section{Grundsätzliche Änderungen am \LaTeX-Kern} |
| 490 |
\seclabel{kernelpatches} |
| 491 |
|
| 492 |
\LaTeX-Klassen verwenden zum Öffnen eines Verzeichnisses, beispielsweise mit |
| 493 |
\Macro{tableofcontents} oder \Macro{listoffigures}, die \LaTeX-Kern-Anweisung |
| 494 |
\Macro{@starttoc}\IndexCmd{@starttoc}. \LaTeX{} selbst lädt bei dieser |
| 495 |
Anweisung nicht nur die zugehörige Hilfsdatei, sondern öffnet diese Hilfsdatei |
| 496 |
auch neu zum Schreiben. Werden anschließend mit \Macro{addtocontents} oder |
| 497 |
\Macro{addcontentsline} Einträge in dieses Verzeichnis vorgenommen, so wird |
| 498 |
jedoch nicht direkt in die geöffnete Hilfsdatei geschrieben. Stattdessen |
| 499 |
schreibt \LaTeX{} \Macro{@writefile}-Anweisungen\IndexCmd{@writefile} in die |
| 500 |
\File{aux}-Datei. Erst beim Einlesen der \File{aux}-Dateien am Ende des |
| 501 |
Dokuments wird dann über diese \Macro{@writefile}-Anweisungen in die |
| 502 |
tatsächlichen Hilfsdateien geschrieben. Die Hilfsdateien werden von \LaTeX{} |
| 503 |
auch nicht explizit geschlossen. Stattdessen verlässt sich \LaTeX{} hier |
| 504 |
darauf, dass \TeX{} die Dateien am Ende ohnehin schließt. |
| 505 |
|
| 506 |
Dieses Vorgehen sorgt dafür, dass die Hilfsdateien zwar erst innerhalb von |
| 507 |
\Macro{end}\PParameter{document} tatsächlich beschrieben werden, aber trotzdem |
| 508 |
während des gesamten \LaTeX-Laufs gleichzeitig offen sind. \Package{scrwfile} |
| 509 |
hat nun genau hier einen Ansatzpunkt: die Umdefinierung von \Macro{@starttoc} |
| 510 |
und \Macro{@writefile}. |
| 511 |
|
| 512 |
Natürlich\textnote{Achtung!} besitzen Änderungen am \LaTeX-Kern immer das |
| 513 |
Potential, dass es zu Unverträglichkeiten mit anderen Paketen kommen |
| 514 |
kann. Betroffen können in erster Linie Pakete sein, die ebenfalls |
| 515 |
\Macro{@starttoc} oder \Macro{@writefile} umdefinieren. In einigen Fällen kann |
| 516 |
es helfen, die Reihenfolge der Pakete zu ändern.% |
| 517 |
\iffalse % Umbruchkorrektur |
| 518 |
\ Wenn Sie auf ein solches Problem stoßen, sollten Sie sich an den |
| 519 |
\KOMAScript-Autor wenden.5 |
| 520 |
\fi |
| 521 |
|
| 522 |
\section{Das Eindateiensystem} |
| 523 |
\seclabel{singlefilefeature} |
| 524 |
|
| 525 |
Bereits beim Laden des Pakets mit |
| 526 |
% Umbruchoptimierung: listings |
| 527 |
\begin{lstcode} |
| 528 |
\usepackage{scrwfile} |
| 529 |
\end{lstcode} |
| 530 |
wird \Macro{@starttoc}\IndexCmd{@starttoc} von \Package{scrwfile} so |
| 531 |
umdefiniert, dass davon selbst keine Datei mehr zum Schreiben angefordert und |
| 532 |
geöffnet wird. Unmittelbar vor dem Schließen der \File{aux}-Datei in |
| 533 |
\Macro{end}\PParameter{document} wird dann \Macro{@writefile} so umdefiniert, |
| 534 |
dass diese Anweisung statt in die eigentlichen Hilfsdateien in eine neue |
| 535 |
Hilfsdatei mit der Endung \File{wrt} schreibt. Nach dem Einlesen der |
| 536 |
\File{aux}-Dateien wird schließlich die \File{wrt}-Datei abgearbeitet und zwar |
| 537 |
ein Mal für jede der Hilfsdateien, in die mit \Macro{@writefile} geschrieben |
| 538 |
wird. Dabei muss aber nicht jede dieser Hilfsdateien gleichzeitig |
| 539 |
geöffnet sein. Stattdessen ist immer nur eine zum Schreiben geöffnet und wird |
| 540 |
auch wieder explizit geschlossen. Da dabei eine interne Schreibdatei von |
| 541 |
\LaTeX{} wiederverwendet wird, benötigt \Package{scrwfile} keine einzige |
| 542 |
eigene Schreibdatei für diese Art von Verzeichnissen. |
| 543 |
|
| 544 |
Selbst wenn bisher nur mit einem Inhaltsverzeichnis gearbeitet wird, steht |
| 545 |
nach dem Laden des Pakets bereits eine Schreibdatei mehr für |
| 546 |
Literaturverzeichnisse, Stichwortverzeichnisse, Glossare und ähnliche |
| 547 |
Verzeichnisse, die nicht mit \Macro{@starttoc} arbeiten, zur |
| 548 |
Verfügung. Darüber hinaus können beliebig viele Verzeichnisse, die mit |
| 549 |
\Macro{@starttoc}\IndexCmd{@starttoc} arbeiten, angelegt werden. |
| 550 |
|
| 551 |
|
| 552 |
\section{Das Klonen von Dateieinträgen} |
| 553 |
\seclabel{clonefilefeature} |
| 554 |
|
| 555 |
Nachdem \Macro{@writefile}\IndexCmd{@writefile} für das Eindateiensystem aus |
| 556 |
dem vorherigen Abschnitt bereits so geändert wurde, dass es nicht direkt in |
| 557 |
die entsprechende Hilfsdatei schreibt, lag eine weitere Idee nahe. Beim |
| 558 |
Kopieren der \Macro{@writefile}-Anweisungen in die \File{wrt}-Datei können |
| 559 |
diese auch für andere Zielendungen übernommen werden. Es sei ausdrücklich |
| 560 |
darauf hingewiesen, dass dies nur in der Dokumentpräambel funktioniert. |
| 561 |
|
| 562 |
%\iffalse^^A |
| 563 |
\begin{Declaration} |
| 564 |
\Macro{TOCclone}\OParameter{Verzeichnisüberschrift} |
| 565 |
\Parameter{Quellendung}\Parameter{Zielendung} |
| 566 |
\Macro{listof\PName{Zielendung}} |
| 567 |
\end{Declaration}% |
| 568 |
%\fi^^A |
| 569 |
% \medskip |
| 570 |
% \noindent\DescribeCommand{\TOCclone}\hspace*{-\marginparsep}^^A |
| 571 |
% \oarg{Verzeichnisüberschrift}\marg{Quellendung}\marg{Zielendung}^^A |
| 572 |
% \hfill\\ |
| 573 |
Durch dieses Klonen von Dateieinträgen werden so ganze Verzeichnisse |
| 574 |
geklont. Dazu muss man nur die Endung der Hilfsdatei des Verzeichnisses |
| 575 |
kennen, dessen Einträge kopiert werden sollen. Zusätzlich muss man die Endung |
| 576 |
einer Zieldatei angeben. In diese werden die Einträge dann kopiert. Natürlich |
| 577 |
kann man in dieses geklonte Verzeichnis auch zusätzliche Einträge |
| 578 |
schreiben. |
| 579 |
|
| 580 |
Die \PName{Zielendung} der Zieldatei wird mit Hilfe von |
| 581 |
\hyperref[cha:tocbasic]{\Package{tocbasic}}% |
| 582 |
\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} |
| 583 |
%\iffalse^^A |
| 584 |
(siehe \autoref{cha:tocbasic}) |
| 585 |
%\fi^^A |
| 586 |
verwaltet. Steht eine solche Datei bereits unter |
| 587 |
Kontrolle von \hyperref[cha:tocbasic]{\Package{tocbasic}} wird eine Warnung |
| 588 |
ausgegeben. Anderenfalls wird mit Hilfe von |
| 589 |
\hyperref[cha:tocbasic]{\Package{tocbasic}} ein neues Verzeichnis für diese |
| 590 |
Endung angelegt. Die Überschrift des neuen Verzeichnisses kann man über das |
| 591 |
optionale Argument \PName{Verzeichnisüberschrift} bestimmen. |
| 592 |
|
| 593 |
% \DescribeCommand[noindex]{\listof\meta{Zielendung}}^^A |
| 594 |
% \SpecialCommandIndex{\listof...}^^A |
| 595 |
Ausgeben kann man dieses neue Verzeichnis dann beispielsweise über die |
| 596 |
Anweisung \Macro{listof\PName{Zielendung}}. Die |
| 597 |
Verzeichniseigenschaften\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} |
| 598 |
\PValue{leveldown}, \PValue{numbered}, \PValue{onecolumn} und \PValue{totoc} |
| 599 |
%\iffalse |
| 600 |
(siehe Anweisung \DescRef{tocbasic.cmd.setuptoc} in |
| 601 |
\autoref{sec:tocbasic.toc}, \DescPageRef{tocbasic.cmd.setuptoc}) |
| 602 |
%\fi |
| 603 |
% (siehe \cs{setuptoc} im Kapitel to \pkg{tocbasic} in the \KOMAScript-Anleitung) |
| 604 |
werden automatisch in das Zielverzeichnis übernommen, falls sie für das |
| 605 |
Quellverzeichnis bereits gesetzt waren. Die Eigenschaft \PValue{nobabel} wird |
| 606 |
für geklonte Verzeichnisse immer gesetzt, da die entsprechenden |
| 607 |
\Package{babel}-Einträge in das Quellverzeichnis ohnehin bereits kopiert |
| 608 |
werden. |
| 609 |
|
| 610 |
\begin{Example} |
| 611 |
Angenommen, Sie wollen zusätzlich zum normalen Inhaltsverzeichnis eine |
| 612 |
Gliederungsübersicht, in der nur die Kapitel angezeigt werden. |
| 613 |
\begin{lstcode} |
| 614 |
\usepackage{scrwfile} |
| 615 |
\TOCclone[Gliederungsübersicht]{toc}{stoc} |
| 616 |
\end{lstcode} |
| 617 |
Hierdurch wird zunächst ein neues Verzeichnis mit der Überschrift |
| 618 |
»Gliederungsübersicht« angelegt. Das neue Verzeichnis verwendet die |
| 619 |
Dateiendung \File{stoc}. Alle Einträge in die Datei mit der Endung |
| 620 |
\File{toc} werden auch in dieses Verzeichnis kopiert. |
| 621 |
|
| 622 |
Damit dieses neue Verzeichnis nun nur die Kapitelebene ausgibt, verwenden |
| 623 |
wir: |
| 624 |
\begin{lstcode} |
| 625 |
\addtocontents{stoc}{\protect\value{tocdepth}=0} |
| 626 |
\end{lstcode} |
| 627 |
Während\textnote{Achtung!} normalerweise erst ab |
| 628 |
\Macro{begin}\PParameter{document} Einträge in ein Verzeichnis vorgenommen |
| 629 |
werden können, funktioniert dies nach Laden von \Package{scrwfile} bereits |
| 630 |
in der Dokumentpräambel. Durch die hier gezeigte unkonventionelle Art, den |
| 631 |
Zähler |
| 632 |
%\iffalse^^A |
| 633 |
\DescRef{maincls.counter.tocdepth} |
| 634 |
%\fi^^A |
| 635 |
% \cnt{tocdepth} |
| 636 |
innerhalb der Verzeichnisdatei zu ändern, bleibt diese Änderung nur für |
| 637 |
dieses Verzeichnis wirksam. |
| 638 |
|
| 639 |
Später im Dokument wird das Verzeichnis mit der Endung \File{stoc} dann |
| 640 |
durch |
| 641 |
\begin{lstcode}[moretexcs={listofstoc}] |
| 642 |
\listofstoc |
| 643 |
\end{lstcode} |
| 644 |
ausgegeben und zeigt nur die Teile und Kapitel des Dokuments. |
| 645 |
|
| 646 |
Etwas schwieriger wird es, wenn das Inhaltsverzeichnis in der |
| 647 |
Gliederungsübersicht angezeigt werden soll. Dies wäre zwar mit |
| 648 |
\begin{lstcode} |
| 649 |
\addtocontents{toc}{% |
| 650 |
\protect\addxcontentsline |
| 651 |
{stoc}{chapter}{\protect\contentsname}% |
| 652 |
} |
| 653 |
\end{lstcode} |
| 654 |
möglich. Da jedoch alle Einträge in \File{toc} auch nach \File{stoc} kopiert |
| 655 |
werden, würde so von der Gliederungsübersicht dieser Eintrag ebenfalls |
| 656 |
übernommen. Also darf der Eintrag nicht aus der Verzeichnisdatei heraus |
| 657 |
erzeugt werden. Da das Paket \hyperref[cha:tocbasic]{\Package{tocbasic}}% |
| 658 |
\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} zum Einsatz kommt, |
| 659 |
kann aber%^^A |
| 660 |
%\iffalse^^A |
| 661 |
\phantomsection\xmpllabel{cmd.BeforeStartingTOC}% |
| 662 |
%\fi^^A |
| 663 |
\begin{lstcode} |
| 664 |
\BeforeStartingTOC[toc]{% |
| 665 |
\addxcontentsline{stoc}{chapter} |
| 666 |
{\protect\contentsname}} |
| 667 |
\end{lstcode} |
| 668 |
verwendet werden. Natürlich\textnote{Achtung!} setzt dies voraus, dass die |
| 669 |
Datei mit Endung \File{toc} auch unter der Kontrolle von |
| 670 |
\hyperref[cha:tocbasic]{\Package{tocbasic}} steht. Dies ist bei allen |
| 671 |
\KOMAScript-Klassen der Fall. Näheres zur Anweisung |
| 672 |
%\iffalse^^A |
| 673 |
\DescRef{tocbasic.cmd.BeforeStartingTOC} ist in \autoref{sec:tocbasic.toc} |
| 674 |
auf \DescPageRef{tocbasic.cmd.BeforeStartingTOC} |
| 675 |
%\fi^^A |
| 676 |
% \cs{BeforeStartingTOC} im Kapitel zu \pkg{tocbasic} in der |
| 677 |
% \KOMAScript-Anleitung |
| 678 |
zu finden. Die Erklärung zu |
| 679 |
%\iffalse^^A |
| 680 |
\DescRef{tocbasic.cmd.addxcontentsline} findet sich in demselben Abschnitt |
| 681 |
auf \DescPageRef{tocbasic.cmd.addxcontentsline}.% |
| 682 |
%\fi^^A |
| 683 |
% \cs{addxcontentsline} findet sich dort ebenfalls.%^^A |
| 684 |
\end{Example}% |
| 685 |
%\iffalse^^A |
| 686 |
\EndIndexGroup% |
| 687 |
\ExampleEndFix |
| 688 |
%\fi^^A |
| 689 |
|
| 690 |
|
| 691 |
\section{Hinweis zum Entwicklungsstand} |
| 692 |
\seclabel{draft} |
| 693 |
|
| 694 |
Obwohl das Paket bereits von mehreren Anwendern getestet wurde und vielfach im |
| 695 |
Einsatz ist, ist es vom Autor als experimentell eingestuft. Deshalb ist es |
| 696 |
theoretisch möglich, dass insbesondere an der internen Funktionsweise des |
| 697 |
Pakets noch Änderungen vorgenommen werden. Teilweise befindet sich auch Code |
| 698 |
für zusätzliche Erweiterungen im Paket. Da jedoch keine Benutzeranweisungen |
| 699 |
existieren, mit denen diese Möglichkeiten genutzt werden könnten, wurde auf |
| 700 |
eine Dokumentation derselben verzichtet. |
| 701 |
|
| 702 |
|
| 703 |
\section{Bekannte Paketunverträglichkeiten} |
| 704 |
\seclabel{incompatible} |
| 705 |
|
| 706 |
Wie in |
| 707 |
%\iffalse^^A |
| 708 |
\autoref{sec:scrwfile.kernelpatches} |
| 709 |
% \fi^^A |
| 710 |
% \autoref{sec-\languagename:scrwfile.kernelpatches} |
| 711 |
bereits erwähnt, muss \Package{scrwfile} einige wenige Anweisungen des |
| 712 |
\LaTeX-Kerns umdefinieren. Dies geschieht nicht allein während des Ladens des |
| 713 |
Pakets, sondern vielmehr zu verschiedenen Zeitpunkten während der Abarbeitung |
| 714 |
eines Dokuments, beispielsweise vor dem Einlesen der |
| 715 |
\File{aux}-Datei. Das\textnote{Achtung!} führt dazu, dass \Package{scrwfile} |
| 716 |
sich nicht mit anderen Paketen verträgt, die dieselben Anweisungen ebenfalls |
| 717 |
zur Laufzeit umdefinieren. |
| 718 |
|
| 719 |
Ein Beispiel für eine solche Unverträglichkeit ist |
| 720 |
\Package{titletoc}%^^A |
| 721 |
%\iffalse^^A |
| 722 |
\important{\Package{titletoc}}\IndexPackage{titletoc}%^^A |
| 723 |
%\fi^^A |
| 724 |
\unskip. Das Paket definiert unter gewissen Umständen \Macro{@writefile} zur |
| 725 |
Laufzeit um. Werden \Package{scrwfile} und \Package{titletoc} zusammen |
| 726 |
verwendet, ist die Funktion beider Paket nicht mehr gewährleistet. Dies ist |
| 727 |
weder ein Fehler in \Package{titletoc} noch in \Package{scrwfile}.% |
| 728 |
%\iffalse^^A |
| 729 |
%</docde> |
| 730 |
%\fi^^A |
| 731 |
% |
| 732 |
% \selectlanguage{USenglish} |
| 733 |
% |
| 734 |
% \MaybeStop{\PrintIndex} |
| 735 |
% |
| 736 |
% \part{Implementation of \pkg{scrwfile}} |
| 737 |
% |
| 738 |
% \begin{macrocode} |
| 739 |
%<*package> |
| 740 |
% \end{macrocode} |
| 741 |
% |
| 742 |
% \begin{macrocode} |
| 743 |
\PackageWarningNoLine{scrwfile}{% |
| 744 |
THIS IS AN EXPERIMENTAL PACKAGE!\MessageBreak |
| 745 |
USAGE OF THIS PACKAGE IS ON YOUR OWN RISK!\MessageBreak |
| 746 |
EVERYTHING MAY HAPPEN!\MessageBreak |
| 747 |
EVERYTHING MAY CHANGE IN FUTURE!\MessageBreak |
| 748 |
THERE IS NO SUPPORT, IF YOU USE THIS PACKAGE!\MessageBreak |
| 749 |
Maybe, it would be better not to load this package% |
| 750 |
} |
| 751 |
% \end{macrocode} |
| 752 |
% |
| 753 |
% \section{Options} |
| 754 |
% Currently we don't need options. |
| 755 |
% |
| 756 |
% \section{Body} |
| 757 |
% |
| 758 |
% \subsection{Needed Packages} |
| 759 |
% |
| 760 |
% Package \pkg*{scrbase} is needed, because of using several \KOMAScript{} |
| 761 |
% basic commands. |
| 762 |
% \changes{v0.1.12}{2023/03/31}{required version of \pkg{scrbase} fixed} |
| 763 |
% \begin{macrocode} |
| 764 |
\RequirePackage{scrbase}[2015/08/29] |
| 765 |
% \end{macrocode} |
| 766 |
% |
| 767 |
% Package \pkg*{scrlfile} is needed because of the \file{aux}-file |
| 768 |
% handling and \cs{protected@immediate@write}. |
| 769 |
% \begin{macrocode} |
| 770 |
\RequirePackage{scrlfile}[2010/09/30] |
| 771 |
% \end{macrocode} |
| 772 |
% |
| 773 |
% \changes{v0.1.10}{2022/02/04}{\pkg{iftex} is required} |
| 774 |
% Package \pkg{iftex} is used to detect Lua\LaTeX. |
| 775 |
% \begin{macrocode} |
| 776 |
\RequirePackage{iftex} |
| 777 |
% \end{macrocode} |
| 778 |
% |
| 779 |
% \subsection{Is is needed?} |
| 780 |
% |
| 781 |
% \changes{v0.1.9}{2021/05/30}{with Lua\LaTeX{} using is not recommended} |
| 782 |
% \changes{v0.1.10}{2022/02/04}{using \cs{ifluatex}} |
| 783 |
% \changes{v0.1.10}{2022/02/04}{\cs{PackageInfoNoLine} replaced by |
| 784 |
% \cs{PackageWarningNoLine}} |
| 785 |
% If the user uses Lua\LaTeX{} usage of \pkg*{scrwfile} should not be |
| 786 |
% needed. |
| 787 |
% \begin{macrocode} |
| 788 |
\ifluatex |
| 789 |
\PackageWarningNoLine{scrwfile}{LuaLaTeX detected.\MessageBreak |
| 790 |
With LuaLaTeX you should never get an error message:\MessageBreak |
| 791 |
\space\space`No room for a new \string\write'.\MessageBreak |
| 792 |
So scrwfile could make much more harm than benefit\MessageBreak |
| 793 |
and using it is not recommended}% |
| 794 |
\fi |
| 795 |
% \end{macrocode} |
| 796 |
% |
| 797 |
% \subsection{\LaTeX{} Kernel Patchs} |
| 798 |
% |
| 799 |
% For some features we need to patch \LaTeX{} kernel macros. Those features |
| 800 |
% and macros are: |
| 801 |
% \begin{description} |
| 802 |
% \item[Single handle feature] means, that \LaTeX{} will no longer need a file |
| 803 |
% handle for every help file, but only one for all files. We will patch |
| 804 |
% \cs{@starttoc} and \cs{@writefile} to do so. |
| 805 |
% \item[Clone file feature] means, that every write to one file may be done to |
| 806 |
% another file, too. We will patch \cs{@writefile} to do so. |
| 807 |
% \end{description} |
| 808 |
% Every patch should be minimum invasive, so that files, that are not under |
| 809 |
% \pkg*{scrwfile}'s control are changed as little as possible. |
| 810 |
% |
| 811 |
% \begin{macro}{\scrwfile@if@only} |
| 812 |
% First of all we check, if the file should be handled by \pkg*{scrwfile}. |
| 813 |
% \begin{macrocode} |
| 814 |
\newcommand*{\scrwfile@if@only}[1]{% |
| 815 |
\begingroup |
| 816 |
\scr@ifundefinedorrelax{scrwfile@only}{\@tempswatrue}{% |
| 817 |
\@tempswafalse |
| 818 |
\edef\reserved@b{#1}% |
| 819 |
\@for\reserved@a:=\scrwfile@only\do |
| 820 |
{\ifx\reserved@a\reserved@b\@tempswatrue\fi}% |
| 821 |
}% |
| 822 |
\if@tempswa |
| 823 |
\scr@ifundefinedorrelax{scrwfile@never}{}{% |
| 824 |
\edef\reserved@b{#1}% |
| 825 |
\@for\reserved@a:=\scrwfile@never\do |
| 826 |
{\ifx\reserved@a\reserved@b\@tempswafalse\fi}% |
| 827 |
}% |
| 828 |
\fi |
| 829 |
\expandafter\endgroup |
| 830 |
\if@tempswa |
| 831 |
\expandafter\@firstoftwo |
| 832 |
\else |
| 833 |
\expandafter\@secondoftwo |
| 834 |
\fi |
| 835 |
} |
| 836 |
% \end{macrocode} |
| 837 |
% \end{macro} |
| 838 |
% |
| 839 |
% \begin{macro}{\scrwfile@starttoc,\scrwfile@@starttoc} |
| 840 |
% This is the internal redefinition of \cs{@starttoc}. First of all test, if it |
| 841 |
% should be used, then use it or not. |
| 842 |
% \begin{macrocode} |
| 843 |
\newcommand*{\scrwfile@starttoc}[1]{% |
| 844 |
\scrwfile@if@only{#1}{\scrwfile@@starttoc}{\scrwfile@saved@starttoc}{#1}% |
| 845 |
} |
| 846 |
\newcommand*{\scrwfile@@starttoc}[1]{% |
| 847 |
%<trace> \PackageInfo{scrwfile}{% |
| 848 |
%<trace> Using my own \string\@starttoc\space for `#1'}% |
| 849 |
\begingroup |
| 850 |
\if@filesw |
| 851 |
\xdef\scrwfile@writefilelist{\scrwfile@writefilelist,#1}% |
| 852 |
\fi |
| 853 |
\@fileswfalse |
| 854 |
\scrwfile@saved@starttoc{#1}% |
| 855 |
\endgroup |
| 856 |
} |
| 857 |
% \end{macrocode} |
| 858 |
% \end{macro} |
| 859 |
% |
| 860 |
% \begin{macro}{\scrwfile@writefile,\scrwfile@@writefile,\scrwfile@wrtout, |
| 861 |
% \scrwfile@writefilelist} |
| 862 |
% This is the internal redefinition of \cs{@writefile}. First of all test, if |
| 863 |
% it should be used, then use it or not. |
| 864 |
% \begin{macrocode} |
| 865 |
\newcommand*{\scrwfile@writefile}[1]{% |
| 866 |
\scrwfile@if@only{#1}{\scrwfile@@writefile}{\scrwfile@saved@writefile}{#1}% |
| 867 |
} |
| 868 |
\newcommand{\scrwfile@@writefile}[2]{% |
| 869 |
%<trace> \PackageInfo{scrwfile}{% |
| 870 |
%<trace> Using my own \string\@writefile\space for `#1'}% |
| 871 |
\ifnum\scrwfile@wrtout>0 |
| 872 |
\begingroup |
| 873 |
\@temptokena{#2}% |
| 874 |
\immediate\write\scrwfile@wrtout{% |
| 875 |
\string\@writefile{#1}{\the\@temptokena}% |
| 876 |
}% |
| 877 |
% \end{macrocode} |
| 878 |
% This was the entry for the real file. But we also may have clone files: |
| 879 |
% \begin{macrocode} |
| 880 |
\scrwfile@process@clones{#1}% |
| 881 |
\endgroup |
| 882 |
\fi |
| 883 |
} |
| 884 |
\chardef\scrwfile@wrtout\z@ |
| 885 |
\newcommand*{\scrwfile@writefilelist}{} |
| 886 |
% \end{macrocode} |
| 887 |
% \end{macro} |
| 888 |
% |
| 889 |
% \begin{macro}{\@writefile,\scrwfile@saved@writefile} |
| 890 |
% We have to add the single handle feature and the clone file feature to |
| 891 |
% \cs{@writefile} and therefore save the original |
| 892 |
% definition. \cs{scrwfile@saved@writefile} is used, whenever a file is not |
| 893 |
% under \pkg*{scrwfile}'s control. |
| 894 |
% \begin{macrocode} |
| 895 |
\newcommand*{\scrwfile@saved@writefile}{} |
| 896 |
\BeforeClosingMainAux{% |
| 897 |
\ifx\scrwfile@writefilelist\@empty\else |
| 898 |
\let\scrwfile@saved@writefile\@writefile |
| 899 |
\let\scrwfile@wrtout\@partaux |
| 900 |
\immediate\openout\scrwfile@wrtout \jobname.wrt |
| 901 |
\let\@writefile\scrwfile@writefile |
| 902 |
\fi |
| 903 |
} |
| 904 |
\AfterReadingMainAux{% |
| 905 |
\ifx\scrwfile@writefilelist\@empty\else |
| 906 |
\immediate\closeout\scrwfile@wrtout |
| 907 |
\chardef\scrwfile@wrtout\z@ |
| 908 |
\begingroup |
| 909 |
\let\@writefile\scrwfile@saved@writefile |
| 910 |
\@for\@currext:=\scrwfile@writefilelist\do{% |
| 911 |
\begingroup |
| 912 |
\ifx\@currext\@empty\else |
| 913 |
\scr@ifundefinedorrelax{tf@\@currext}{% |
| 914 |
%<trace> \typeout{Process extension: `\@currext'} |
| 915 |
\immediate\openout\@partaux \jobname.\@currext |
| 916 |
\expandafter\let\csname tf@\@currext\endcsname\@partaux |
| 917 |
\@input@{\jobname.wrt}% |
| 918 |
\immediate\closeout\@partaux |
| 919 |
}{}% |
| 920 |
\fi |
| 921 |
\endgroup |
| 922 |
}% |
| 923 |
\endgroup |
| 924 |
\fi |
| 925 |
} |
| 926 |
% \end{macrocode} |
| 927 |
% \changes{v0.1.8}{2021/05/30}{added order rule for |
| 928 |
% \pkg*{scrlayer-notecolumn}} |
| 929 |
% Note: Here we use a \LaTeX{} version test, because a do-nothing-definition |
| 930 |
% like the one of \pkg{latexrelease} wouldn't be correct, if the command is |
| 931 |
% not supported by the current \LaTeX{} kernel version setting. |
| 932 |
% \begin{macrocode} |
| 933 |
\IfLTXAtLeastTF{2020/10/01}{% |
| 934 |
\DeclareHookRule{enddocument/afteraux}% |
| 935 |
{scrwfile}{before}{scrlayer-notecolumn}% |
| 936 |
}{% |
| 937 |
\@ifpackageloaded{scrlayer-notecolumn}{% |
| 938 |
\PackageWarningNoLine{scrwfile}{% |
| 939 |
Dangerous package order detected!\MessageBreak |
| 940 |
As a general rule, you should load scrwfile as soon\MessageBreak |
| 941 |
as possible, maybe even before `\string\documentclass'\MessageBreak |
| 942 |
(using `\string\RequirePackage' instead of |
| 943 |
`\string\usepackage').\MessageBreak |
| 944 |
Following packages should be loaded after scrwfile:\MessageBreak |
| 945 |
\space - scrlayer-notecolumn}% |
| 946 |
}{}% |
| 947 |
} |
| 948 |
% \end{macrocode} |
| 949 |
% \end{macro} |
| 950 |
% |
| 951 |
% \begin{macro}{\@starttoc,\scrwfile@saved@starttoc} |
| 952 |
% We have to add the single handle feature to \cs{@starttoc} and therefore |
| 953 |
% save the original definition. |
| 954 |
% \changes{v0.1.5}{2013/07/24}{take care for outdated \pkg{hyperref}} |
| 955 |
% \changes{v0.1.11}{2022/10/06}{ready for \pkg{hyperref} without |
| 956 |
% \cs{Hy@AtBeginDocumentHook}} |
| 957 |
% \cs{scrwfile@saved@starttoc} is be used, whenever the file is not under |
| 958 |
% \pkg*{scrwfile}'s control. Because of old versions of package |
| 959 |
% \pkg{hyperref}, that do a hard redefinition without any care for changed |
| 960 |
% definitions, we have to take care for that and cannot do a simple |
| 961 |
% \begin{verbatim} |
| 962 |
% \let\scrwfile@saved@starttoc\@starttoc |
| 963 |
% \let\@starttoc\scrwfile@starttoc |
| 964 |
% \end{verbatim} |
| 965 |
% \begin{macrocode} |
| 966 |
\newcommand*{\scrwfile@saved@starttoc}{} |
| 967 |
\AtBeginDocument{% |
| 968 |
\begingroup |
| 969 |
\@ifpackageloaded{hyperref}{% |
| 970 |
\scr@ifundefinedorrelax{Hy@AtBeginDocument}{% |
| 971 |
\PackageInfo{scrwfile}{% |
| 972 |
Using immediate redefinition of `\string\@starttoc'% |
| 973 |
}% |
| 974 |
\aftergroup\@firstofone |
| 975 |
}{% |
| 976 |
\ifx\Hy@AtBeginDocumentHook\@undefined |
| 977 |
\PackageInfo{scrwfile}{% |
| 978 |
Using immediate redefinition of `\string\@starttoc'% |
| 979 |
}% |
| 980 |
\aftergroup\@firstofone |
| 981 |
\else |
| 982 |
% \end{macrocode} |
| 983 |
% From v7.00o \pkg{hyperref} does not redefine \cs{@starttoc} any more. So we |
| 984 |
% do need the usage of \cs{Hy@AtBeginDocument} only for versions before. |
| 985 |
% \begin{macrocode} |
| 986 |
\@ifpackagelater{hyperref}{2022/02/22}{% newer than v7.00n |
| 987 |
\PackageInfo{scrwfile}{% |
| 988 |
Using immediate redefinition of `\string\@starttoc'% |
| 989 |
}% |
| 990 |
\aftergroup\@firstofone |
| 991 |
}{% |
| 992 |
\PackageWarning{scrwfile}{% |
| 993 |
Outdated package `hyperref' detected.\MessageBreak |
| 994 |
Using `\string\Hy@AtBeginDocument' for redefinition of |
| 995 |
`\string\@starttoc'.\MessageBreak |
| 996 |
We recommend to update `hyperref' |
| 997 |
}% |
| 998 |
\aftergroup\Hy@AtBeginDocument |
| 999 |
}% |
| 1000 |
\fi |
| 1001 |
}% |
| 1002 |
}{% |
| 1003 |
\PackageInfo{scrwfile}{% |
| 1004 |
Using immediate redefinition of `\string\@starttoc'% |
| 1005 |
}% |
| 1006 |
\aftergroup\@firstofone |
| 1007 |
}% |
| 1008 |
\endgroup |
| 1009 |
{% |
| 1010 |
\PackageInfo{scrwfile}{% |
| 1011 |
Extending `\string\@starttoc` |
| 1012 |
}% |
| 1013 |
\let\scrwfile@saved@starttoc\@starttoc |
| 1014 |
\let\@starttoc\scrwfile@starttoc |
| 1015 |
}% |
| 1016 |
} |
| 1017 |
% \end{macrocode} |
| 1018 |
% \end{macro} |
| 1019 |
% |
| 1020 |
% |
| 1021 |
% \subsection{Clone TOC Feature} |
| 1022 |
% |
| 1023 |
% \pkg*{scrwfile} may clone a TOC, that means, every entry to one file will |
| 1024 |
% be copied to other files, too. You must not clone recursively! |
| 1025 |
% |
| 1026 |
% \begin{description} |
| 1027 |
% \item[ToDo:]The whole feature should be moved to \pkg*{tocbasic}. But this |
| 1028 |
% would need a complete re-implementation and would result in one more write |
| 1029 |
% handle for every cloned file. So maybe it wouldn't be a really good idea |
| 1030 |
% to do so. |
| 1031 |
% \end{description} |
| 1032 |
% |
| 1033 |
% \begin{macro}{\scrwfile@process@clones} |
| 1034 |
% \begin{macrocode} |
| 1035 |
\newcommand*{\scrwfile@process@clones}[1]{% |
| 1036 |
\scr@ifundefinedorrelax{scrwfile@clone@#1}{}{% |
| 1037 |
\begingroup |
| 1038 |
\let\@@protect\protect\let\protect\@empty\afterassignment\restore@protect |
| 1039 |
\edef\reserved@b{\csname scrwfile@clone@#1\endcsname}% |
| 1040 |
\edef\reserved@c{,#1}% |
| 1041 |
\@for \reserved@a:=\reserved@b\do {% |
| 1042 |
\@tempswatrue |
| 1043 |
\@for \reserved@d:=\reserved@c\do {% |
| 1044 |
\ifx\reserved@d\reserved@a\@tempswafalse\fi |
| 1045 |
}% |
| 1046 |
\if@tempswa |
| 1047 |
%<trace> \typeout{clone entry from `#1' to `\reserved@a'}% |
| 1048 |
\immediate\write\scrwfile@wrtout{% |
| 1049 |
\string\@writefile{\reserved@a}{\the\@temptokena}% |
| 1050 |
}% |
| 1051 |
\edef\reserved@c{\reserved@c,\reserved@a}% |
| 1052 |
\fi |
| 1053 |
}% |
| 1054 |
\endgroup |
| 1055 |
}% |
| 1056 |
}% |
| 1057 |
% \end{macrocode} |
| 1058 |
% \end{macro} |
| 1059 |
% |
| 1060 |
% \begin{command}{\TOCclone} |
| 1061 |
% \changes{v0.1.8}{2019/11/18}{\cs{ifstr} umbenannt in \cs{Ifstr}} |
| 1062 |
% \changes{v0.1.8}{2019/11/19}{\cs{ifattoclist} replaced by \cs{Ifattoclist}} |
| 1063 |
% \changes{v0.1.8}{2019/11/19}{\cs{iftocfeature} replaced by |
| 1064 |
% \cs{Iftocfeature}} |
| 1065 |
% \changes{v0.1.8}{2020/02/25}{spurious space in warning message removed} |
| 1066 |
% \changes{v0.1.9}{2021/05/30}{requires package \pkg*{tocbasic}} |
| 1067 |
% \changes{v0.1.9}{2021/05/30}{can be used only in preamble} |
| 1068 |
% \changes{v0.1.12}{2023/03/31}{using \cs{IfArgIsEmpty} instead of \cs{Ifstr} |
| 1069 |
% with empty argument} |
| 1070 |
% Clone the entries from the second (first mandatory) argument TOC to the |
| 1071 |
% third (second mandatory) argument TOC. If the first (optional) argument was |
| 1072 |
% given, define |\listof#3name| to this and also define |\listof#3| and clone |
| 1073 |
% the toc features \texttt{leveldown}, \texttt{numbered}, \texttt{onecolumn} |
| 1074 |
% and \texttt{totoc} of |#2| to |#3|. The toc feature \texttt{nobabel} will |
| 1075 |
% always be set, because the babel entries at TOC |#3| will be cloned from TOC |
| 1076 |
% |#2|. |
| 1077 |
% \begin{description} |
| 1078 |
% \item{Note:} We use owner \texttt{TOCclone} for all cloned extensions. |
| 1079 |
% \end{description} |
| 1080 |
% \begin{macrocode} |
| 1081 |
\newcommand*{\TOCclone}[3][]{% |
| 1082 |
\RequirePackage{tocbasic}% |
| 1083 |
\scr@ifundefinedorrelax{scrwfile@clone@#2}{% |
| 1084 |
\expandafter\protected@edef\csname scrwfile@clone@#2\endcsname{% |
| 1085 |
#3,\protect\csname scrwfile@clone@#3\endcsname |
| 1086 |
}% |
| 1087 |
}{% |
| 1088 |
\edef\reserved@b{\csname scrwfile@clone@#2\endcsname}% |
| 1089 |
\expandafter\protected@edef\csname scrwfile@clone@#2\endcsname{% |
| 1090 |
\csname scrwfile@clone@#2\endcsname,% |
| 1091 |
#3,% |
| 1092 |
\protect\csname scrwfile@clone@#3\endcsname |
| 1093 |
}% |
| 1094 |
}% |
| 1095 |
\scr@ifundefinedorrelax{scrwfile@clone@#3}{% |
| 1096 |
\expandafter\let\csname scrwfile@clone@#3\endcsname\@empty |
| 1097 |
}{}% |
| 1098 |
\Ifattoclist{#3}{% |
| 1099 |
\PackageWarning{scrwfile}{`#3' already under control of |
| 1100 |
tocbasic.\MessageBreak |
| 1101 |
Nevertheless features will be set% |
| 1102 |
}% |
| 1103 |
}{% |
| 1104 |
\addtotoclist[TOCclone]{#3}% |
| 1105 |
}% |
| 1106 |
\setuptoc{#3}{nobabel}% |
| 1107 |
\IfArgIsEmpty{#1}{% |
| 1108 |
}{% |
| 1109 |
\@namedef{listof#3name}{#1}% |
| 1110 |
\@namedef{listof#3}{\listoftoc{#3}}% |
| 1111 |
\Iftocfeature{#2}{leveldown}{\setuptoc{#3}{leveldown}}{}% |
| 1112 |
\Iftocfeature{#2}{numbered}{\setuptoc{#3}{numbered}}{}% |
| 1113 |
\Iftocfeature{#2}{onecolumn}{\setuptoc{#3}{leveldownonecolumn}}{}% |
| 1114 |
\Iftocfeature{#2}{totoc}{\setuptoc{#3}{totoc}}{}% |
| 1115 |
}% |
| 1116 |
} |
| 1117 |
\@onlypreamble\TOCClone |
| 1118 |
% \end{macrocode} |
| 1119 |
% \end{command} |
| 1120 |
% |
| 1121 |
% \begin{macrocode} |
| 1122 |
%</package> |
| 1123 |
% \end{macrocode} |
| 1124 |
% |
| 1125 |
% \Finale |
| 1126 |
% \PrintChanges |
| 1127 |
% |
| 1128 |
% \endinput |
| 1129 |
% Local Variables: |
| 1130 |
% mode: doctex |
| 1131 |
% ispell-local-dictionary: "en_US" |
| 1132 |
% eval: (flyspell-mode 1) |
| 1133 |
% TeX-master: t |
| 1134 |
% TeX-engine: luatex-dev |
| 1135 |
% eval: (setcar (or (cl-member "Index" (setq-local TeX-command-list (copy-alist TeX-command-list)) :key #'car :test #'string-equal) (setq-local TeX-command-list (cons nil TeX-command-list))) '("Index" "mkindex %s" TeX-run-index nil t :help "makeindex for dtx")) |
| 1136 |
% End: |