path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex

% ======================================================================
% scrlfile.tex
% Copyright (c) Markus Kohm, 2001-2013
%
% 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.
% ----------------------------------------------------------------------
% scrlfile.tex
% Copyright (c) Markus Kohm, 2001-2013
%
% 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 scrlfile of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------------
%
% Kapitel ueber scrlfile in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ============================================================================

\KOMAProvidesFile{scrlfile.tex}
                 [$Date: 2013-12-13 12:11:01 +0100 (Fri, 13 Dec 2013) $
                  KOMA-Script guide (chapter: scrlfile)]
\translator{Gernot Hassenpflug\and Markus Kohm}

% Date of translated german file: 2013/11/24

\chapter{Control Package Dependencies with \Package{scrlfile}}
\labelbase{scrlfile}

\BeginIndex{Package}{scrlfile}

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}

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.
  
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.
  
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}
\label{sec:scrlfile.macros}

\Package{scrlfile} can execute actions both before and after the
loading of files. In the commands used to do this, distinctions are
made made between general files, classes, and packages.

\begin{Declaration}
  \Macro{BeforeFile}\Parameter{file}\Parameter{instructions}\\
  \Macro{AfterFile}\Parameter{file}\Parameter{instructions}
\end{Declaration}%
\BeginIndex{Cmd}{BeforeFile}%
\BeginIndex{Cmd}{AfterFile}%
The macro \Macro{BeforeFile} ensures that \PName{instructions} are
only executed before the next time \PName{file} is loaded.
\Macro{AfterFile} works in a similar fashion, and the
\PName{instructions} will be executed only after the \PName{file} has
been loaded.  If \PName{file} is never loaded then the
\PName{instructions} will never be executed.

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{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}%

\begin{Declaration}
  \Macro{BeforeClass}\Parameter{class}\Parameter{instructions}\\
  \Macro{BeforePackage}\Parameter{package}\Parameter{instructions}
\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.%
%
\EndIndex{Cmd}{BeforeClass}%
\EndIndex{Cmd}{BeforePackage}%

\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{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\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 has not 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 has not 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{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{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{lstcode}

  All the rest can now be left to \Macro{AfterFile}.
\begin{lstcode}
  \documentclass{article}
  \usepackage{scrlfile}
  \AfterFile{hdvips.def}{\hypersetup{linktocpage}}
  \AfterFile{hypertex.def}{\hypersetup{linktocpage}}
  \usepackage{hyperref}
  \begin{document}
  \listoffigures
  \clearpage
  \begin{figure}
    \caption{This is an example for a fairly long figure caption, but
      which does not employ the optional caption argument that would
      allow one to write a short caption in the list of figures.}
  \end{figure}
  \end{document}
\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 was not 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}
would not 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} would not 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}.

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
does not 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 does not. 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}%

\begin{Declaration}
  \Macro{UnReplaceInput}\Parameter{file name}\\
  \Macro{UnReplacePackage}\Parameter{package}\\
  \Macro{UnReplaceClass}\Parameter{class}%
\end{Declaration}
\BeginIndex{Cmd}{UnReplaceInput}%
\BeginIndex{Cmd}{UnReplacePackage}%
\BeginIndex{Cmd}{UnReplaceClass}%
A\ChangedAt{v3.12}{\Package{scrlfile}} replacement definition can be removed
using one of these commands. The replacement definition of a input file should
be removed using \Macro{UnReplaceInput}, the replacement definition of a
package should be removed using \Macro{UnReplacePackage}, and the replacement
definition of a class should be removed using \Macro{UnReplaceClass}.%
\EndIndex{Cmd}{UnReplaceClass}%
\EndIndex{Cmd}{UnReplacePackage}%
\EndIndex{Cmd}{UnReplaceInput}%


\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}\OParameter{instead code}%
  \Parameter{package list}\\
  \Macro{PreventPackageFromLoading*}\OParameter{instead code}%
  \Parameter{package list}
\end{Declaration}
\BeginIndex{Cmd}{PreventPackageFromLoading}%
\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} would not 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.

If \PName{package list} is empty or contains a package, that already has been
loaded, \Macro{PreventPackageFromLoading} will warn. If you'd prefer an
info\ChangedAt{v3.12}{\Package{scrlfile}} at the log-file only, you may use
\Macro{PreventPackageFromLoading*} instead.

The optional argument\ChangedAt{v3.12}{\Package{scrlfile}} may be used to
execute code instead of loading the package. But you must not load another
packages or files inside \PName{instead code}. See \Macro{ReplacePackage} in
\autoref{sec:scrlfile.macros} on
\autopageref{desc:scrlfile.cmd.ReplacePackage} for information about replacing
a package by another one. Note also, that the \PName{instead code} will be
executed several times, if you try to load the package more than once!%
\EndIndex{Cmd}{PreventPackageFromLoading*}%
\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.

Please note\textnote{Attention!}, that \Macro{ResetPreventPackageFromLoading}
does not clean the \PName{instead code} of a package. Only the execution is not
done as long as the prevention is not reactivated.%
\EndIndex{Cmd}{ResetPreventPackageFromLoading}%
\EndIndex{Cmd}{StorePreventPackageFromLoading}%

\begin{Declaration}
  \Macro{UnPreventPackageFromLoading}\Parameter{package list}\\
  \Macro{UnPreventPackageFromLoading*}\Parameter{package list}
\end{Declaration}
\BeginIndex{Cmd}{UnPreventPackageFromLoading}%
\BeginIndex{Cmd}{UnPreventPackageFromLoading*}%
Instead\ChangedAt{v3.12}{\Package{scrlfile}} of resetting the whole list of
packages, that should prevented from being loaded, you may also remove some
packages from that list. The star version of the command does also clean the
\PName{instead code}. So reactivation of the prevent package list, e.\,g.,
from a stored one, will not reactivate the \PName{instead code} of the
packages.%
%
\begin{Example}
  Assuming, you want to prevent a package \Package{foo} from being loaded, but
  you do not want an already stored \PName{instead code} to be
  executed. Instead of that code, you're own \PName{instead code} should be
  executed. You can do this:
\begin{lstcode}
  \UnPreventPackageFromLoading*{foo}
  \PreventPackageFromLoading[\typeout{Stattdessencode}]{foo}
\end{lstcode}
  For \Macro{UnPreventPackageFromLoading} it does not matter whether or not
  the package has been prevented from being loaded before.

  Surely you can use the command also to remove only the \PName{instead code}
  of all packages:
\begin{lstcode}
  \StorePreventPackageFromLoading\TheWholePreventList
  \UnPreventPackageFromLoading*{\TheWholePreventList}
  \PreventPackageFromLoading{\TheWholePreventList}
\end{lstcode}
  In this case the packages, that has been prevented from being loaded, are
  still prevented from being loaded, but their \PName{instead code} has been
  cleaned and will not be executed any longer.%
\end{Example}%
\EndIndex{Cmd}{UnPreventPackageFromLoading*}%
\EndIndex{Cmd}{UnPreventPackageFromLoading}%
%
\EndIndex{Package}{scrlfile}

\endinput

%%% Local Variables: 
%%% mode: latex
%%% mode: flyspell
%%% ispell-local-dictionary: "english"
%%% coding: us-ascii
%%% TeX-master: "../guide"
%%% End: 

% LocalWords:  restorability