% ======================================================================
% scrwfile.tex
% Copyright (c) Markus Kohm, 2001-2017
%
% 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-2017
%
% 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: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $
                  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.

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 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{listoffigure} 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.

Tatsächlich sind bisher keine solchen Probleme im Zusammenhang mit
\Package{scrwfile} bekannt, obwohl das Paket vor der Veröffentlichung von
verschiedenen Anwendern über ein Jahr lang getestet wurde. Wenn Sie jedoch auf
ein solches Problem stoßen, sollten Sie sich an den \KOMAScript-Autor wenden.


\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 dann noch die \File{wrt}-Datei abgearbeitet und zwar
ein Mal für jede der Hilfsdateien, in die mit \Macro{@writefile} geschrieben
wird. Dabei muss dann 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.

\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
\Package{tocbasic}\important{\Package{tocbasic}} (siehe
\autoref{cha:tocbasic}) verwaltet. Steht eine solche Datei bereits unter
Kontrolle von \Package{tocbasic} wird eine Warnung ausgegeben. Anderenfalls
wird mit Hilfe von \Package{tocbasic} ein neues Verzeichnis für diese Endung
angelegt. Die Überschrift dieses 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{\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\addcontentsline
      {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 \Package{tocbasic}\important{\Package{tocbasic}}
  zum Einsatz kommt, kann aber
  \phantomsection\xmpllabel{cmd.BeforeStartingTOC}
\begin{lstcode}
  \BeforeStartingTOC[toc]{%
    \addcontentsline{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 \Package{tocbasic}
  steht. Dies ist bei allen \KOMAScript-Klassen der Fall. Näheres zur
  Anweisung \DescPageRef{tocbasic.cmd.BeforeStartingTOC} ist in
  \autoref{sec:tocbasic.toc} auf \DescPageRef{tocbasic.cmd.BeforeStartingTOC}
  zu finden.
\end{Example}
%
\EndIndexGroup


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

Obwohl das Paket bereits von mehreren Anwendern getestet wurde und vielfach im
Einsatz ist, ist seine Entwicklung noch nicht abgeschlossen. Deshalb ist es
theoretisch möglich, dass insbesondere an der internen Funktionsweise des
Pakets noch Änderungen vorgenommen werden. Sehr wahrscheinlich sind auch
künftige Erweiterungen. Teilweise befindet sich bereits Code für solche
Erweiterungen im Paket. Da jedoch noch keine Benutzeranweisungen existieren,
mit denen diese Möglichkeiten genutzt werden könnten, wurde hier 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. Dies\textnote{Achtung!} führt dazu, dass \Package{scrwfile}
sich nicht mit anderen Paketen verträgt, die diese 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: iso-latin-1
%%% 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

