diff options
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.tex | 237 |
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: |