summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex')
-rw-r--r--Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex703
1 files changed, 542 insertions, 161 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex
index 3c5153ee853..a3bfa1aab2e 100644
--- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex
+++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex
@@ -45,79 +45,73 @@
%
% ============================================================================
-\ProvidesFile{scrlfile.tex}[2007/09/26 KOMA-Script guide (chapter: scrlfile)]
+\ProvidesFile{scrlfile.tex}[2012/02/24 KOMA-Script guide (chapter: scrlfile)]
\translator{Gernot Hassenpflug\and Markus Kohm}
-% Date of translated german file: 2007/08/07
+% Date of translated german file: 2012/02/25
\chapter{Control Package Dependencies with \Package{scrlfile}}
\labelbase{scrlfile}
\BeginIndex{Package}{scrlfile}
-\begin{Explain}
- The introduction of {\LaTeXe} in 1994 brought many changes in the
- handling of {\LaTeX} extensions. Today the package author has many
- macros available to determine if another package or class is
- employed and whether specific options are used. The author can load
- other packages or can specify options in the the case that the
- package is loaded later. This has led to the expectation that the
- order in which package are loaded would not be important. Sadly
- this hope has not been fulfilled.
-\end{Explain}
+The introduction of {\LaTeXe} in 1994 brought many changes in the
+handling of {\LaTeX} extensions. Today the package author has many
+macros available to determine if another package or class is
+employed and whether specific options are used. The author can load
+other packages or can specify options in the the case that the
+package is loaded later. This has led to the expectation that the
+order in which package are loaded would not be important. Sadly
+this hope has not been fulfilled.
\section{About Package Dependencies}
\label{sec:scrlfile.dependency}
-\begin{Explain}
- More and more frequently, different packages either newly define or
- redefine the same macro again. In such a case the order in which a
- package is loaded becomes very important. For the user it sometimes
- becomes very difficult to understand the behaviour, and in some
- cases the user wants only to react to the loading of a package. This
- too is not really a simple matter.
-
- Let us take the simple example of loading the package
- \Package{longtable} with a {\KOMAScript} document class. The
- \Package{longtable} package defines table captions very well suited
- to the standard classes, but the captions are totally unsuitable for
- documents using {\KOMAScript} and also do not react to the options
- of the provided configuration commands. In order to solve this
- problem, the \Package{longtable} package commands which are
- responsible for the table captions need to be redefined. However, by
- the time the \Package{longtable} package is loaded, the
- {\KOMAScript} class has already been processed.
-
- Until the present, the only way for {\KOMAScript} to solve this
- problem was to delay the redefinition until the beginning of the
- document with help of the macro \Macro{AtBeginDocument}. If the
- user wants to change the definitions too, it is recommended to do
- this in the preamble of the document. However, this is impossible
- since later at \Macro{begin}\PParameter{document} {\KOMAScript} will
- again overwrite the user definition with its own. Therefore, the
- user too has to delay his definition with \Macro{AtBeginDocument}.
+
+More and more frequently, different packages either newly define or
+redefine the same macro again. In such a case the order in which a
+package is loaded becomes very important. For the user it sometimes
+becomes very difficult to understand the behaviour, and in some
+cases the user wants only to react to the loading of a package. This
+too is not really a simple matter.
+
+Let us take the simple example of loading the package \Package{longtable} with
+a {\KOMAScript} document class. The \Package{longtable} package defines table
+captions very well suited to the standard classes, but the captions are
+totally unsuitable for documents using {\KOMAScript} and also do not react to
+the options of the provided configuration commands. In order to solve this
+problem, the \Package{longtable} package commands which are responsible for
+the table captions need to be redefined. However, by the time the
+\Package{longtable} package is loaded, the {\KOMAScript} class has already
+been processed.
+
+Until the present, the only way for {\KOMAScript} to solve this problem was to
+delay the redefinition until the beginning of the document with help of the
+macro \Macro{AtBeginDocument}. If the user wants to change the definitions
+too, it is recommended to do this in the preamble of the document. However,
+this is impossible since later at \Macro{begin}\PParameter{document}
+{\KOMAScript} will again overwrite the user definition with its own.
+Therefore, the user too has to delay his definition with
+\Macro{AtBeginDocument}.
- Actually, {\KOMAScript} should not need to delay the redefinition
- until \Macro{begin}\PParameter{document}. It would be enough to
- delay exactly until the package \Package{longtable} has been
- loaded. Unfortunately, the {\LaTeX} kernel does not define
- appropriate commands. The package \Package{scrlfile} provides
- redress here.
+Actually, {\KOMAScript} should not need to delay the redefinition until
+\Macro{begin}\PParameter{document}. It would be enough to delay exactly until
+the package \Package{longtable} has been loaded. Unfortunately, the {\LaTeX}
+kernel does not define appropriate commands. The package \Package{scrlfile}
+provides redress here.
- Likewise, it might be conceivable that before a package is loaded
- one would like to save the definition of a macro in a help-macro, in
- order to restore its meaning after the package has been loaded. The
- package \Package{scrlfile} allows this, too.
+Likewise, it might be conceivable that before a package is loaded one would
+like to save the definition of a macro in a help-macro, in order to restore
+its meaning after the package has been loaded. The package \Package{scrlfile}
+allows this, too.
- The employment of \Package{scrlfile} is not limited to package
- dependencies only. Even dependencies on any other file can be
- considered. For example, the user can be warned if the not
- uncritical file \File{french.ldf} has been loaded.
+The employment of \Package{scrlfile} is not limited to package dependencies
+only. Even dependencies on any other file can be considered. For example,
+the user can be warned if the not uncritical file \File{french.ldf} has been
+loaded.
- Although the package is particularly of interest for package
- authors, there are of course applications for normal {\LaTeX} users,
- too. Therefore, this chapter gives and explains examples for both
- groups of users.
-\end{Explain}
+Although the package is particularly of interest for package authors, there
+are of course applications for normal {\LaTeX} users, too. Therefore, this
+chapter gives and explains examples for both groups of users.
\section{Actions Prior to and After Loading}
@@ -140,29 +134,25 @@ only executed before the next time \PName{file} is loaded.
been loaded. If \PName{file} is never loaded then the
\PName{instructions} will never be executed.
-\begin{Explain}
- In order to implement those features \Package{scrlfile} redefines
- the well known {\LaTeX} command \Macro{InputIfFileExists}. If this
- macro does not have the expected definition then \Package{scrlfile}
- issues a warning. This is for the case that in future {\LaTeX}
- versions the macro can have a different definition, or that another
- package has already redefined it.
+In order to implement those features \Package{scrlfile} redefines the well
+known {\LaTeX} command \Macro{InputIfFileExists}. If this macro does not have
+the expected definition then \Package{scrlfile} issues a warning. This is for
+the case that in future {\LaTeX} versions the macro can have a different
+definition, or that another package has already redefined it.
- The command \Macro{InputIfFileExists} is used by {\LaTeX} every time
- a file is to be loaded. This is independent of whether the actual
- load command is \Macro{include}, \Macro{LoadClass},
- \Macro{documentclass}, \Macro{usepackage}, \Macro{RequirePackage},
- or similar. Exceptionally, the command
- \begin{lstlisting}
- \input foo
- \end{lstlisting}
- loads the file \texttt{foo} without utilizing
- \Macro{InputIfFileExists}. Therefore, one should always use
- \begin{lstlisting}
- \input{foo}
- \end{lstlisting}
- instead. Notice the parentheses surrounding the file name!
-\end{Explain}
+The command \Macro{InputIfFileExists} is used by {\LaTeX} every time a file is
+to be loaded. This is independent of whether the actual load command is
+\Macro{include}, \Macro{LoadClass}, \Macro{documentclass}, \Macro{usepackage},
+\Macro{RequirePackage}, or similar. Exceptionally, the command
+\begin{lstcode}[belowskip=\dp\strutbox]
+ \input foo
+\end{lstcode}
+loads the file \texttt{foo} without utilizing
+\Macro{InputIfFileExists}. Therefore, one should always use
+\begin{lstcode}[belowskip=\dp\strutbox]
+ \input{foo}
+\end{lstcode}
+instead. Notice the parentheses surrounding the file name!%
%
\EndIndex{Cmd}{BeforeFile}%
\EndIndex{Cmd}{AfterFile}%
@@ -173,11 +163,11 @@ been loaded. If \PName{file} is never loaded then the
\end{Declaration}%
\BeginIndex{Cmd}{BeforeClass}%
\BeginIndex{Cmd}{BeforePackage}%
-These two commands work in the same way as \Macro{BeforeFile}. The
-only difference is that the document class \PName{class} and the
-{\LaTeX} package \PName{package} are specified with their names and
-not with their file names. That means that the file extensions
-\File{.cls} and \File{.sty} can be omitted.
+These two commands work in the same way as \Macro{BeforeFile}. The only
+difference is that the document class \PName{class} and the {\LaTeX} package
+\PName{package} are specified with their names and not with their file names.
+That means that the file extensions \File{.cls} and \File{.sty} can be
+omitted.%
%
\EndIndex{Cmd}{BeforeClass}%
\EndIndex{Cmd}{BeforePackage}%
@@ -185,88 +175,121 @@ not with their file names. That means that the file extensions
\begin{Declaration}
\Macro{AfterClass}\Parameter{class}\Parameter{instructions}\\
\Macro{AfterClass*}\Parameter{class}\Parameter{instructions}\\
+ \Macro{AfterClass+}\Parameter{class}\Parameter{instructions}\\
+ \Macro{AfterClass!}\Parameter{class}\Parameter{instructions}\\
+ \Macro{AfterAtEndOfClass}\Parameter{class}\Parameter{instructions}\\
\Macro{AfterPackage}\Parameter{package}\Parameter{instructions}\\
- \Macro{AfterPackage*}\Parameter{package}\Parameter{instructions}
+ \Macro{AfterPackage*}\Parameter{package}\Parameter{instructions}\\
+ \Macro{AfterPackage+}\Parameter{package}\Parameter{instructions}\\
+ \Macro{AfterPackage!}\Parameter{package}\Parameter{instructions}\\
+ \Macro{AfterAtEndOfPackage}\Parameter{package}\Parameter{instructions}
\end{Declaration}%
\BeginIndex{Cmd}{AfterClass}%
\BeginIndex{Cmd}{AfterClass*}%
+\BeginIndex{Cmd}{AfterClass+}%
+\BeginIndex{Cmd}{AfterClass!}%
+\BeginIndex{Cmd}{AfterAtEndOfClass}%
\BeginIndex{Cmd}{AfterPackage}%
\BeginIndex{Cmd}{AfterPackage*}%
+\BeginIndex{Cmd}{AfterPackage+}%
+\BeginIndex{Cmd}{AfterPackage!}%
+\BeginIndex{Cmd}{AfterAtEndOfPackage}%
The commands \Macro{AfterClass} and \Macro{AfterPackage} work in the
same way as \Macro{AfterFile}. The only difference is that the
document class \PName{class} and the {\LaTeX} package \PName{package}
are specified with their names and not with their file names. That
means that the file extensions \File{.cls} and \File{.sty} can be
-omitted. The starred versions execute the \PName{instructions} not
-only at next time that the class or package is loaded, but also
-immediately if the class or package has been loaded already.
-%
-\EndIndex{Cmd}{AfterClass}%
-\EndIndex{Cmd}{AfterClass*}%
-\EndIndex{Cmd}{AfterPackage}%
-\EndIndex{Cmd}{AfterPackage*}%
+omitted.
+
+The\important[i]{\Macro{AfterClass*}\\\Macro{AfterPackage*}} starred versions
+are a little bit different. They execute the \PName{instructions} not only at
+next time that the class or package is loaded, but also immediately if the
+class or package has been loaded already.
+
+The\important[i]{\Macro{AfterClass+}\\\Macro{AfterPackage+}}
+plussed\ChangedAt{v3.09}{\Package{scrlfile}} version executes the
+\PName{instructions} after loading of the class or package has been
+finished. The difference to the starred version is only valid, if loading of
+the class or package already started but hasn't been finished
+yet. Nevertheless, \PName{instructions} will be executed before the
+instructions of \Macro{AtEndOfClass} or \Macro{AtEndOfPackage} when loading of
+the class or package hasn't been finished already.
+
+If\important[i]{\Macro{AfterClass!}\\\Macro{AfterPackage!}} a class uses
+\Macro{AtEndOfClass} or a package uses \Macro{AtEndOfPackage} to execute
+instructions after the class of package file has been loaded completely, and
+if you want to execute \PName{instructions} after the instructions of these
+commands, you may use the exclamation mark version,
+\Macro{AfterClass!}\ChangedAt{v3.09}{\Package{scrlfile}} respectively
+\Macro{AfterPackage!}.
+
+If\important[i]{\Macro{AfterAtEndOfClass}\\\Macro{AfterAtEndOfPackage}} you
+want to do this only in the case the class or package will be loaded later,
+and if you want to execute \PName{instructions} outside the context of the
+class or package, that will be loaded, you may use
+\Macro{AfterAtEndOfClass}\ChangedAt{v3.09}{\Package{scrlfile}} for classes and
+\Macro{AfterAtEndOfPackage} for packages.
\begin{Example}
In the following, an example for class and package authors shall be
given. It shows how {\KOMAScript} itself employs the new commands.
The class \Class{scrbook} contains:
-\begin{lstlisting}
-\AfterPackage{hyperref}{%
- \@ifpackagelater{hyperref}{2001/02/19}{}{%
- \ClassWarningNoLine{scrbook}{%
- You are using an old version of hyperref package!%
- \MessageBreak%
- This version has a buggy hack at many drivers%
- \MessageBreak%
- causing \string\addchap\space to behave strange.%
- \MessageBreak%
- Please update hyperref to at least version
- 6.71b}}}
-\end{lstlisting}
-Old versions of the \Package{hyperref} package redefine a macro of the
-\Class{scrbook} class in such a way that does not work with newer
-{\KOMAScript} versions. New versions of \Package{hyperref} desist
-from making these changes if a new {\KOMAScript} version is detected.
-For the case that \Package{hyperref} is loaded at a later stage,
-therefore, the code in \Class{scrbook} verifies that a acceptable
-\Package{hyperref} version is used. If not, the command issues a
-warning.
-
-At other places in three {\KOMAScript} classes the following can be
-found:
-\begin{lstlisting}
+\begin{lstcode}
+ \AfterPackage{hyperref}{%
+ \@ifpackagelater{hyperref}{2001/02/19}{}{%
+ \ClassWarningNoLine{scrbook}{%
+ You are using an old version of hyperref package!%
+ \MessageBreak%
+ This version has a buggy hack at many drivers%
+ \MessageBreak%
+ causing \string\addchap\space to behave strange.%
+ \MessageBreak%
+ Please update hyperref to at least version
+ 6.71b}}}
+\end{lstcode}
+ Old versions of the \Package{hyperref} package redefine a macro of the
+ \Class{scrbook} class in such a way that does not work with newer
+ {\KOMAScript} versions. New versions of \Package{hyperref} desist
+ from making these changes if a new {\KOMAScript} version is detected.
+ For the case that \Package{hyperref} is loaded at a later stage,
+ therefore, the code in \Class{scrbook} verifies that a acceptable
+ \Package{hyperref} version is used. If not, the command issues a
+ warning.
+
+ At other places in three {\KOMAScript} classes the following can be
+ found:
+\begin{lstcode}
\AfterPackage{caption2}{%
\renewcommand*{\setcapindent}{%
-\end{lstlisting}
-After the package \Package{caption2} has been loaded, and only if it
-has been loaded, {\KOMAScript} redefines its own command
-\Macro{setcapindent}. The exact code of the redefinition is not
-important. It should only be noted that \Package{caption2} takes
-control of the \Macro{caption} macro and that therefore the normal
-definition of the \Macro{setcapindent} macro would become ineffective.
-The redefinition improves the collaboration with \Package{caption2}.
-
-There are however also useful examples for normal {\LaTeX} user.
-Suppose a document that should be available as a PS file, using
-{\LaTeX} and dvips, as well as a PDF file, using pdf{\LaTeX}. In
-addition, the document should contain hyperlinks. In the list of
-tables there are entries longer than one line. This is not a problem
-for the pdf{\LaTeX} method, since here hyperlinks can be broken across
-multiple lines. However, if a \Package{hyperref} driver for dvips or
-hyper{\TeX} is used then this is not possible. In this case one
-desires that for the \Package{hyperref} setup \Option{linktocpage} is
-used. The decision which \Package{hyperref} driver to use happens
-automatically via \File{hyperref.cfg}. The file has, for example, the
-following content:
-\begin{lstlisting}
+\end{lstcode}
+ After the package \Package{caption2} has been loaded, and only if it
+ has been loaded, {\KOMAScript} redefines its own command
+ \Macro{setcapindent}. The exact code of the redefinition is not
+ important. It should only be noted that \Package{caption2} takes
+ control of the \Macro{caption} macro and that therefore the normal
+ definition of the \Macro{setcapindent} macro would become ineffective.
+ The redefinition improves the collaboration with \Package{caption2}.
+
+ There are however also useful examples for normal {\LaTeX} user. Suppose a
+ document that should be available as a PS file, using {\LaTeX} and dvips, as
+ well as a PDF file, using pdf{\LaTeX}. In addition, the document should
+ contain hyperlinks. In the list of tables there are entries longer than one
+ line. This is not a problem for the pdf{\LaTeX} method, since here
+ hyperlinks can be broken across multiple lines. However, if a
+ \Package{hyperref} driver for dvips or hyper{\TeX} is used then this is not
+ possible. In this case one desires that for the \Package{hyperref} setup
+ \Option{linktocpage} is used. The decision which \Package{hyperref} driver
+ to use happens automatically via \File{hyperref.cfg}. The file has, for
+ example, the following content:
+\begin{lstcode}
\ProvidesFile{hyperref.cfg}
\@ifundefined{pdfoutput}{\ExecuteOptions{dvips}}
{\ExecuteOptions{pdftex}}
\endinput
-\end{lstlisting}
+\end{lstcode}
-All the rest can now be left to \Macro{AfterFile}.
-\begin{lstlisting}
+ All the rest can now be left to \Macro{AfterFile}.
+\begin{lstcode}
\documentclass{article}
\usepackage{scrlfile}
\AfterFile{hdvips.def}{\hypersetup{linktocpage}}
@@ -281,28 +304,386 @@ All the rest can now be left to \Macro{AfterFile}.
allow one to write a short caption in the list of figures.}
\end{figure}
\end{document}
-\end{lstlisting}
-If now the \Package{hyperref} drivers \Option{hypertex} or
-\Option{dvips} are used, then the useful \Package{hyperref} option
-\Option{linktocpage} will be set. In the pdf{\LaTeX} case, the option
-will not be set, since in that case another \Package{hyperref} driver,
-\File{hpdftex.def}, will be used. That means neither \File{hdvips.def}
-nor \File{hypertex.def} will be loaded.
+\end{lstcode}
+ If now the \Package{hyperref} drivers \Option{hypertex} or
+ \Option{dvips} are used, then the useful \Package{hyperref} option
+ \Option{linktocpage} will be set. In the pdf{\LaTeX} case, the option
+ will not be set, since in that case another \Package{hyperref} driver,
+ \File{hpdftex.def}, will be used. That means neither \File{hdvips.def}
+ nor \File{hypertex.def} will be loaded.
+\end{Example}
+
+Furthermore\textnote{Hint!}, the loading of package \Package{scrlfile} and
+the \Macro{AfterFile} statement can be written in a private
+\File{hyperref.cfg}. If you do so, then instead of \Macro{usepackage} the
+macro \Macro{RequirePackage} ought be used (see \cite{latex:clsguide}). The
+new lines have to be inserted directly after the \Macro{ProvidesFile} line,
+thus immediately prior to the execution of the options \Option{dvips} or
+\Option{pdftex}.%
+%
+\EndIndex{Cmd}{AfterClass}%
+\EndIndex{Cmd}{AfterClass*}%
+\EndIndex{Cmd}{AfterClass+}%
+\EndIndex{Cmd}{AfterClass!}%
+\EndIndex{Cmd}{AfterAtEndOfClass}%
+\EndIndex{Cmd}{AfterPackage}%
+\EndIndex{Cmd}{AfterPackage*}%
+\EndIndex{Cmd}{AfterPackage+}%
+\EndIndex{Cmd}{AfterPackage!}%
+\EndIndex{Cmd}{AfterAtEndOfPackage}%
+
+
+\begin{Declaration}
+ \Macro{BeforeClosingMainAux}\Parameter{instructions}\\
+ \Macro{AfterReadingMainAux}\Parameter{instructions}%
+\end{Declaration}%
+\BeginIndex{Cmd}{BeforeClosingMainAux}%
+\BeginIndex{Cmd}{AfterReadingMainAux}%
+Package authors often want to write something into the \File{aux}-file after
+the last document page have been shipped out. To do so, often
+\begin{lstcode}[belowskip=\dp\strutbox]
+ \AtEndDocument{%
+ \if@filesw
+ \write\@auxout{%
+ \protect\writethistoaux%
+ }%
+ \fi
+ }
+\end{lstcode}
+is used. Nevertheless this is not a real solution of the problem. If the last
+page of the document already have been shipped out before
+\Macro{end}\PParameter{document}, the code above will not result in any
+writing into the \File{aux}-file. If someone would try to fix this new problem
+using \Macro{immediate} just before \Macro{write}, the inverse problem would
+occur: If the last page wasn't shipped out before
+\Macro{end}\PParameter{document} the \Macro{writethistoaux} would be written
+into \File{aux}-file before ship-out the last page. Another often seen
+suggestion for this problem therefore is:
+\begin{lstcode}[belowskip=\dp\strutbox]
+ \AtEndDocument{%
+ \if@filesw
+ \clearpage
+ \immediate\write\@auxout{%
+ \protect\writethistoaux%
+ }%
+ \fi
+ }
+\end{lstcode}
+This suggestion has a disadvantage again: The ship-out of the last page has
+been enforced by the \Macro{clearpage}. After that, instructions like
+\begin{lstcode}[belowskip=\dp\strutbox]
+ \AtEndDocument{%
+ \par\vspace*{\fill}%
+ Note at the end of the document.\par
+ }
+\end{lstcode}
+wouldn't any longer output the note at the end of the last page of the
+document but at the end of one more page. Additionally \Macro{writethistoaux}
+would be written one page to early into the \File{aux}-file again.
+
+The best solution for this problem would be, to write to the \File{aux}-file
+immediately after the final \Macro{clearpage}, that is part of
+\Macro{end}\PParameter{document}, but just before closing the
+\File{aux}-file. This is the purpose of \Macro{BeforeClosingMainAux}:
+\begin{lstcode}[belowskip=\dp\strutbox]
+ \BeforeClosingMainAux{%
+ \if@filesw
+ \immediate\write\@auxout{%
+ \protect\writethistoaux%
+ }%
+ \fi
+ }
+\end{lstcode}
+This would be successful even if the final \Macro{clearpage} inside of
+\Macro{end}\PParameter{document} wouldn't really ship-out any page or if
+someone have had used \Macro{clearpage} in the argument of
+\Macro{AtEndDocument}.
+
+Nevertheless there one important limitation using
+\Macro{BeforeClosingMainAux}: You should not use a typeset instruction inside
+the \PName{instructions} of \Macro{BeforeClosingMainAux}! If you miss this
+limitation the result would be as unpredictable as the results of the
+problematic suggestions using \Macro{AtEndDocument} upward.
+
+Command \Macro{AfterReadingMainAux}\ChangedAt{v3.03}{\Package{scrlfile}}
+actually executes the \PName{instructions} just after closing and input of the
+\File{aux}-file inside of \Macro{end}\PParameter{document}. This will make
+sense only in some cases, e.\,g., to show statistic information, that will be
+valid only after input of the \File{aux}-file, or to write such information
+into the \File{log}-file, or to implement additional \emph{rerun}
+requests. Typeset instructions are even more critical inside these
+\PName{instructions} that inside the argument of \Macro{BeforeClosingMainAux}.%
+%
+\EndIndex{Cmd}{AfterReadingMainAux}%
+\EndIndex{Cmd}{BeforeClosingMainAux}%
+
+
+\section{Replacing Files at Input}
+\label{sec:scrlfile.replace}
+
+All previous sections in this chapter describe commands to execute
+instructions before or after input of a file, class, or package. Package
+\Package{scrlfile} also provides commands to input another file, class, or
+package instead of the one, that has been declared.
+
+
+\begin{Declaration}
+ \Macro{ReplaceInput}\Parameter{source file name}%
+ \Parameter{replacement file name}%
+\end{Declaration}%
+\BeginIndex{Cmd}{ReplaceInput}%
+This\ChangedAt{v2.96}{\Package{scrlfile}} command defines a replacement for
+the file of the first argument: \PName{source file name}, by the file of the
+second argument: \PName{replacement file name}. If \LaTeX{} will be instructed
+to input the file with \PName{source file name} at any time afterward, the
+file with the \PName{replacement file name} will be input instead. The
+replacement definition will be valid for all files, that the user will input
+with \Macro{InputIfFileExists} and for all files, that will be input with a
+command, that uses \Macro{InputIfFileExists} internally. To do so,
+\Package{scrlfile} redefined \Macro{InputIfFileExists}.
+
+\begin{Example}
+ You want \LaTeX{} to input file \File{\Macro{jobname}.xua} instead of file
+ \File{\Macro{jobname.aux}}. This may be done using
+\begin{lstcode}
+ \ReplaceInput{\jobname.aux}{\jobname.xua}
+\end{lstcode}
+ Additionally you may replace \File{\Macro{jobname}.xua} by
+ \File{\Macro{jobname}.uxa} using:
+\begin{lstcode}
+ \ReplaceInput{\jobname.xua}{\jobname.uxa}
+\end{lstcode}
+ This will also replace input of \File{\Macro{jobname}.aux}, i.\,e., while
+ \Macro{end}\PParameter{document}, by \File{\Macro{jobname}.uxa}. As you see,
+ the whole replacement chain will be executed.
+
+ Nevertheless a round robin replacement like
+\begin{lstcode}
+ \ReplaceInput{\jobname.aux}{\jobname.xua}
+ \ReplaceInput{\jobname.xua}{\jobname.aux}
+\end{lstcode}
+ would result in a \emph{stack size error}. So it is not possible to define a
+ replacement of a file by itself directly or indirectly.
+\end{Example}
+
+In theory is would also be possible to replace a package or class by another
+one. But \LaTeX{} would recognize the usage of the wrong file name in this
+case. A solution for this problem will be shown next.%
+%
+\EndIndex{Cmd}{ReplaceInput}%
+
+\begin{Declaration}
+ \Macro{ReplaceClass}\Parameter{source class}%
+ \Parameter{replacement package}\\
+ \Macro{ReplacePackage}\Parameter{source package}%
+ \Parameter{replacement package}%
+\end{Declaration}%
+\BeginIndex{Cmd}{ReplaceClass}%
+\BeginIndex{Cmd}{ReplacePackage}%
+Classes\ChangedAt{v2.96}{\Package{scrlfile}}\textnote{Attention!} or packages
+should never be replaced using previously described command
+\Macro{ReplaceInput}. Using this command would result in a \LaTeX{} warning
+because of class or package name not according the file name.
+\begin{Example}
+ You replace package \Package{fancyhdr} by package \Package{scrpage2}
+ inconsiderately using
+\begin{lstcode}
+ \ReplaceInput{fancyhdr.sty}{scrpage2.sty}
+\end{lstcode}
+ Loading \Package{fancyhdr}, would result in
+\begin{lstcode}
+ LaTeX warning: You have requested `scrpage2',
+ but the package provides `fancyhdr'.
+\end{lstcode}
+ after this. Users may be confused by such a warning, because they've used,
+ e.\,g., \Macro{usepackage}\PParameter{fancyhdr} and never requested package
+ \Package{scrpage2} on their own. But \Package{scrlfile} replaced the input
+ of \File{fancyhdr.sty} by \File{scrpage2.sty} because of your replacement
+ definition.
\end{Example}
+A solution for this problem would be, to use \Macro{ReplaceClass} or
+\Macro{ReplacePackage} instead of \Macro{ReplaceFile}. Please note, that in
+this case you have to use the names of the classes or packages only instead of
+the whole file name. This is similar to usage of \Macro{documentclass} and
+\Macro{usepackage}.
+
+The class replacement would perform for all classes, that will be loaded using
+\Macro{documentclass}, \Macro{LoadClassWithOptions}, or \Macro{LoadClass}. The
+package replacement would perform for all packages, that will be loaded using
+\Macro{usepackage}, \Macro{RequirePackageWithOptions}, or
+\Macro{RequirePackage}.
-\begin{Explain}
- Furthermore, the loading of package \Package{scrlfile} and the
- \Macro{AfterFile} statement can be written in a private
- \File{hyperref.cfg}. If you do so, then instead of
- \Macro{usepackage} the macro \Macro{RequirePackage} ought be used
- (see \cite{latex:clsguide}). The new lines have to be inserted
- directly after the \Macro{ProvidesFile} line, thus immediately prior
- to the execution of the options \Option{dvips} or \Option{pdftex}.
-\end{Explain}%
+Please\textnote{Attention!} note, that the \PName{replacement class} or the
+\PName{replacement package} will be loaded with the same options, the
+\PName{source class} or \PName{replacement class} would until it has been
+replaced. Replacement of a class or package by a class or package, that
+doesn't support a requested option, would result in a warning or even an error
+message. But you may declare such missing options using \Macro{BeforeClass} or
+\Macro{BeforePackage}.
+
+\begin{Example}
+ Assumed, package \Package{oldfoo} should be replaced by
+ \Package{newfoo}. This may be done using:
+\begin{lstcode}
+ \ReplacePackage{oldfoo}{newfoo}
+\end{lstcode}
+ Assumed the old package provides an option \Option{oldopt}, but the new
+ package doesn't. Using
+\begin{lstcode}
+ \BeforePackage{newfoo}{%
+ \DeclareOption{oldopt}{%
+ \PackageInfo{newfoo}%
+ {option `oldopt' not supported}%
+ }}%
+\end{lstcode}
+ additionally, would declare this missing option for package
+ \Package{newfoo}. This would avoid warning message about unsupported
+ options.
+
+ However, if package \Package{newfoo} supports an option \Option{newopt},
+ that should be used instead of option \Option{oldopt} of old package
+ \Package{oldfoo}, this may achieved using:
+\begin{lstcode}
+ \BeforePackage{newfoo}{%
+ \DeclareOption{oldopt}{%
+ \ExecuteOptions{newopt}%
+ }}%
+\end{lstcode}
+ Last but not least different default options may be selected, that should be
+ valid while package replacement:
+\begin{lstcode}
+ \BeforePackage{newfoo}{%
+ \DeclareOption{oldopt}{%
+ \ExecuteOptions{newopt}%
+ }%
+ \PassOptionsToPackage{newdefoptA,newdefoptB}%
+ {newfoo}%
+ }
+\end{lstcode}
+ or somehow more directly:
+\begin{lstcode}
+ \BeforePackage{newfoo}{%
+ \DeclareOption{oldopt}{%
+ \ExecuteOptions{newopt}%
+ }%
+ }%
+ \PassOptionsToPackage{newdefoptA,newdefoptB}%
+ {newfoo}%
+\end{lstcode}
+\end{Example}
+
+To replace classes package \Package{scrlfile} has to be loaded before the
+class using \Macro{RequirePackage} instead of \Macro{usepackage}.
+%
+\EndIndex{Cmd}{ReplacePackage}%
+\EndIndex{Cmd}{ReplaceClass}%
+
+
+\section{Prevent File Loading}
+\label{sec:scrlfile.prevent}
+
+Especially\ChangedAt{v3.08}{\Package{scrlfile}} classes or packages, that have
+been made for companies or institutes, often load a lot of packages not needed
+by the classes or packages itself but only because the users often use
+them. Now, if such a not essential package causes any kind of problem, loading
+of that package has to prevented. For this purpose \Package{scrlfile} again
+provides a solution.
+
+\begin{Declaration}
+ \Macro{PreventPackageFromLoading}\Parameter{package list}
+\end{Declaration}
+\BeginIndex{Cmd}{PreventPackageFromLoading}%
+Calling this command\ChangedAt{v3.08}{\Package{scrlfile}} before loading a
+package using \Macro{usepackage}\IndexCmd{usepackage},
+\Macro{RequirePackage}\IndexCmd{RequirePackage}, or
+\Macro{RequirePackageWithOptions}\IndexCmd{RequirePackageWithOptions} will
+prevent the package from being loaded effectively if the package is part of
+the \PName{package list}.
+%
+\begin{Example}
+ Assumed you're working in a company, that uses font Latin-Modern for all
+ kind of documents. Because of this the company class, \Class{compycls}
+ contains the lines:
+\begin{lstcode}
+ \RequirePackage[T1]{fontenc}
+ \RequirePackage{lmodern}
+\end{lstcode}
+ But now, you want to use
+ X\kern-.125em\lower.5ex\hbox{\reflectbox{E}}\LaTeX{} oder Lua\LaTeX{} the
+ first time. In this case loading of \Package{fontenc} wouldn't be a good
+ suggestion and Latin-Modern would be the default font of the recommended
+ package \Package{fontspec}. Because of this you want to prevent both
+ packages from being loaded. This may be done, loading the class like this:
+\begin{lstcode}
+ \RequirePackage{scrlfile}
+ \PreventPackageFromLoading{fontenc,lmodern}
+ \documentclass{firmenci}
+\end{lstcode}
+\end{Example}
+The example above also shows, that package \Package{scrlfile} may be loaded
+before the class. In this case \Macro{RequirePackage}\IndexCmd{RequirePackage}
+has to be used, because \Macro{usepackage} before \Macro{documentclass} is not
+permitted.%
+%
+\EndIndex{Cmd}{PreventPackageFromLoading}
+
+\begin{Declaration}
+ \Macro{StorePreventPackageFromLoading}\Parameter{\Macro{command}}\\
+ \Macro{ResetPreventPackageFromLoading}
+\end{Declaration}
+\BeginIndex{Cmd}{StorePreventPackageFromLoading}%
+\BeginIndex{Cmd}{ResetPreventPackageFromLoading}%
+\Macro{StorePreventPackageFromLoad}\ChangedAt{v3.08}{\Package{scrlfile}}
+defines \Macro{command} to be the current list of packages, that should be
+prevented from being loaded. In opposite to this,
+\Macro{ResetPreventPackageFromLoading}\ChangedAt{v3.08}{\Package{scrlfile}}
+resets the list of packages, that should be prevented from being loaded. After
+\Macro{ResetPreventPackageFromLoading} all packages may be loaded again.
+\begin{Example}
+ Assumed, you really need a package inside your own package and you want the
+ user inhibit to prevent loading of that package with
+ \Macro{PreventPackageFromLoading}\IndexCmd{PreventPackageFromLoading}. Because
+ of this, you reset the package preventing list before loading the package:
+\begin{lstcode}
+ \ResetPreventPackageFromLoading
+ \RequirePackage{foo}
+\end{lstcode}
+ Unfortunately the complete prevention list of the user would be lost after
+ that. To avoid this, you first store the list and restore it at the end:
+\begin{lstcode}
+ \newcommand*{\Users@PreventList}{}%
+ \StorePreventPackageFromLoading\Users@PreventList
+ \ResetPreventPackageFromLoading
+ \RequirePackage{foo}
+ \PreventPackageFromLoading{\Users@PreventList}
+\end{lstcode}
+ Please\textnote{Attention!} note, that
+ \Macro{StorePreventPackageFromLoading} would define
+ \Macro{Users@PreventList} even if it already has been defined before. In other
+ words: \Macro{StorePreventPackageFromLoading} overwrites existing
+ \Macro{command} definitions without care. Because of this,
+ \Macro{newcommand*} has been used in the example to get an error message, if
+ \Macro{Users@PreventList} has already been defined.
+\end{Example}
+At this point please note, that everybody who manipulates the list, that has
+been stored using \Macro{StorePreventPackageFromLoading} is responsible for
+the correct restorability. For example the list elements must be separated by
+comma, must not contain white space or group braces, and must be fully
+expandable.
+%
+\EndIndex{Cmd}{ResetPreventPackageFromLoading}%
+\EndIndex{Cmd}{StorePreventPackageFromLoading}%
+%
\EndIndex{Package}{scrlfile}
+\endinput
+
%%% Local Variables:
%%% mode: latex
-%%% coding: iso-latin-1
+%%% mode: flyspell
+%%% ispell-local-dictionary: "english"
+%%% coding: us-ascii
%%% TeX-master: "../guide"
%%% End:
+
+% LocalWords: restorability