diff options
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/scrlfile-en.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/doc/scrlfile-en.tex | 678 |
1 files changed, 678 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/scrlfile-en.tex b/macros/latex/contrib/koma-script/doc/scrlfile-en.tex new file mode 100644 index 0000000000..ece18e8881 --- /dev/null +++ b/macros/latex/contrib/koma-script/doc/scrlfile-en.tex @@ -0,0 +1,678 @@ +% ====================================================================== +% scrlfile-en.tex +% Copyright (c) Markus Kohm, 2001-2022 +% +% 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.md. +% ====================================================================== +% +% Chapter about scrlfile of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrlfile-en.tex} + [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $ + KOMA-Script guide (chapter: scrlfile)] +\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen} + +\chapter{Controlling Package Dependencies with \Package{scrlfile}} +\labelbase{scrlfile} +\BeginIndexGroup +\BeginIndex{Package}{scrlfile} + +The introduction of \LaTeXe{} in 1994 brought many changes in the handling of +\LaTeX{} extensions. The package author today has a whole series of macros +available to determine if another package or class has been loaded and whether +specific options are being used. The package author can even load other +packages or specify certain options in case 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} +\seclabel{dependency} +%\begin{Explain} +More and more often, different packages either newly define or redefine the +same macro. In such a case, the order in which a package is loaded becomes +very important. Sometimes, users find it very difficult to understand the +resulting behaviour. Sometimes it is necessary to react in a specific way when +another package is loaded. + +As a simple example, consider loading the \Package{longtable} package with a +\KOMAScript{} document class. The \Package{longtable} package defines its own +table captions. These are perfectly suited to the standard classes, but they +do not match the default settings for \KOMAScript{} captions, nor do they +react to the relevant configuration options. 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. + +Previously, the only way to solve this problem was to delay the redefinition +until the beginning of the document using \Macro{AtBeginDocument}. However, if +users want to change the relevant commands themselves, they should do so in +the preamble of the document. But this is impossible because \KOMAScript{} +will overwrite the users' definitions at \Macro{begin}\PParameter{document}. +They would also need to perform the redefinition with \Macro{AtBeginDocument}. + +But \KOMAScript{} does not actually need to wait for +\Macro{begin}\PParameter{document} to redefine the macros. It would be +sufficient to postpone the redefinition until after the \Package{longtable} +package has been loaded. Unfortunately, the \LaTeX{} kernel does not define +necessary commands. The \Package{scrlfile} package provides a remedy for this +problem. + +It is also conceivable that you would like to save the definition of a macro +in a temporary macro before a package is loaded and restore it after the +package has been loaded. The \Package{scrlfile} package allows this, too. + +The use of \Package{scrlfile} is not limited to package dependencies. +Dependencies can also be considered for any other file. For example, you can +ensure that loading the not unimportant file \File{french.ldf} automatically +leads to a warning. + +Although the package is particularly of interest for package authors, there +are also applications for normal \LaTeX{} users. Therefore, this chapter +gives examples for both groups. +%\end{Explain} + +\begin{Declaration} + \Option{withdeprecated} +\end{Declaration} +With\ChangedAt{v3.32}{\Package{scrlfile}} \LaTeX{} 2020-10-01 a completely new +hook mechanism is available. Instead of redefining macros of the \LaTeX{} +kernel, \Package{scrlfile} 3.32 and newer makes use of it. For this purpose it +loads the internal package +\Package{scrfile-hook}\IndexPackage[indexmain]{scrlfile-hook}. With older +\LaTeX{} versions, depending\ChangedAt{v3.35}{\Package{scrlfile}} on the +kernel version, either the internal package +\Package{scrlayer-hook-3.34}\IndexPackage[indexmain]{scrlfile-hook-3.34} or +\Package{scrlayer-patcholdkernel}% +\IndexPackage[indexmain]{scrlfile-patcholdkernel} is used. However, since it +was not possible to achieve identical functionality with the new mechanism in +\LaTeX, some commands of \Package{scrlfile} were marked as +deprecated. Furthermore, the opportunity was taken to organize the +proliferation of command variants. If a user uses a class or package that is +still based on the commands that are no longer supported by +\Package{scrlfile}, the package \Package{scrlfile} can be loaded with +\begin{lstcode} + \RequirePackage[withdeprecated]{scrlfile} +\end{lstcode} +before loading the class. \Package{scrlfile} then additionally emulates some +of the deprecated commands in a way that should be sufficient in most +cases. In any case, the author of the corresponding class or package should be +informed, so that he or she can make an adaptation to the current version of +\Package{scrlfile} or directly to \LaTeX{} from version 2021-11-15.% +% +\EndIndexGroup + +\section{Actions Before and After Loading} +\seclabel{macros} + +The \Package{scrlfile} package can execute actions both before and after +loading files. The commands used to do so distinguish between ordinary files, +classes, and packages. + +\begin{Declaration} + \Macro{BeforeFile}\Parameter{file}\OParameter{label}\Parameter{commands}% + \Macro{AfterFile}\Parameter{file}\OParameter{label}\Parameter{commands} +\end{Declaration}% +\Macro{BeforeFile} ensures that the \PName{commands} are executed before the +next time \PName{file} is loaded. \Macro{AfterFile} works in a similar +fashion, and the \PName{commands} will be executed after the \PName{file} has +been loaded. Of course, if \PName{file} is never loaded, the \PName{commands} +will never be executed. For \PName{file}, you should specify any extensions as +part of the file name, as you would with \Macro{input}. + +To implement those featuresfor \LaTeX{} before version 2020-10-01, +\Package{scrlfile-patcholdlatex} redefines the well-known \LaTeX{} command +\Macro{InputIfFileExists}. If this command does not have the expected +definition, \Package{scrlfile-patcholdlatex} issues a warning. This occurs in +case the command has already been redefined by an incompatible package. + +With\ChangedAt{v3.32}{\Package{scrlfile}}\IndexCmd{AddToHook} \LaTeX{} from +version 2020-10-01 on, \Package{scrlfile-hook} uses +\Macro{AddToHook}\PParameter{file/before/\PName{file}}\OParameter{label}\Parameter{commands} +or +\Macro{AddToHook}\PParameter{file/after/\PName{file}}\OParameter{label}\Parameter{commands}. +For more information on the meaning of the optional argument \PName{label}, +please refer to the corresponding manual of the \LaTeX{} core statement +\Macro{AddToHook}. As a rule, the omission of the optional argument is +recommended. With older \LaTeX{} versions this is ignored anyway. + +\LaTeX{} uses the \Macro{InputIfFileExists} command every time it loads a +file. This occurs regardless of whether the file is loaded with +\Macro{include}, \Macro{LoadClass}, \Macro{documentclass}, \Macro{usepackage}, +\Macro{RequirePackage}, or similar commands. Only +\begin{lstcode} + \input foo +\end{lstcode} +loads the file \texttt{foo} without using +\Macro{InputIfFileExists}. You should therefore always use +\begin{lstcode} + \input{foo} +\end{lstcode} +instead. Notice the parentheses surrounding the file name!% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{BeforeClass}\Parameter{class}\OParameter{label}\Parameter{commands}% + \Macro{BeforePackage}\Parameter{package}\OParameter{label}\Parameter{commands} +\end{Declaration}% +These two commands work the same way as \DescRef{\LabelBase.cmd.BeforeFile}. +The only difference is that the \PName{class} or \PName{package} is specified +with its class or package name and not with its file name. That means you +should omit the file extensions \File{.cls} or \File{.sty}. + +Note,\important{Attention!} \Package{scrlfile-hook} also uses \PValue{file} +and not \PValue{class} or \PValue{package} for the hook. This is the only way +to ensure that the execution of the \PName{commands} already takes place in +the context of the class or package. For the meaning of the optional argument +\PName{label} please refer to the \LaTeX{} core statement +\Macro{AddToHook}\IndexCmd{AddToHook}. As a rule, the omission of the optional +argument is recommended. With older \LaTeX{} versions this is ignored anyway.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AfterClass}\Parameter{class}\OParameter{label}\Parameter{commands}% + \Macro{AfterClass*}\Parameter{class}\OParameter{label}\Parameter{commands}% + \Macro{AfterAtEndOfClass}\Parameter{class}\OParameter{label}\Parameter{commands}% + \Macro{AfterAtEndOfClass*}\Parameter{class}\OParameter{label}\Parameter{commands}% + \Macro{AfterPackage}\Parameter{package}\OParameter{label}\Parameter{commands}% + \Macro{AfterPackage*}\Parameter{package}\OParameter{label}\Parameter{commands}% + \Macro{AfterAtEndOfPackage}\Parameter{package}\OParameter{label}\Parameter{commands} + \Macro{AfterAtEndOfPackage*}\Parameter{package}\OParameter{label}\Parameter{commands} +\end{Declaration}% +The \Macro{AfterClass} and \Macro{AfterPackage} commands work much like +\DescRef{\LabelBase.cmd.AfterFile}. The only difference is that the +\PName{class} or \PName{package} is specified with its class or package name +and not with its file name. That means you should omit the file extensions +\File{.cls} or \File{.sty}. + +The\important[i]{\Macro{AfterClass*}\\\Macro{AfterPackage*}} starred versions +function somewhat differently. If the class or package has already been +loaded, they execute the \PName{commands} immediately rather than waiting +until the next time the class or package is loaded. + +However\ChangedAt{v3.09}{\Package{scrlfile}}% +\important[i]{\Macro{AfterAtEndOfClass}\\\Macro{AfterAtEndOfPackage}}, code +whose execution is delayed by \Macro{AtEndOfClass} or \Macro{AtEndOfPackage} +within the class or package is first executed afterwards. In contrast, +\Macro{AfterAtEndOfClass} or \Macro{AfterAtEndOfPackage} ensures that +\PName{commands} are executed after such code. + +Again\ChangedAt{v3.32}{\Package{scrlfile}}% +\important[i]{\Macro{AfterAtEndOfClass*}\\\Macro{AfterAtEndOfPackage*}}, there +are star variants that ensure that \PName{commands} are executed immediately +if the class or package is already completely loaded. If a class or package is +currently loaded, the execution is delayed like in the version without star. + +Note that \Package{scrlfile-hook} uses a \PValue{file/after} hook for +\Macro{AfterClass}, \Macro{AfterPackage} and their star variants. In contrast +\Macro{AfterAtEndOfClass} and its star variant set a \PValue{class/after} hook +and \Macro{AfterAtEndOfPackage} and its star variant set a +\PValue{package/after} hook accordingly. For the meaning of the optional +argument \PName{label} please refer to the \LaTeX{} core statement +\Macro{AddToHook}\IndexCmd{AddToHook}. As a rule, the omission of the optional +argument is recommended. With older \LaTeX{} versions this is ignored anyway. + +\begin{Example} + The following example for class and package authors shows how \KOMAScript{} + itself makes use of the new commands. The class \Class{scrbook} contains the + following: +\begin{lstcode} + \AfterPackage{hyperref}{% + \@ifpackagelater{hyperref}{2001/02/19}{}{% + \ClassWarningNoLine{scrbook}{% + You are using an old version of the hyperref + package!\MessageBreak% + This version has a buggy hack in many + drivers,\MessageBreak% + causing \string\addchap\space to behave + strangely.\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 a way that is incompatible with newer \KOMAScript{} + versions. Newer versions of \Package{hyperref} refrain from making this + change if a newer version of \KOMAScript{} is detected. In case + \Package{hyperref} is loaded at a later stage, \Class{scrbook} ensures that + a check for an acceptable version of \Package{hyperref} is performed + immediately after the package is loaded. If this is not the case, a warning + is issued. + + Elsewhere in three of the \KOMAScript{} classes, you can find the following: +\begin{lstcode} + \AfterPackage{caption2}{% + \renewcommand*{\setcapindent}{% +\end{lstcode} + After loading \Package{caption2}, and only if it has been loaded, + \KOMAScript{} redefines its own \DescRef{maincls.cmd.setcapindent} command. + The exact code of the redefinition is irrelevant. The important thing to + note is that \Package{caption2} takes control of the + \DescRef{maincls.cmd.caption} macro and that therefore the normal definition + of the \DescRef{maincls.cmd.setcapindent} command would have no effect. The + redefinition thus improves interoperability with \Package{caption2}. + + There are also, however, instances where these commands are useful to normal + \LaTeX{} users. For example, suppose you create a document from which you + want to generate both a PostScript file, using \LaTeX{} and dvips, and a PDF + file, using \mbox{pdf{\LaTeX}}. The document should also contain hyperlinks. + In the table of contents, you have entries that span several lines. This is + not a problem for the \mbox{pdf{\LaTeX}} method, since here hyperlinks can + be broken across multiple lines. However, this is not possible with the + \Package{hyperref} driver for dvips or \mbox{hyper{\TeX}}. In this case, you + would like \Package{hyperref} to use the \Option{linktocpage} option. The + decision as to which driver is loaded is made automatically by + \File{hyperref}. + + Everything else can now be left to \DescRef{\LabelBase.cmd.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 of a fairly long figure caption, but + one that does not use the optional caption argument that would + allow you to write a short caption in the list of figures.} + \end{figure} + \end{document} +\end{lstcode} + If either of the \Package{hyperref} drivers \Option{hypertex} or + \Option{dvips} is used, the useful \Package{hyperref} option + \Option{linktocpage} will be set. However, if you create a PDF file + with \mbox{pdf{\LaTeX}}, the option + will not be set because then the \Package{hyperref} driver + \File{hpdftex.def} will be used. This means that neither \File{hdvips.def} + nor \File{hypertex.def} will be loaded. +\end{Example} +\iffalse% Umbruchkorrekturtext (der besser nicht mehr verwendet wird!) + Furthermore\textnote{Hint!}, you can also load \Package{scrlfile} and the + \DescRef{\LabelBase.cmd.AfterFile} command into a private + \File{hyperref.cfg}. In this case, however, you should use + \Macro{RequirePackage} instead of \Macro{usepackage} to load the package + (see \cite{latex:clsguide}). In the example above, the new lines have to be + inserted directly after the \Macro{ProvidesFile} line, that is, immediately + before the \Option{dvips} or \Option{pdftex} options are executed.% +\fi +Incidentally\textnote{Hint!}, you can also load \Package{scrlfile} before +\DescRef{maincls.cmd.documentclass}\IndexCmd{documentclass}. In this case, +however, you should use \Macro{RequirePackage}\IndexCmd{RequirePackage} +instead of \DescRef{maincls.cmd.usepackage} (see \cite{latex:clsguide}).% +\EndIndexGroup + + +\begin{Declaration} + \Macro{BeforeClosingMainAux}\Parameter{commands}% + \Macro{AfterReadingMainAux}\Parameter{commands}% +\end{Declaration}% +These commands differ in one detail from the commands explained previously. +Those commands enable actions before or after loading files. That is not the +case here. Package authors often want to write something to the \File{aux} +file after the last document page has been shipped out. To do so, ignoring the +resulting problems they create, they often use code such as the following: +\begin{lstcode} + \AtEndDocument{% + \if@filesw + \write\@auxout{% + \protect\writethistoaux% + }% + \fi + } +\end{lstcode} +However, this does not really solve the problem. If the last page of the +document has already been shipped out before \Macro{end}\PParameter{document}, +the code above will not result in any output to the \File{aux} file. If you +try to fix this new problem using \Macro{immediate} just before \Macro{write}, +you would have the opposite problem: if the last page has not yet been shipped +out before \Macro{end}\PParameter{document}, \Macro{writethistoaux} would be +written to the \File{aux} file too early. Therefore you often see solutions +like: +\begin{lstcode} + \AtEndDocument{% + \if@filesw + \clearpage + \immediate\write\@auxout{% + \protect\writethistoaux% + }% + \fi + } +\end{lstcode} +However, this solution has the disadvantage that it forces the last page to be +shipped out. A command such as +\begin{lstcode} + \AtEndDocument{% + \par\vspace*{\fill}% + Note at the end of the document.\par + } +\end{lstcode} +will no longer cause the note to appear beneath the text of the last real page +of the document but at the end of one additional page. Furthermore, +\Macro{writethistoaux} will again be written to the \File{aux} file one page +too early. + +The best solution for this problem would be if you could write directly to the +\File{aux} file immediately after the final \DescRef{maincls.cmd.clearpage} +that is part of \Macro{end}\PParameter{document} but before closing the +\File{aux} file. This is the purpose of \Macro{BeforeClosingMainAux}: +\begin{lstcode} + \BeforeClosingMainAux{% + \if@filesw + \immediate\write\@auxout{% + \protect\writethistoaux% + }% + \fi + } +\end{lstcode} +This will be successful even if the final \DescRef{maincls.cmd.clearpage} +inside of \Macro{end}\PParameter{document} does not actually ship out any page +or if \DescRef{maincls.cmd.clearpage} is used within an \Macro{AtEndDocument} +command. + +However, there one important limitation using \Macro{BeforeClosingMainAux}: +you should not use any typesetting commands inside the \PName{commands} of +\Macro{BeforeClosingMainAux}! If you ignore this restriction, the result is +just as unpredictable as the results of the problematic suggestions above that +use \Macro{AtEndDocument}. + +The \Macro{AfterReadingMainAux}\ChangedAt{v3.03}{\Package{scrlfile}} command +actually executes the \PName{commands} after closing and reading the +\File{aux} file inside \Macro{end}\PParameter{document}. This is only useful +in a few very rare cases, for example to write statistical information to the +\File{log} file which is valid only after reading the \File{aux} file, or to +implement additional \emph{rerun} requests. Typesetting commands are even more +dangerous inside these \PName{commands} than inside the argument of +\Macro{BeforeClosingMainAux}.% +% +\EndIndexGroup + + +\section{Replacing Files at Input} +\seclabel{replace} + +The previous sections in this chapter have explained commands to perform +actions before or after loading a particular file, package, or class. You can +also use \Package{scrlfile} to input a completely different file than the one +that was requested. + +\begin{Declaration} + \Macro{ReplaceInput}\Parameter{original file}% + \Parameter{replacement file}% +\end{Declaration}% +This command\ChangedAt{v2.96}{\Package{scrlfile}} defines a replacement +for the file specified in the first argument, \PName{original file}. If +\LaTeX{} is instructed to load this file, the \PName{replacement file} will be +loaded instead. The replacement-file definition affects all files loaded using +\Macro{InputIfFileExists}, whether they are loaded by the user or internally +by \LaTeX{}. To do so, \Package{scrlfile} redefines \Macro{InputIfFileExists}. + +When\ChangedAt{v3.32}{\Package{scrlfile}} using a \LaTeX{} version up to +2020-04-01, the package \Package{scrlfile-patcholdlatex} must redefine the +\Macro{InputIfFileExists} statement for this purpose. When using \LaTeX{} from +version 2020-10-01 on, \Package{scrlfile-hook} uses the internal \LaTeX{} +statement \Macro{declare@file@substitution}. The \LaTeX{} team asks to make +such a substitution only if there is no other way to achieve the desired +result, for example if such a substitution is indispensable to maintain +compatibility and if the \PName{replacement file} provides the same +functionality. + +\begin{Example} + You want to input the \File{\Macro{jobname}.tol} file instead of the + \File{\Macro{jobname.lot}} file. To do this, you use +\begin{lstcode} + \ReplaceInput{\jobname.tol}{\jobname.lot} +\end{lstcode} + If additionally you replace \File{\Macro{jobname}.tol} by + \File{\Macro{jobname}.tlo} using +\begin{lstcode} + \ReplaceInput{\jobname.tol}{\jobname.tlo} +\end{lstcode} + then \File{\Macro{jobname}.tol} will also be replaced by + \File{\Macro{jobname}.tlo}. In this way, you can process the whole + replacement chain. + + However, a replacement that results in a loop such as +\begin{lstcode} + \ReplaceInput{\jobname.lot}{\jobname.tol} + \ReplaceInput{\jobname.tol}{\jobname.lot} +\end{lstcode} + will cause an error. So it is not possible to replace + a file that has already been replaced once by itself again. +\end{Example} + +In theory, it would also be possible to use this command to replace one +package or class with another .However, it is recommended to use the following +instructions for replacing a package or class. For older \LaTeX{} versions +this is even mandatory.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ReplaceClass}\Parameter{original class}% + \Parameter{replacement class}% + \Macro{ReplacePackage}\Parameter{original package}% + \Parameter{replacement package}% +\end{Declaration}% +You\ChangedAt{v2.96}{\Package{scrlfile}}\textnote{Attention!} should never +replace a class or package using the \DescRef{\LabelBase.cmd.ReplaceInput} +command described above. Instead, \Macro{ReplacePackage} should be used for +package replacements and \Macro{ReplaceClass} for class replacements. Note +that in this case, as with \Macro{documentclass} and \Macro{usepackage}, you +should give the name of the class or package and not the complete file name. + +The replacement class works for all classes loaded with +\Macro{documentclass}, \Macro{LoadClassWithOptions}, or \Macro{LoadClass}. The +replacement package works for all packages loaded with +\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 that would +have been passed to the \PName{original class} or \PName{original package}. If +you replace a class or package with one that does not support a requested +option, you will receive the usual warnings and errors. + +Of course, to replace classes, you must load \Package{scrlfile} before the +class using \Macro{RequirePackage} instead of \Macro{usepackage}. + +When\ChangedAt{v3.32}{\Package{scrlfile}} using a \LaTeX{} version up to +2020-04-01 the package \Package{scrlfile-patcholdlatex} must redefine the +internal statements \Macro{@onefilewithoptions} and +\Macro{@loadwithoptions}. When using \LaTeX{} from version 2020-10-01 on, +\Package{scrlfile-hook} uses the internal \LaTeX{} statement +\Macro{declare@file@substitution}. The \LaTeX{} Team asks to perform such a +substitution only if there is no other way to achieve the desired result, +e.g. if such a substitution is indispensable to maintain compatibility and the +\PName{replacement package} or \PName{replacement class} provides the same +functionality.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{UnReplaceInput}\Parameter{file name}% + \Macro{UnReplacePackage}\Parameter{package}% + \Macro{UnReplaceClass}\Parameter{class}% +\end{Declaration} +You\ChangedAt{v3.12}{\Package{scrlfile}} can also remove a replacement. You +should remove the replacement definition for an input file using +\Macro{UnReplaceInput}, for a package using \Macro{UnReplacePackage}, and for +a class using \Macro{UnReplaceClass}.% +\EndIndexGroup + + +\section{Preventing File Loading} +\seclabel{prevent} + +Classes\ChangedAt{v3.08}{\Package{scrlfile}} and packages written for use +within companies or academic institutions often load many packages only +because users need them frequently, not because they are required by the class +or package itself. If a problem occurs with one of these automatically loaded +packages, you somehow have to keep the problematic package from being loaded. +Once again, \Package{scrlfile} provides a simple solution. + +\begin{Declaration} + \Macro{PreventPackageFromLoading}\OParameter{alternate code}% + \Parameter{package list}% + \Macro{PreventPackageFromLoading*}\OParameter{alternate code}% + \Parameter{package list} +\end{Declaration} +Calling this command\ChangedAt{v3.08}{\Package{scrlfile}} before loading a +package with \Macro{usepackage}\IndexCmd{usepackage}, +\Macro{RequirePackage}\IndexCmd{RequirePackage}, or +\Macro{RequirePackageWithOptions}\IndexCmd{RequirePackageWithOptions} +effectively prevents the package from being loaded if it is found in the the +\PName{package list}. +% +\begin{Example} + Suppose you work at a company where all documents are created using Latin + Modern. The company class, \Class{compycls}, therefore contains these lines: +\begin{lstcode} + \RequirePackage[T1]{fontenc} + \RequirePackage{lmodern} +\end{lstcode} + But now, for the first time, you want to use \XeLaTeX{} or Lua\LaTeX{}. + Since the recommended \Package{fontspec} package uses Latin Modern as the + default font anyway, and loading \Package{fontenc} would not be a good idea, + you want to prevent both packages from being loaded. Therefore, you load the + class in your own document as follows: +\begin{lstcode} + \RequirePackage{scrlfile} + \PreventPackageFromLoading{fontenc,lmodern} + \documentclass{firmenci} +\end{lstcode} +\end{Example} +The example above also shows that you can load \Package{scrlfile} before the +class. In this case, you must use +\Macro{RequirePackage}\IndexCmd{RequirePackage} because \Macro{usepackage} +before \Macro{documentclass} is not permitted. + +If you specify an empty \PName{package list} or if it contains a package that +has already been loaded, \Macro{PreventPackageFromLoading} issues a warning, +while\ChangedAt{v3.12}{\Package{scrlfile}} \Macro{PreventPackageFromLoading*} +merely writes a note to the log file only. + +You\ChangedAt{v3.12}{\Package{scrlfile}} can use the optional argument to +execute code instead of loading the package. But you cannot load any other +packages or files inside \PName{alternate code}. To load another package, see +\DescRef{\LabelBase.cmd.ReplacePackage} in \autoref{sec:scrlfile.macros} on +\DescPageRef{\LabelBase.cmd.ReplacePackage}. Note also that the +\PName{alternate code} will be executed several times if you try to load the +package more than once!% +\EndIndexGroup + + +\begin{Declaration} + \Macro{StorePreventPackageFromLoading}\Parameter{\textMacro{command}}% + \Macro{ResetPreventPackageFromLoading} +\end{Declaration} +\Macro{StorePreventPackageFromLoad}\ChangedAt{v3.08}{\Package{scrlfile}} +defines \Macro{command} to be the current list of packages that should not be +loaded. In contrast, +\Macro{ResetPreventPackageFromLoading}\ChangedAt{v3.08}{\Package{scrlfile}} +resets the list of packages that should not be loaded. After +\Macro{ResetPreventPackageFromLoading}, you can load all packages again. +\begin{Example} + Suppose you need to load a package inside another package and you do not + want the user to be able to prevent that package from being loaded with + \DescRef{\LabelBase.cmd.PreventPackageFromLoading}% + \IndexCmd{PreventPackageFromLoading}. So you reset the do-not-load list + before you load this package: +\begin{lstcode} + \ResetPreventPackageFromLoading + \RequirePackage{foo} +\end{lstcode} + Unfortunately, from this point on the user's entire do-not-load list would + be lost. To avoid this, you first store the list and then restore it later: +\begin{lstcode} + \newcommand*{\Users@PreventList}{}% + \StorePreventPackageFromLoading\Users@PreventList + \ResetPreventPackageFromLoading + \RequirePackage{foo} + \PreventPackageFromLoading{\Users@PreventList} +\end{lstcode} + Note\textnote{Attention!} that \Macro{StorePreventPackageFromLoading} + defines the \Macro{Users@PreventList} macro even if it has already been + defined. In other words, calling \Macro{StorePreventPackageFromLoading} + overwrites existing \Macro{command} definitions without checking. Therefore + this example uses \Macro{newcommand*} to get an error message if + \Macro{Users@PreventList} has already been defined. +\end{Example} +Note that when you manipulate the list stored by +\Macro{StorePreventPackageFromLoading}, you are responsible for making sure it +can be restored. For example, the list elements must be separated by comma, +must not contain white space or group braces, and must be fully expandable. + +Also note\textnote{Attention!}, that \Macro{ResetPreventPackageFromLoading} +does not clear the \PName{alternate code} for a package. But this code +will not be executed so long as the package is not added again to the +do-not-load list.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{UnPreventPackageFromLoading}\Parameter{package list}% + \Macro{UnPreventPackageFromLoading*}\Parameter{package list} +\end{Declaration} +Instead\ChangedAt{v3.12}{\Package{scrlfile}} of completely resetting the list +of packages that should not be loaded, you can also specify individual +packages to remove from the list. The starred version of the command also +deletes the \PName{alternate code}. For example, restoring packages to the +do-not-load list from a stored list will not reactivate their \PName{alternate +code} in this case.% +% +\begin{Example} + Suppose you want to prevent a \Package{foo} package from being loaded, but + you do not want to execute any outdated \PName{alternate code} that may + exist. Instead, only your new \PName{alternate code} should be executed. You + can do this as follows: +\begin{lstcode} + \UnPreventPackageFromLoading*{foo} + \PreventPackageFromLoading[\typeout{alternate code}]{foo} +\end{lstcode} + For the \Macro{UnPreventPackageFromLoading} command, it does not matter + whether or not the package has been prevented from being loaded before. + + Of course you can also use the command to indirectly delete the + \PName{alternate code} of all packages: +\begin{lstcode} + \StorePreventPackageFromLoading\TheWholePreventList + \UnPreventPackageFromLoading*{\TheWholePreventList} + \PreventPackageFromLoading{\TheWholePreventList} +\end{lstcode} + In this case the packages that have been prevented from being loaded are + still prevented from being loaded, but their \PName{alternate code} has been + deleted and will no longer be executed.% +\end{Example}% +\EndIndexGroup +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "scrguide-en.tex" +%%% coding: utf-8 +%%% ispell-local-dictionary: "en_GB" +%%% eval: (flyspell-mode 1) +%%% End: |