Debian Codegraph @

texmf-dist/source/latex/scrwfile/scrwfile.dtx

raw
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: