path: root/macros/latex/contrib/koma-script/source-doc/ngerman/scrwfile.tex

% ======================================================================
% scrwfile.tex
% Copyright (c) Markus Kohm, 2001-2021
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX 
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of all files listed in manifest.txt.
% ----------------------------------------------------------------------
% scrwfile.tex
% Copyright (c) Markus Kohm, 2001-2021
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
% Die neuste Version dieser Lizenz ist
%   http://www.latex-project.org/lppl.txt
% und Version 1.3c ist Teil aller Verteilungen von LaTeX
% Version 2005/12/01 oder spaeter und dieses Werks.
%
% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained"
% (allein durch den Autor verwaltet).
%
% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm.
% 
% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien.
% ======================================================================
%
% Chapter about scrwfile of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------------
%
% Kapitel über scrwfile in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ============================================================================

\KOMAProvidesFile{scrwfile.tex}
                 [$Date: 2021-05-30 19:31:59 +0200 (Sun, 30 May 2021) $
                  KOMA-Script guide (chapter: scrwfile)]

\chapter{Dateien mit \Package{scrwfile} sparen und ersetzen}
\labelbase{scrwfile}

\BeginIndexGroup
\BeginIndex{Package}{scrwfile}
Eines der Probleme, die auch durch die Einführung von \eTeX{} nicht gelöst
wurden, ist die Tatsache, dass \TeX{} nur 18 Dateien gleichzeitig zum Schreiben
geöffnet haben kann. Diese Zahl erscheint zunächst recht groß. Allerdings ist
zu berücksichtigen, dass bereits \LaTeX{} selbst einige dieser Dateien
belegt. Inhaltsverzeichnis, Tabellenverzeichnis, Abbildungsverzeichnis, Index,
Glossar und jedes weitere Verzeichnis, das von \LaTeX{} aus erzeugt wird,
belegt in der Regel eine weitere Datei. Dazu kommen Hilfsdateien von Paketen
wie \Package{hyperref} oder \Package{minitoc}.

Im Endeffekt kann es daher geschehen, dass irgendwann die Meldung
\begin{lstcode}
  ! No room for a new \write .
  \ch@ck ...\else \errmessage {No room for a new #3}
                                                    \fi 
\end{lstcode}
erscheint. Seit einiger Zeit ist die einfachste Lösung dieses Problems die
Verwendung von Lua\LaTeX{} anstelle von PDF\LaTeX{} oder \XeLaTeX. Damit
entfällt die Beschränkung und die maximale Anzahl der gleichzeitig zum
Schreiben geöffneten Dateien wird nur noch durch das Betriebssystem
bestimmt. In der Realität braucht man sich darüber dann normalerweise keine
Gedanken mehr zu machen.

Dass \LaTeX{} bei Verzeichnissen wie dem Inhaltsverzeichnis, dem
Tabellenverzeichnis und dem Abbildungsverzeichnis immer sofort eine neue Datei
zum Schreiben öffnet, hat aber auch noch einen weiteren Nachteil. Solche
Verzeichnisse werden durch deren Befehle nicht nur direkt gesetzt, sie können
auch kein weiteres Mal gesetzt werden, da die zugehörige Hilfsdatei nach dem
jeweiligen Befehl bis zum Ende des Dokuments leer ist.

Das Paket \Package{scrwfile} bietet hier eine grundsätzliche Änderung im
\LaTeX-Kern, durch die beide Probleme nicht nur für Lua\LaTeX{} sondern auch bei
Verwendung von PDF\LaTeX{} oder \XeLaTeX{} gelöst werden können.


\section{Grundsätzliche Änderungen am \LaTeX-Kern}
\seclabel{kernelpatches}

\LaTeX-Klassen verwenden zum Öffnen eines Verzeichnisses, beispielsweise mit
\Macro{tableofcontents} oder \Macro{listoffigures}, die \LaTeX-Kern-Anweisung
\Macro{@starttoc}\IndexCmd{@starttoc}. \LaTeX{} selbst lädt bei dieser
Anweisung nicht nur die zugehörige Hilfsdatei, sondern öffnet diese Hilfsdatei
auch neu zum Schreiben. Werden anschließend mit \Macro{addtocontents} oder
\Macro{addcontentsline} Einträge in dieses Verzeichnis vorgenommen, so wird
jedoch nicht direkt in die geöffnete Hilfsdatei geschrieben. Stattdessen
schreibt \LaTeX{} \Macro{@writefile}-Anweisungen\IndexCmd{@writefile} in die
\File{aux}-Datei. Erst beim Einlesen der \File{aux}-Dateien am Ende des
Dokuments wird dann über diese \Macro{@writefile}-Anweisungen in die
tatsächlichen Hilfsdateien geschrieben. Die Hilfsdateien werden von \LaTeX{}
auch nicht explizit geschlossen. Stattdessen verlässt sich \LaTeX{} hier
darauf, dass \TeX{} die Dateien am Ende ohnehin schließt.

Dieses Vorgehen sorgt dafür, dass die Hilfsdateien zwar erst innerhalb von
\Macro{end}\PParameter{document} tatsächlich beschrieben werden, aber trotzdem
während des gesamten \LaTeX-Laufs gleichzeitig offen sind. \Package{scrwfile}
hat nun genau hier einen Ansatzpunkt: die Umdefinierung von \Macro{@starttoc}
und \Macro{@writefile}.

Natürlich\textnote{Achtung!} besitzen Änderungen am \LaTeX-Kern immer das
Potential, dass es zu Unverträglichkeiten mit anderen Paketen kommen
kann. Betroffen können in erster Linie Pakete sein, die ebenfalls
\Macro{@starttoc} oder \Macro{@writefile} umdefinieren. In einigen Fällen kann
es helfen, die Reihenfolge der Pakete zu ändern.%
\iffalse % Umbruchkorrektur
\ Wenn Sie auf ein solches Problem stoßen, sollten Sie sich an den
\KOMAScript-Autor wenden.5
\fi

\section{Das Eindateiensystem}
\seclabel{singlefilefeature}

Bereits beim Laden des Pakets mit
% Umbruchoptimierung: listings
\begin{lstcode}
  \usepackage{scrwfile}
\end{lstcode}
wird \Macro{@starttoc}\IndexCmd{@starttoc} von \Package{scrwfile} so
umdefiniert, dass davon selbst keine Datei mehr zum Schreiben angefordert und
geöffnet wird. Unmittelbar vor dem Schließen der \File{aux}-Datei in
\Macro{end}\PParameter{document} wird dann \Macro{@writefile} so umdefiniert,
dass diese Anweisung statt in die eigentlichen Hilfsdateien in eine neue
Hilfsdatei mit der Endung \File{wrt} schreibt. Nach dem Einlesen der
\File{aux}-Dateien wird schließlich die \File{wrt}-Datei abgearbeitet und zwar
ein Mal für jede der Hilfsdateien, in die mit \Macro{@writefile} geschrieben
wird. Dabei muss aber nicht jede dieser Hilfsdateien gleichzeitig
geöffnet sein. Stattdessen ist immer nur eine zum Schreiben geöffnet und wird
auch wieder explizit geschlossen. Da dabei eine interne Schreibdatei von
\LaTeX{} wiederverwendet wird, benötigt \Package{scrwfile} keine einzige
eigene Schreibdatei für diese Art von Verzeichnissen.

Selbst wenn bisher nur mit einem Inhaltsverzeichnis gearbeitet wird, steht
nach dem Laden des Pakets bereits eine Schreibdatei mehr für
Literaturverzeichnisse, Stichwortverzeichnisse, Glossare und ähnliche
Verzeichnisse, die nicht mit \Macro{@starttoc} arbeiten, zur
Verfügung. Darüber hinaus können beliebig viele Verzeichnisse, die mit
\Macro{@starttoc}\IndexCmd{@starttoc} arbeiten, angelegt werden.%
%

\section{Das Klonen von Dateieinträgen}
\seclabel{clonefilefeature}

Nachdem \Macro{@writefile}\IndexCmd{@writefile} für das Eindateiensystem aus
dem vorherigen Abschnitt bereits so geändert wurde, dass es nicht direkt in
die entsprechende Hilfsdatei schreibt, lag eine weitere Idee nahe. Beim
Kopieren der \Macro{@writefile}-Anweisungen in die \File{wrt}-Datei können
diese auch für andere Zielendungen übernommen werden. Es sei ausdrücklich
darauf hingewiesen, dass dies nur in der Dokumentpräambel funktioniert.

\begin{Declaration}
  \Macro{TOCclone}\OParameter{Verzeichnisüberschrift}
                  \Parameter{Quellendung}\Parameter{Zielendung}
  \Macro{listof\PName{Zielendung}}
\end{Declaration}%
Durch dieses Klonen von Dateieinträgen werden so ganze Verzeichnisse
geklont. Dazu muss man nur die Endung der Hilfsdatei des Verzeichnisses
kennen, dessen Einträge kopiert werden sollen. Zusätzlich muss man die Endung
einer Zieldatei angeben. In diese werden die Einträge dann kopiert. Natürlich
kann man in dieses geklonte Verzeichnis auch zusätzliche Einträge
schreiben.

Die \PName{Zielendung} der Zieldatei wird mit Hilfe von
\hyperref[cha:tocbasic]{\Package{tocbasic}}%
\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} (siehe
\autoref{cha:tocbasic}) verwaltet. Steht eine solche Datei bereits unter
Kontrolle von \hyperref[cha:tocbasic]{\Package{tocbasic}} wird eine Warnung
ausgegeben. Anderenfalls wird mit Hilfe von
\hyperref[cha:tocbasic]{\Package{tocbasic}} ein neues Verzeichnis für diese
Endung angelegt. Die Überschrift des neuen Verzeichnisses kann man über das
optionale Argument \PName{Verzeichnisüberschrift} bestimmen.

Ausgeben kann man dieses neue Verzeichnis dann beispielsweise über die
Anweisung \Macro{listof\PName{Zielendung}}. Die
Verzeichniseigenschaften\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}}
\PValue{leveldown}, \PValue{numbered}, \PValue{onecolumn} und \PValue{totoc}
(siehe Anweisung \DescRef{tocbasic.cmd.setuptoc} in
\autoref{sec:tocbasic.toc}, \DescPageRef{tocbasic.cmd.setuptoc}) werden
automatisch in das Zielverzeichnis übernommen, falls sie für das
Quellverzeichnis bereits gesetzt waren. Die Eigenschaft \PValue{nobabel} wird
für geklonte Verzeichnisse immer gesetzt, da die entsprechenden
\Package{babel}-Einträge in das Quellverzeichnis ohnehin bereits kopiert
werden.

\begin{Example}
  Angenommen, Sie wollen zusätzlich zum normalen Inhaltsverzeichnis eine
  Gliederungsübersicht, in der nur die Kapitel angezeigt werden.
\begin{lstcode}
  \usepackage{scrwfile}
  \TOCclone[Gliederungsübersicht]{toc}{stoc}
\end{lstcode}
  Hierdurch wird zunächst ein neues Verzeichnis mit der Überschrift
  »Gliederungsübersicht« angelegt. Das neue Verzeichnis verwendet die
  Dateiendung \File{stoc}. Alle Einträge in die Datei mit der Endung
  \File{toc} werden auch in dieses Verzeichnis kopiert.

  Damit dieses neue Verzeichnis nun nur die Kapitelebene ausgibt, verwenden
  wir: 
\begin{lstcode}
  \addtocontents{stoc}{\protect\value{tocdepth}=0}
\end{lstcode}
  Während\textnote{Achtung!} normalerweise erst ab
  \Macro{begin}\PParameter{document} Einträge in ein Verzeichnis vorgenommen
  werden können, funktioniert dies nach Laden von \Package{scrwfile} bereits
  in der Dokumentpräambel. Durch die hier gezeigte unkonventionelle Art, den
  Zähler \DescRef{maincls.counter.tocdepth} innerhalb der Verzeichnisdatei zu
  ändern, bleibt diese Änderung nur für dieses Verzeichnis wirksam.

  Später im Dokument wird das Verzeichnis mit der Endung \File{stoc} dann
  durch
\begin{lstcode}[moretexcs={listofstoc}]
  \listofstoc
\end{lstcode}
  ausgegeben und zeigt nur die Teile und Kapitel des Dokuments.

  Etwas schwieriger wird es, wenn das Inhaltsverzeichnis in der
  Gliederungsübersicht angezeigt werden soll. Dies wäre zwar mit
\begin{lstcode}
  \addtocontents{toc}{%
    \protect\addxcontentsline
      {stoc}{chapter}{\protect\contentsname}%
  }
\end{lstcode}
  möglich. Da jedoch alle Einträge in \File{toc} auch nach \File{stoc} kopiert
  werden, würde so von der Gliederungsübersicht dieser Eintrag ebenfalls
  übernommen. Also darf der Eintrag nicht aus der Verzeichnisdatei heraus
  erzeugt werden. Da das Paket \hyperref[cha:tocbasic]{\Package{tocbasic}}%
  \important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} zum Einsatz kommt,
  kann aber%
  \phantomsection\xmpllabel{cmd.BeforeStartingTOC}%
\begin{lstcode}
  \BeforeStartingTOC[toc]{%
    \addxcontentsline{stoc}{chapter}
                     {\protect\contentsname}}
\end{lstcode}
  verwendet werden. Natürlich\textnote{Achtung!} setzt dies voraus, dass die
  Datei mit Endung \File{toc} auch unter der Kontrolle von
  \hyperref[cha:tocbasic]{\Package{tocbasic}} steht. Dies ist bei allen
  \KOMAScript-Klassen der Fall. Näheres zur Anweisung
  \DescRef{tocbasic.cmd.BeforeStartingTOC} ist in \autoref{sec:tocbasic.toc}
  auf \DescPageRef{tocbasic.cmd.BeforeStartingTOC} zu finden. Die Erklärung zu
  \DescRef{tocbasic.cmd.addxcontentsline} findet sich in demselben Abschnitt
  auf \DescPageRef{tocbasic.cmd.addxcontentsline}.%
\end{Example}%
\EndIndexGroup%
\ExampleEndFix


\section{Hinweis zum Entwicklungsstand}
\seclabel{draft}

Obwohl das Paket bereits von mehreren Anwendern getestet wurde und vielfach im
Einsatz ist, ist es vom Autor als experimentell eingestuft. Deshalb ist es
theoretisch möglich, dass insbesondere an der internen Funktionsweise des
Pakets noch Änderungen vorgenommen werden. Teilweise befindet sich auch Code
für zusätzliche Erweiterungen im Paket. Da jedoch keine Benutzeranweisungen
existieren, mit denen diese Möglichkeiten genutzt werden könnten, wurde auf
eine Dokumentation derselben verzichtet.


\section{Bekannte Paketunverträglichkeiten}
\seclabel{incompatible}

Wie in \autoref{sec:scrwfile.kernelpatches} bereits erwähnt, muss
\Package{scrwfile} einige wenige Anweisungen des \LaTeX-Kerns
umdefinieren. Dies geschieht nicht allein während des Ladens des Pakets,
sondern vielmehr zu verschiedenen Zeitpunkten während der Abarbeitung eines
Dokuments, beispielsweise vor dem Einlesen der
\File{aux}-Datei. Das\textnote{Achtung!} führt dazu, dass \Package{scrwfile}
sich nicht mit anderen Paketen verträgt, die dieselben Anweisungen ebenfalls
zur Laufzeit umdefinieren.

Ein Beispiel für eine solche Unverträglichkeit ist
\Package{titletoc}\important{\Package{titletoc}}\IndexPackage{titletoc}. Das
Paket definiert unter gewissen Umständen \Macro{@writefile} zur Laufzeit
um. Werden \Package{scrwfile} und \Package{titletoc} zusammen verwendet, ist
die Funktion beider Paket nicht mehr gewährleistet. Dies ist weder ein Fehler
in \Package{titletoc} noch in \Package{scrwfile}.%
%
\EndIndexGroup

%%% Local Variables: 
%%% mode: latex
%%% mode: flyspell
%%% coding: utf-8
%%% ispell-local-dictionary: "de_DE"
%%% TeX-master: "../guide"
%%% End: 

% LocalWords:  Eindateiensystem Schreibdatei Zieldatei Zielendung Quellendung
% LocalWords:  Verzeichnisüberschrift Dateiendung Zielendungen Verzeichnisdatei
% LocalWords:  Benutzeranweisungen Dokumentpräambel Kapitelebene
% LocalWords:  Paketunverträglichkeiten Verzeichniseigenschaften