summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/source-doc/english/scrlfile.tex
blob: a01a4a0035a189df4b35538c4d86d5f4652a5cbd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
% ======================================================================
% scrlfile.tex
% Copyright (c) Markus Kohm, 2001-2018
%
% 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-2018
%
% 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: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $
                  KOMA-Script guide (chapter: scrlfile)]
\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen}

% Date of the translated German file: 2018-02-15

\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}


\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}\Parameter{commands}%
  \Macro{AfterFile}\Parameter{file}\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 features, \Package{scrlfile} redefines the well-known
\LaTeX{} command \Macro{InputIfFileExists}. If this command does not have the
expected definition, \Package{scrlfile} issues a warning. This occurs in case
the command is changed in future \LaTeX{} versions or has already been
redefined by another package.

\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}\Parameter{commands}%
  \Macro{BeforePackage}\Parameter{package}\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}.%
%
\EndIndexGroup


\begin{Declaration}
  \Macro{AfterClass}\Parameter{class}\Parameter{commands}%
  \Macro{AfterClass*}\Parameter{class}\Parameter{commands}%
  \Macro{AfterClass+}\Parameter{class}\Parameter{commands}%
  \Macro{AfterClass!}\Parameter{class}\Parameter{commands}%
  \Macro{AfterAtEndOfClass}\Parameter{class}\Parameter{commands}%
  \Macro{AfterPackage}\Parameter{package}\Parameter{commands}%
  \Macro{AfterPackage*}\Parameter{package}\Parameter{commands}%
  \Macro{AfterPackage+}\Parameter{package}\Parameter{commands}%
  \Macro{AfterPackage!}\Parameter{package}\Parameter{commands}%
  \Macro{AfterAtEndOfPackage}\Parameter{package}\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.

The\important[i]{\Macro{AfterClass+}\\\Macro{AfterPackage+}}
plus\ChangedAt{v3.09}{\Package{scrlfile}} version executes the
\PName{commands} after the class or package has been completely loaded. This
behaviour differs from that of the starred version only if you use the command
when the class or package has begun loading but has not yet finished. If the
class or package has not finished loading, the \PName{commands} will always be
executed before the commands in \Macro{AtEndOfClass} or
\Macro{AtEndOfPackage}.

If\important[i]{\Macro{AfterClass!}\\\Macro{AfterPackage!}} a class uses
\Macro{AtEndOfClass} or a package uses \Macro{AtEndOfPackage} to execute
commands after the class of package file has been loaded completely, and
if you want to execute \PName{commands} after these deferred
commands have been executed, you can use the exclamation-mark versions
\Macro{AfterClass!}\ChangedAt{v3.09}{\Package{scrlfile}} or
\Macro{AfterPackage!}.

If\important[i]{\Macro{AfterAtEndOfClass}\\\Macro{AfterAtEndOfPackage}} you
want to execute the \PName{commands} only when the class or package is loaded
later and outside the context of that class or package, you can use
\Macro{AfterAtEndOfClass}\ChangedAt{v3.09}{\Package{scrlfile}} for classes and
\Macro{AfterAtEndOfPackage} for packages.

\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:
% CORRECTED MESSAGE:
%        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}%
\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 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\ChangedAt{v2.96}{\Package{scrlfile}} command 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}.

\begin{Example}
  You want to input the \File{\Macro{jobname}.xua} file instead of the
  \File{\Macro{jobname.aux}} file. To do this, you use
\begin{lstcode}
  \ReplaceInput{\jobname.aux}{\jobname.xua}
\end{lstcode}
  If additionally you replace \File{\Macro{jobname}.xua} by
  \File{\Macro{jobname}.uxa} using
\begin{lstcode}
  \ReplaceInput{\jobname.xua}{\jobname.uxa}
\end{lstcode}
  then \File{\Macro{jobname}.aux} will also be replaced by
  \File{\Macro{jobname}.uxa}. In this way, you can process the whole
  replacement chain.

  However, a replacement that results in a loop such as
\begin{lstcode}
  \ReplaceInput{\jobname.aux}{\jobname.xua}
  \ReplaceInput{\jobname.xua}{\jobname.aux}
\end{lstcode}
  will cause a \emph{stack size 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. But \LaTeX{} would recognize that the requested
file name does not match the name of the package or class. You can find a
solution for this problem below.%
\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. Doing so would result in a \LaTeX{} warning about
mismatched class or package names. Real errors are also possible if a class or
package is loaded under an incorrect file name.
\begin{Example}
  You replace the \Package{scrpage2} package with its official successor,
  \Package{scrlayer-scrpage}, by using
\begin{lstcode}[escapechar=\$]
  \ReplaceInput{scrpage2.sty}{scrlayer-scrpage.sty}$\textnote{Do not try this!}$
\end{lstcode}
  Loading \Package{scrpage2} will then lead to the following warning:
\begin{lstcode}
  LaTeX warning: You have requested `scrpage2',
                 but the package provides `scrlayer-scrpage'.
\end{lstcode}
  Users may be greatly confused by such a warning because they requested not
  \Package{scrlayer-scrpage} but \Package{scrpage2}, which was replaced by
  \Package{scrlayer-scrpage}.
\end{Example}
One solution to this problem is to use \Macro{ReplaceClass} or
\Macro{ReplacePackage} instead of \DescRef{\LabelBase.cmd.ReplaceInput}. 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. However, you can
declare such missing options using \DescRef{\LabelBase.cmd.BeforeClass} or
\DescRef{\LabelBase.cmd.BeforePackage}.

\begin{Example}
  Suppose you want to replace the \Package{oldfoo} package with the
  \Package{newfoo} package when the former package is loaded. You can do this with
\begin{lstcode}
  \ReplacePackage{oldfoo}{newfoo}
\end{lstcode}
  Suppose the old package provides an \Option{oldopt} option, but the new
  package does not. With
\begin{lstcode}
  \BeforePackage{newfoo}{%
    \DeclareOption{oldopt}{%
      \PackageInfo{newfoo}%
                  {option `oldopt' not supported}%
    }}%
\end{lstcode}
  you can declare this missing option for the \Package{newfoo} package. This
  avoids an error message when the \Package{oldfoo} package is loaded with the
  option that is unsupported by \Package{newfoo}.

  If, on the other hand, the \Package{newfoo} package supports a
  \Option{newopt} option that should be used instead of the \Option{oldopt}
  option, you can also achieved this:
\begin{lstcode}
  \BeforePackage{newfoo}{%
    \DeclareOption{oldopt}{%
      \ExecuteOptions{newopt}%
    }}%
\end{lstcode}
  You can even specify different default options that apply when loading the
  new package:
\begin{lstcode}
  \BeforePackage{newfoo}{%
    \DeclareOption{oldopt}{%
      \ExecuteOptions{newopt}%
    }%
    \PassOptionsToPackage{newdefoptA,newdefoptB}%
                         {newfoo}%
  }
\end{lstcode}
  or directly:
\begin{lstcode}
  \BeforePackage{newfoo}{%
    \DeclareOption{oldopt}{%
      \ExecuteOptions{newopt}%
    }%
  }%
  \PassOptionsToPackage{newdefoptA,newdefoptB}%
                       {newfoo}%
\end{lstcode}
  Note that in the last example, the call to \Macro{PassOptionsToPackage}
  occurs not within but after \Macro{BeforePackage}
\end{Example}

Of course, to replace classes, you must load \Package{scrlfile} before the
class using \Macro{RequirePackage} instead of \Macro{usepackage}.
%
\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
%%% mode: flyspell
%%% ispell-local-dictionary: "english"
%%% coding: us-ascii
%%% TeX-master: "../guide"
%%% End: