summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex')
-rw-r--r--Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex237
1 files changed, 131 insertions, 106 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex
index 9d69c9d2fc7..8003dffb7cf 100644
--- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex
+++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrwfile.tex
@@ -1,53 +1,58 @@
-%%
-%% This is file `scrwfile.tex',
-%% generated with the docstrip utility.
-%%
-%% The original source files were:
-%%
-%% scrwfile.dtx (with options: `doc')
-%%
-%% Copyright (c) 2010-2013 by Markus Kohm <komascript(at)gmx.info>
-%%
-%% This file was generated from file(s) of the 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 file may only be distributed together with the file
-%% `scrwfile.dtx' and `scrlogo.dtx'. You may however distribute the files
-%% `scrwfile.dtx' and `scrlogo.dtx' without this file.
-%%
-%% If this file is a beta version, you are not allowed to distribute it.
-%%
-%% English and German manuals are part of KOMA-Script bundle.
-%% ----------------------------------------------------------
-%%
-%% The english manual is at `scrwfile.dtx', too.
-%%
-%% The KOMA-Script bundle (but not this file) was based upon the LaTeX2.09
-%% Script family created by Frank Neukam 1993 and the LaTeX2e standard
-%% classes created by The LaTeX3 Project 1994-1996.
-%%
-%% THIS IS AN ALPHA VERSION!
-%% USAGE OF THIS VERSION IS ON YOUR OWN RISK!
-%% EVERYTHING MAY HAPPEN!
-%% EVERYTHING MAY CHANGE IN FUTURE!
-%% THERE IS NO SUPPORT, IF YOU USE THIS PACKAGE!
-%%
-%%% From File: $Id: scrwfile.dtx 1562 2013-12-19 07:51:16Z mjk $
-\ProvidesFile{scrwfile.tex}
- [2013/08/05 v0.1f-alpha LaTeX2e KOMA-Script package (write and clone files)]
-\chapter[{Spare and Replace Files Using \Package{scrwfile}}]
-{Spare and Replace Files Using \Package{scrwfile}%
+% ======================================================================
+% scrwfile.tex
+% Copyright (c) Markus Kohm, 2010-2014
+%
+% 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, 2010-2014
+%
+% 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 ueber scrwfile in der KOMA-Script-Anleitung
+% Verwaltet von Markus Kohm
+%
+% ============================================================================
+
+\KOMAProvidesFile{scrwfile.tex}%
+ [$Date: 2014-10-16 08:48:50 +0200 (Thu, 16 Oct 2014) $
+ KOMA-Script guide (chapter: scrwfile)]
+
+\translator{Markus Kohm\and Jana Schubert}
+
+\chapter[{Economise and Replace Files Using \Package{scrwfile}}]
+{Economise and Replace Files Using \Package{scrwfile}%
}
\labelbase{scrwfile}
@@ -68,61 +73,60 @@ The bottom line is, that this eventually will result in the error message:
\fi
\end{lstcode}
-Last but not least, immediately opening one more write handle for every table
-of contents, list of figures, list of tables, and so on has one more
-disadvantage. These are not only set by the corresponding commands, they also
-couldn't not be set once more, because their helper files are empty after the
-corresponding commands until the end of the document.
+There is an additional disadvantage of immediately opening a new write handle
+for every table of contents, list of figures, list of tables etc. These are
+not only set by the corresponding commands, they also could not be set once
+more, because their helper files are empty after the corresponding commands
+until the end of the document.
-Package \Package{scrwfile} provides a general change of the \LaTeX{} kernel,
-that may solve both problems.
+Package \Package{scrwfile} provides an amendment of the \LaTeX{} kernel,
+that solves both problems.
\section{General Modifications of the \LaTeX{} Kernel}
\label{sec:scrwfile.kernelpatches}
-\LaTeX{} classes use the \LaTeX{} kernel command
-\Macro{@starttoc}\IndexCmd{@starttoc} for output and opening of a new table of
-contents, list of float, e.\,g., \Macro{listoffigures} or
-\Macro{listoftables}, or similar. Thereby \LaTeX{} not only reads the helper
-file with the contents of the directory, but opens the helper file for writing
-also. Nevertheless, if afterwards new entries to these lists of floats will be
-made using \Macro{addcontentsline}, then this will not write immediately to
-the helper file. Instead of \LaTeX{} writes
+To allocate a new file handle eg. for \Macro{listoffigures} or
+\Macro{listoftables} \LaTeX{} classes use the \LaTeX{} kernel command
+\Macro{@starttoc}\IndexCmd{@starttoc}. This command not only inputs the
+associated helper file but also allocates a new write handle for the
+associated helper file and opens it for writing. Nevertheless, if afterwards
+new entries to these lists of floats are added using \Macro{addcontentsline},
+then these file handles are not used immediately, instead \LaTeX{} writes
\Macro{@writefile}\IndexCmd{@writefile} commands into the
\File{aux}-file. Only while reading the \File{aux}-file while the end of the
-document, those \Macro{@writefile} commands generates real write operations
-into the helper files. \LaTeX{} even doesn't close the helper files
-explicitly. Instead of \LaTeX{} counts on \TeX{} to close all open files at
+document, those \Macro{@writefile} commands become real write operations
+on the helper files. Additionally \LaTeX{} does not close the helper files
+explicitly. Instead \LaTeX{} relies on \TeX{} to close all open files at
the end.
-This procedure means, that all the helper files are open for writing from the
-output of the contents, i.\,e. at the front matter of the document until the
-end of the document, though their content is written after the end of the
-document. \Package{scrwfile}'s basic approach is exactly this: redefinition of
+Thus all the helper files are open throughout the entire process. However the
+content is written at \Macro{end}\PParameter{document}. The basic idea of
+\Package{scrwfile} is tackling this contradiction by redefining
\Macro{@starttoc} and \Macro{@writefile}.
-Surely\textnote{Attention!}, changes of the \LaTeX{} kernel always may
-potentially result in incompatibilities with other packages. In case of
-\Package{scrwfile} this may be happen with all packages, that redefine
-\Macro{@starttoc} or \Macro{@writefile} too. Sometimes changing the order of
+Surely\textnote{Attention!}, changes of the \LaTeX{} kernel may
+result in incompatibilities with other packages. In case of
+\Package{scrwfile}, clashes my arise with all packages also redefining
+\Macro{@starttoc} or \Macro{@writefile}. Sometimes changing the order of
loading the packages may help.
-In fact, such problems with \Package{scrwfile} haven't been reported currently,
-though several users have tested the package for more than a year until first
-release. Nevertheless, if you find such a problem, please contact the
+However, only few such problems have been reported eventhough several users
+have tested the package for one year before its first release. See
+\autoref{sec:scrwfile.incompatible} for more information about known
+incompatibilities. If you find such a problem, please contact the
\KOMAScript{} author.
\section{The Single File Feature}
\label{sec:scrwfile.singlefilefeature}
-Just while loading the package using, e.\,g.,
+At the point the package is loaded using, e.\,g.,
\begin{lstcode}[belowskip=\dp\strutbox]
\usepackage{scrwfile}
\end{lstcode}
\Package{scrwfile} will redefine \Macro{@starttoc}\IndexCmd{@starttoc} to not
-longer allocate a file handle or open any file for writing. Immediately before
+longer allocate a write handle or open any file for writing. Immediately before
closing the \File{aux}-file in \Macro{end}\PParameter{document} it will
-redefine \Macro{@writefile} to not longer write into the usual helper files
+redefine \Macro{@writefile} to no longer write into the usual helper files
but into one single new file with file extension \File{wrt}. After
reading the \File{aux}-file this \File{wrt}-file will be processed once per
helper file. This means, that not all of the helper file have to be open at
@@ -131,22 +135,22 @@ afterwards and the write handle is not longer needed after it is closed. An
internal write handle of \LaTeX{} is used for this. So \Package{scrwfile}
doesn't need any own write handle.
-Because of this, even if only one table of contents should be generated, after
-loading \Package{scrwfile} one more write file handle will be available,
+Because of this, even if only one table of contents should be generated,
+loading \Package{scrwfile} gives one extra write file handle,
e.\,g., for bibliographies, indexes, glossaries and similar, that are not
using \Macro{@starttoc}. Additionally the number of tables of contents and
-lists of whatever, that use \Macro{@starttoc}\IndexCmd{@starttoc} won't be
+lists of whatever, that use \Macro{@starttoc}\IndexCmd{@starttoc} is not
limited any longer.
\section{The Clone File Write Feature}
\label{sec:scrwfile.clonefilefeature}
Sometimes it is useful to input a file not only once but several times. As
-\Macro{@starttoc} does not open files for writing any longer, this may be
-done by simply using \Macro{@starttoc} several times with the same
-extension. But sometimes you may have additional entries in only some of the
-content directories. Because of this, \Package{scrwfile} allows to copy all
-entries of a file to another file, too. We call this cloning.
+\Macro{@starttoc} does not open files for writing any more, this can be done
+by simply using \Macro{@starttoc} several times with the same extension. But
+sometimes you may have additional entries in only some of the content
+directories. \Package{scrwfile} allows to copy all entries of a file to
+another file, too. We call this cloning.
\begin{Declaration}
\Macro{TOCclone}%
@@ -156,7 +160,7 @@ entries of a file to another file, too. We call this cloning.
activates the clone feature for files with extensions \PName{source} and
\PName{destination}. All entries to the file
\Macro{jobname}\File{.}\PName{source} will be added to
-\Macro{jobname}\File{.}\PName{destination}, too.
+\Macro{jobname}\File{.}\PName{destination}.
If extension \PName{destination} is a new one, \PName{destination} will be
added to the list of known extensions using the \KOMAScript{} package
@@ -169,7 +173,7 @@ as section (or chapter) heading of this list. In this case several
\PName{destination}, if and only if they have been set up when
\Macro{TOCclone} was used. Feature \PName{nobabel} will always be set,
because the language selection commands are part of the helper file and
-would be cloned, too.
+would be cloned, anyway.
\begin{Example}
Assumed, you want a short table of contents
@@ -179,8 +183,8 @@ contents:
\usepackage{scrwfile}
\TOCclone[Short \contentsname]{toc}{stoc}
\end{lstcode}
-This would create a new table of contents with the heading ^^c2^^bbShort
-Contents^^c2^^ab. The new table of contents uses a helper file with extension
+This would create a new table of contents with the heading ``Short
+Contents''. The new table of contents uses a helper file with extension
\File{stoc}. All entries to the helper file with extension \File{toc} will
also be copied to this new helper file.
@@ -191,9 +195,9 @@ be done using:
\end{lstcode}
Normally you cannot write into a helper file before
\Macro{begin}\PParameter{document}. But using \Package{scrwfile} changes
-this. So the code above will be successful after loading \Package{scrwfile}.
+this. So the code above is correct already after loading \Package{scrwfile}.
-To show the new short contents of helper file extension \File{stoc} we will
+To show the new short contents of helper file extension \File{stoc} we
use
\begin{lstcode}[moretexcs={listofsttoc}]
\listofstoc
@@ -219,7 +223,7 @@ too. So we cannot add the command to the \File{toc}-file. Package
{\protect\contentsname}%
}
\end{lstcode}
-But this needs, that the file with extension \File{toc} is under control of
+However, this needs, that the file with extension \File{toc} is under control of
package \Package{tocbasic}, which is indeed the case within all \KOMAScript{}
classes.
See \autoref{sec:tocbasic.toc} on
@@ -228,19 +232,40 @@ See \autoref{sec:tocbasic.toc} on
\end{Example}
\EndIndex{Cmd}{TOCclone}
-\section{State of Development Note}
+\section{Note on State of Development}
\label{sec:scrwfile.draft}
-Though this package has been tested by several users and even is in
-productivity usage several times, development is not finished yet. Because of
-this especially internal functionality may be changed in future. Most likely
+Eventhough this package has been tested by several users and even is in
+productivity usage several times it is still under construction. Therefore,
+there might be amendments especially to the internal functionality. Most likely
the package will be extended. Some code for extensions is already in the
-package. Nevertheless, currently user haven't make requests for such
-extension. So there's currently no user documentation for this.
+package. However, there is currently no user documentation available, as up to
+now nobody has requested any of these extensions.
+
+\section{Known Package Incompatibilities}
+\label{sec:scrwfile.incompatible}
+
+As mentioned in \autoref{sec:scrwfile.kernelpatches},
+\Package{scrwfile} redefines some commands of the \LaTeX{} kernel. This
+happens not only while loading the package, but indeed at different times of
+processing a document, e.\,g., just before reading the
+\File{aux}-file. This\textnote{Attention!} results in incompatibility with
+packages that also redefine these commands at run-time.
+
+The \Package{titletoc}\important{Package{titletoc}}\IndexPackage{titletoc}
+package is an example for such an incompatibility. That
+package redefines \Macro{@writefile} under some conditions at run-time. If you
+use both, \Package{scrwfile} and \Package{titletoc}, there is no warranty for
+the correct behaviour of neither of them. This is neither an error of
+\Package{titletoc} nor of \Package{scrwfile}.
\EndIndex{Package}{scrwfile}
-\endinput
-%%
-%% End of file `scrwfile.tex'.
+%%% Local Variables:
+%%% mode: latex
+%%% mode: flyspell
+%%% coding: us-ascii
+%%% ispell-local-dictionary: "en_GB"
+%%% TeX-master: "../guide"
+%%% End: