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