summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex
blob: c680b1ee92c7350e6d2f88af7c7e8ccb8a62c478 (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
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
% ======================================================================
% scrlfile.tex
% Copyright (c) Markus Kohm, 2001-2013
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX 
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of all files listed in manifest.txt.
% ----------------------------------------------------------------------
% scrlfile.tex
% Copyright (c) Markus Kohm, 2001-2013
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
% Die neuste Version dieser Lizenz ist
%   http://www.latex-project.org/lppl.txt
% und Version 1.3c ist Teil aller Verteilungen von LaTeX
% Version 2005/12/01 oder spaeter und dieses Werks.
%
% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained"
% (allein durch den Autor verwaltet).
%
% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm.
% 
% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien.
% ======================================================================
%
% Chapter about scrlfile of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------------
%
% Kapitel ueber scrlfile in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ============================================================================

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

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

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

\BeginIndex{Package}{scrlfile}

The introduction of {\LaTeXe} in 1994 brought many changes in the
handling of {\LaTeX} extensions.  Today the package author has many
macros available to determine if another package or class is
employed and whether specific options are used.  The author can load
other packages or can specify options in the the case that the
package is loaded later.  This has led to the expectation that the
order in which package are loaded would not be important.  Sadly
this hope has not been fulfilled.

\section{About Package Dependencies}
\label{sec:scrlfile.dependency}

More and more frequently, different packages either newly define or
redefine the same macro again.  In such a case the order in which a
package is loaded becomes very important.  For the user it sometimes
becomes very difficult to understand the behaviour, and in some
cases the user wants only to react to the loading of a package. This
too is not really a simple matter.

Let us take the simple example of loading the package \Package{longtable} with
a {\KOMAScript} document class.  The \Package{longtable} package defines table
captions very well suited to the standard classes, but the captions are
totally unsuitable for documents using {\KOMAScript} and also do not react to
the options of the provided configuration commands.  In order to solve this
problem, the \Package{longtable} package commands which are responsible for
the table captions need to be redefined. However, by the time the
\Package{longtable} package is loaded, the {\KOMAScript} class has already
been processed.

Until the present, the only way for {\KOMAScript} to solve this problem was to
delay the redefinition until the beginning of the document with help of the
macro \Macro{AtBeginDocument}.  If the user wants to change the definitions
too, it is recommended to do this in the preamble of the document.  However,
this is impossible since later at \Macro{begin}\PParameter{document}
{\KOMAScript} will again overwrite the user definition with its own.
Therefore, the user too has to delay his definition with
\Macro{AtBeginDocument}.
  
Actually, {\KOMAScript} should not need to delay the redefinition until
\Macro{begin}\PParameter{document}.  It would be enough to delay exactly until
the package \Package{longtable} has been loaded. Unfortunately, the {\LaTeX}
kernel does not define appropriate commands. The package \Package{scrlfile}
provides redress here.
  
Likewise, it might be conceivable that before a package is loaded one would
like to save the definition of a macro in a help-macro, in order to restore
its meaning after the package has been loaded. The package \Package{scrlfile}
allows this, too.
  
The employment of \Package{scrlfile} is not limited to package dependencies
only.  Even dependencies on any other file can be considered.  For example,
the user can be warned if the not uncritical file \File{french.ldf} has been
loaded.
  
Although the package is particularly of interest for package authors, there
are of course applications for normal {\LaTeX} users, too.  Therefore, this
chapter gives and explains examples for both groups of users.


\section{Actions Prior to and After Loading}
\label{sec:scrlfile.macros}

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

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

In order to implement those features \Package{scrlfile} redefines the well
known {\LaTeX} command \Macro{InputIfFileExists}. If this macro does not have
the expected definition then \Package{scrlfile} issues a warning.  This is for
the case that in future {\LaTeX} versions the macro can have a different
definition, or that another package has already redefined it.
  
The command \Macro{InputIfFileExists} is used by {\LaTeX} every time a file is
to be loaded.  This is independent of whether the actual load command is
\Macro{include}, \Macro{LoadClass}, \Macro{documentclass}, \Macro{usepackage},
\Macro{RequirePackage}, or similar. Exceptionally, the command
\begin{lstcode}[belowskip=\dp\strutbox]
  \input foo
\end{lstcode}
loads the file \texttt{foo} without utilizing
\Macro{InputIfFileExists}. Therefore, one should always use
\begin{lstcode}[belowskip=\dp\strutbox]
  \input{foo}
\end{lstcode}
instead. Notice the parentheses surrounding the file name!%
%
\EndIndex{Cmd}{BeforeFile}%
\EndIndex{Cmd}{AfterFile}%

\begin{Declaration}
  \Macro{BeforeClass}\Parameter{class}\Parameter{instructions}\\
  \Macro{BeforePackage}\Parameter{package}\Parameter{instructions}
\end{Declaration}%
\BeginIndex{Cmd}{BeforeClass}%
\BeginIndex{Cmd}{BeforePackage}%
These two commands work in the same way as \Macro{BeforeFile}.  The only
difference is that the document class \PName{class} and the {\LaTeX} package
\PName{package} are specified with their names and not with their file names.
That means that the file extensions \File{.cls} and \File{.sty} can be
omitted.%
%
\EndIndex{Cmd}{BeforeClass}%
\EndIndex{Cmd}{BeforePackage}%

\begin{Declaration}
  \Macro{AfterClass}\Parameter{class}\Parameter{instructions}\\
  \Macro{AfterClass*}\Parameter{class}\Parameter{instructions}\\
  \Macro{AfterClass+}\Parameter{class}\Parameter{instructions}\\
  \Macro{AfterClass!}\Parameter{class}\Parameter{instructions}\\
  \Macro{AfterAtEndOfClass}\Parameter{class}\Parameter{instructions}\\
  \Macro{AfterPackage}\Parameter{package}\Parameter{instructions}\\
  \Macro{AfterPackage*}\Parameter{package}\Parameter{instructions}\\
  \Macro{AfterPackage+}\Parameter{package}\Parameter{instructions}\\
  \Macro{AfterPackage!}\Parameter{package}\Parameter{instructions}\\
  \Macro{AfterAtEndOfPackage}\Parameter{package}\Parameter{instructions}
\end{Declaration}%
\BeginIndex{Cmd}{AfterClass}%
\BeginIndex{Cmd}{AfterClass*}%
\BeginIndex{Cmd}{AfterClass+}%
\BeginIndex{Cmd}{AfterClass!}%
\BeginIndex{Cmd}{AfterAtEndOfClass}%
\BeginIndex{Cmd}{AfterPackage}%
\BeginIndex{Cmd}{AfterPackage*}%
\BeginIndex{Cmd}{AfterPackage+}%
\BeginIndex{Cmd}{AfterPackage!}%
\BeginIndex{Cmd}{AfterAtEndOfPackage}%
The commands \Macro{AfterClass} and \Macro{AfterPackage} work in the
same way as \Macro{AfterFile}.  The only difference is that the
document class \PName{class} and the {\LaTeX} package \PName{package}
are specified with their names and not with their file names.  That
means that the file extensions \File{.cls} and \File{.sty} can be
omitted.  

The\important[i]{\Macro{AfterClass*}\\\Macro{AfterPackage*}} starred versions
are a little bit different. They execute the \PName{instructions} not only at
next time that the class or package is loaded, but also immediately if the
class or package has been loaded already.

The\important[i]{\Macro{AfterClass+}\\\Macro{AfterPackage+}}
plussed\ChangedAt{v3.09}{\Package{scrlfile}} version executes the
\PName{instructions} after loading of the class or package has been
finished. The difference to the starred version is only valid, if loading of
the class or package already started but has not been finished
yet. Nevertheless, \PName{instructions} will be executed before the
instructions of \Macro{AtEndOfClass} or \Macro{AtEndOfPackage} when loading of
the class or package has not been finished already.

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

If\important[i]{\Macro{AfterAtEndOfClass}\\\Macro{AfterAtEndOfPackage}} you
want to do this only in the case the class or package will be loaded later,
and if you want to execute \PName{instructions} outside the context of the
class or package, that will be loaded, you may use
\Macro{AfterAtEndOfClass}\ChangedAt{v3.09}{\Package{scrlfile}} for classes and
\Macro{AfterAtEndOfPackage} for packages.

\begin{Example}
  In the following, an example for class and package authors shall be
  given.  It shows how {\KOMAScript} itself employs the new commands.
  The class \Class{scrbook} contains:
\begin{lstcode}
  \AfterPackage{hyperref}{%
    \@ifpackagelater{hyperref}{2001/02/19}{}{%
      \ClassWarningNoLine{scrbook}{%
        You are using an old version of hyperref package!%
        \MessageBreak%
        This version has a buggy hack at many drivers%
        \MessageBreak%
        causing \string\addchap\space to behave strange.%
        \MessageBreak%
        Please update hyperref to at least version
        6.71b}}}
\end{lstcode}
  Old versions of the \Package{hyperref} package redefine a macro of the
  \Class{scrbook} class in such a way that does not work with newer
  {\KOMAScript} versions.  New versions of \Package{hyperref} desist
  from making these changes if a new {\KOMAScript} version is detected.
  For the case that \Package{hyperref} is loaded at a later stage,
  therefore, the code in \Class{scrbook} verifies that a acceptable
  \Package{hyperref} version is used.  If not, the command issues a
  warning.

  At other places in three {\KOMAScript} classes the following can be
  found:
\begin{lstcode}
  \AfterPackage{caption2}{%
    \renewcommand*{\setcapindent}{%
\end{lstcode}
  After the package \Package{caption2} has been loaded, and only if it
  has been loaded, {\KOMAScript} redefines its own command
  \Macro{setcapindent}.  The exact code of the redefinition is not
  important.  It should only be noted that \Package{caption2} takes
  control of the \Macro{caption} macro and that therefore the normal
  definition of the \Macro{setcapindent} macro would become ineffective.
  The redefinition improves the collaboration with \Package{caption2}.

  There are however also useful examples for normal {\LaTeX} user.  Suppose a
  document that should be available as a PS file, using {\LaTeX} and dvips, as
  well as a PDF file, using pdf{\LaTeX}.  In addition, the document should
  contain hyperlinks.  In the list of tables there are entries longer than one
  line.  This is not a problem for the pdf{\LaTeX} method, since here
  hyperlinks can be broken across multiple lines.  However, if a
  \Package{hyperref} driver for dvips or hyper{\TeX} is used then this is not
  possible.  In this case one desires that for the \Package{hyperref} setup
  \Option{linktocpage} is used. The decision which \Package{hyperref} driver
  to use happens automatically via \File{hyperref.cfg}. The file has, for
  example, the following content:
\begin{lstcode}
  \ProvidesFile{hyperref.cfg}
  \@ifundefined{pdfoutput}{\ExecuteOptions{dvips}}
                          {\ExecuteOptions{pdftex}}
  \endinput
\end{lstcode}

  All the rest can now be left to \Macro{AfterFile}.
\begin{lstcode}
  \documentclass{article}
  \usepackage{scrlfile}
  \AfterFile{hdvips.def}{\hypersetup{linktocpage}}
  \AfterFile{hypertex.def}{\hypersetup{linktocpage}}
  \usepackage{hyperref}
  \begin{document}
  \listoffigures
  \clearpage
  \begin{figure}
    \caption{This is an example for a fairly long figure caption, but
      which does not employ the optional caption argument that would
      allow one to write a short caption in the list of figures.}
  \end{figure}
  \end{document}
\end{lstcode}
  If now the \Package{hyperref} drivers \Option{hypertex} or
  \Option{dvips} are used, then the useful \Package{hyperref} option
  \Option{linktocpage} will be set. In the pdf{\LaTeX} case, the option
  will not be set, since in that case another \Package{hyperref} driver,
  \File{hpdftex.def}, will be used. That means neither \File{hdvips.def}
  nor \File{hypertex.def} will be loaded.
\end{Example}

Furthermore\textnote{Hint!}, the loading of package \Package{scrlfile} and
the \Macro{AfterFile} statement can be written in a private
\File{hyperref.cfg}. If you do so, then instead of \Macro{usepackage} the
macro \Macro{RequirePackage} ought be used (see \cite{latex:clsguide}).  The
new lines have to be inserted directly after the \Macro{ProvidesFile} line,
thus immediately prior to the execution of the options \Option{dvips} or
\Option{pdftex}.%
%
\EndIndex{Cmd}{AfterClass}%
\EndIndex{Cmd}{AfterClass*}%
\EndIndex{Cmd}{AfterClass+}%
\EndIndex{Cmd}{AfterClass!}%
\EndIndex{Cmd}{AfterAtEndOfClass}%
\EndIndex{Cmd}{AfterPackage}%
\EndIndex{Cmd}{AfterPackage*}%
\EndIndex{Cmd}{AfterPackage+}%
\EndIndex{Cmd}{AfterPackage!}%
\EndIndex{Cmd}{AfterAtEndOfPackage}%


\begin{Declaration}
  \Macro{BeforeClosingMainAux}\Parameter{instructions}\\
  \Macro{AfterReadingMainAux}\Parameter{instructions}%
\end{Declaration}%
\BeginIndex{Cmd}{BeforeClosingMainAux}%
\BeginIndex{Cmd}{AfterReadingMainAux}%
Package authors often want to write something into the \File{aux}-file after
the last document page have been shipped out. To do so, often
\begin{lstcode}[belowskip=\dp\strutbox]
  \AtEndDocument{%
    \if@filesw
      \write\@auxout{%
        \protect\writethistoaux%
      }%
    \fi
  } 
\end{lstcode}
is used. Nevertheless this is not a real solution of the problem. If the last
page of the document already have been shipped out before
\Macro{end}\PParameter{document}, the code above will not result in any
writing into the \File{aux}-file. If someone would try to fix this new problem
using \Macro{immediate} just before \Macro{write}, the inverse problem would
occur: If the last page was not shipped out before
\Macro{end}\PParameter{document} the \Macro{writethistoaux} would be written
into \File{aux}-file before ship-out the last page. Another often seen
suggestion for this problem therefore is:
\begin{lstcode}[belowskip=\dp\strutbox]
  \AtEndDocument{%
    \if@filesw
      \clearpage
      \immediate\write\@auxout{%
        \protect\writethistoaux%
      }%
    \fi
  } 
\end{lstcode}
This suggestion has a disadvantage again: The ship-out of the last page has
been enforced by the \Macro{clearpage}. After that, instructions like
\begin{lstcode}[belowskip=\dp\strutbox]
  \AtEndDocument{%
    \par\vspace*{\fill}%
    Note at the end of the document.\par
  }
\end{lstcode}
would not any longer output the note at the end of the last page of the
document but at the end of one more page. Additionally \Macro{writethistoaux}
would be written one page to early into the \File{aux}-file again.

The best solution for this problem would be, to write to the \File{aux}-file
immediately after the final \Macro{clearpage}, that is part of
\Macro{end}\PParameter{document}, but just before closing the
\File{aux}-file. This is the purpose of \Macro{BeforeClosingMainAux}:
\begin{lstcode}[belowskip=\dp\strutbox]
  \BeforeClosingMainAux{%
    \if@filesw
      \immediate\write\@auxout{%
        \protect\writethistoaux%
      }%
    \fi
  }
\end{lstcode}
This would be successful even if the final \Macro{clearpage} inside of
\Macro{end}\PParameter{document} would not really ship-out any page or if
someone have had used \Macro{clearpage} in the argument of
\Macro{AtEndDocument}.

Nevertheless there one important limitation using
\Macro{BeforeClosingMainAux}: You should not use a typeset instruction inside
the \PName{instructions} of \Macro{BeforeClosingMainAux}! If you miss this
limitation the result would be as unpredictable as the results of the
problematic suggestions using \Macro{AtEndDocument} upward.

Command \Macro{AfterReadingMainAux}\ChangedAt{v3.03}{\Package{scrlfile}}
actually executes the \PName{instructions} just after closing and input of the
\File{aux}-file inside of \Macro{end}\PParameter{document}. This will make
sense only in some cases, e.\,g., to show statistic information, that will be
valid only after input of the \File{aux}-file, or to write such information
into the \File{log}-file, or to implement additional \emph{rerun}
requests. Typeset instructions are even more critical inside these
\PName{instructions} that inside the argument of \Macro{BeforeClosingMainAux}.%
%
\EndIndex{Cmd}{AfterReadingMainAux}%
\EndIndex{Cmd}{BeforeClosingMainAux}%


\section{Replacing Files at Input}
\label{sec:scrlfile.replace}

All previous sections in this chapter describe commands to execute
instructions before or after input of a file, class, or package. Package
\Package{scrlfile} also provides commands to input another file, class, or
package instead of the one, that has been declared.


\begin{Declaration}
  \Macro{ReplaceInput}\Parameter{source file name}%
                      \Parameter{replacement file name}%
\end{Declaration}%
\BeginIndex{Cmd}{ReplaceInput}%
This\ChangedAt{v2.96}{\Package{scrlfile}} command defines a replacement for
the file of the first argument: \PName{source file name}, by the file of the
second argument: \PName{replacement file name}. If \LaTeX{} will be instructed
to input the file with \PName{source file name} at any time afterward, the
file with the \PName{replacement file name} will be input instead. The
replacement definition will be valid for all files, that the user will input
with \Macro{InputIfFileExists} and for all files, that will be input with a
command, that uses \Macro{InputIfFileExists} internally. To do so,
\Package{scrlfile} redefined \Macro{InputIfFileExists}.

\begin{Example}
  You want \LaTeX{} to input file \File{\Macro{jobname}.xua} instead of file
  \File{\Macro{jobname.aux}}. This may be done using
\begin{lstcode}
  \ReplaceInput{\jobname.aux}{\jobname.xua}
\end{lstcode}
  Additionally you may replace \File{\Macro{jobname}.xua} by
  \File{\Macro{jobname}.uxa} using:
\begin{lstcode}
  \ReplaceInput{\jobname.xua}{\jobname.uxa}
\end{lstcode}
  This will also replace input of \File{\Macro{jobname}.aux}, i.\,e., while
  \Macro{end}\PParameter{document}, by \File{\Macro{jobname}.uxa}. As you see,
  the whole replacement chain will be executed.

  Nevertheless a round robin replacement like
\begin{lstcode}
  \ReplaceInput{\jobname.aux}{\jobname.xua}
  \ReplaceInput{\jobname.xua}{\jobname.aux}
\end{lstcode}
  would result in a \emph{stack size error}. So it is not possible to define a
  replacement of a file by itself directly or indirectly.
\end{Example}

In theory is would also be possible to replace a package or class by another
one. But \LaTeX{} would recognize the usage of the wrong file name in this
case. A solution for this problem will be shown next.%
%
\EndIndex{Cmd}{ReplaceInput}%

\begin{Declaration}
  \Macro{ReplaceClass}\Parameter{source class}%
                      \Parameter{replacement package}\\
  \Macro{ReplacePackage}\Parameter{source package}%
                        \Parameter{replacement package}%
\end{Declaration}%
\BeginIndex{Cmd}{ReplaceClass}%
\BeginIndex{Cmd}{ReplacePackage}%
Classes\ChangedAt{v2.96}{\Package{scrlfile}}\textnote{Attention!} or packages
should never be replaced using previously described command
\Macro{ReplaceInput}. Using this command would result in a \LaTeX{} warning
because of class or package name not according the file name.
\begin{Example}
  You replace package \Package{fancyhdr} by package \Package{scrpage2}
  inconsiderately using
\begin{lstcode}
  \ReplaceInput{fancyhdr.sty}{scrpage2.sty}
\end{lstcode}
  Loading \Package{fancyhdr}, would result in
\begin{lstcode}
  LaTeX warning: You have requested `scrpage2',
                 but the package provides `fancyhdr'.
\end{lstcode}
  after this. Users may be confused by such a warning, because they've used,
  e.\,g., \Macro{usepackage}\PParameter{fancyhdr} and never requested package
  \Package{scrpage2} on their own. But \Package{scrlfile} replaced the input
  of \File{fancyhdr.sty} by \File{scrpage2.sty} because of your replacement
  definition.
\end{Example}
A solution for this problem would be, to use \Macro{ReplaceClass} or
\Macro{ReplacePackage} instead of \Macro{ReplaceFile}. Please note, that in
this case you have to use the names of the classes or packages only instead of
the whole file name. This is similar to usage of \Macro{documentclass} and
\Macro{usepackage}.

The class replacement would perform for all classes, that will be loaded using
\Macro{documentclass}, \Macro{LoadClassWithOptions}, or \Macro{LoadClass}. The
package replacement would perform for all packages, that will be loaded using
\Macro{usepackage}, \Macro{RequirePackageWithOptions}, or
\Macro{RequirePackage}.

Please\textnote{Attention!} note, that the \PName{replacement class} or the
\PName{replacement package} will be loaded with the same options, the
\PName{source class} or \PName{replacement class} would until it has been
replaced. Replacement of a class or package by a class or package, that
does not support a requested option, would result in a warning or even an error
message. But you may declare such missing options using \Macro{BeforeClass} or
\Macro{BeforePackage}.

\begin{Example}
  Assumed, package \Package{oldfoo} should be replaced by
  \Package{newfoo}. This may be done using:
\begin{lstcode}
  \ReplacePackage{oldfoo}{newfoo}
\end{lstcode}
  Assumed the old package provides an option \Option{oldopt}, but the new
  package does not. Using
\begin{lstcode}
  \BeforePackage{newfoo}{%
    \DeclareOption{oldopt}{%
      \PackageInfo{newfoo}%
                  {option `oldopt' not supported}%
    }}%
\end{lstcode}
  additionally, would declare this missing option for package
  \Package{newfoo}. This would avoid warning message about unsupported
  options.

  However, if package \Package{newfoo} supports an option \Option{newopt},
  that should be used instead of option \Option{oldopt} of old package
  \Package{oldfoo}, this may achieved using:
\begin{lstcode}
  \BeforePackage{newfoo}{%
    \DeclareOption{oldopt}{%
      \ExecuteOptions{newopt}%
    }}%
\end{lstcode}
  Last but not least different default options may be selected, that should be
  valid while package replacement:
\begin{lstcode}
  \BeforePackage{newfoo}{%
    \DeclareOption{oldopt}{%
      \ExecuteOptions{newopt}%
    }%
    \PassOptionsToPackage{newdefoptA,newdefoptB}%
                         {newfoo}%
  }
\end{lstcode}
  or somehow more directly:
\begin{lstcode}
  \BeforePackage{newfoo}{%
    \DeclareOption{oldopt}{%
      \ExecuteOptions{newopt}%
    }%
  }%
  \PassOptionsToPackage{newdefoptA,newdefoptB}%
                       {newfoo}%
\end{lstcode}
\end{Example}

To replace classes package \Package{scrlfile} has to be loaded before the
class using \Macro{RequirePackage} instead of \Macro{usepackage}.
%
\EndIndex{Cmd}{ReplacePackage}%
\EndIndex{Cmd}{ReplaceClass}%

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


\section{Prevent File Loading}
\label{sec:scrlfile.prevent}

Especially\ChangedAt{v3.08}{\Package{scrlfile}} classes or packages, that have
been made for companies or institutes, often load a lot of packages not needed
by the classes or packages itself but only because the users often use
them. Now, if such a not essential package causes any kind of problem, loading
of that package has to prevented. For this purpose \Package{scrlfile} again
provides a solution.

\begin{Declaration}
  \Macro{PreventPackageFromLoading}\OParameter{instead code}%
  \Parameter{package list}\\
  \Macro{PreventPackageFromLoading*}\OParameter{instead code}%
  \Parameter{package list}
\end{Declaration}
\BeginIndex{Cmd}{PreventPackageFromLoading}%
\BeginIndex{Cmd}{PreventPackageFromLoading*}%
Calling this command\ChangedAt{v3.08}{\Package{scrlfile}} before loading a
package using \Macro{usepackage}\IndexCmd{usepackage},
\Macro{RequirePackage}\IndexCmd{RequirePackage}, or
\Macro{RequirePackageWithOptions}\IndexCmd{RequirePackageWithOptions} will
prevent the package from being loaded effectively if the package is part of
the \PName{package list}.
%
\begin{Example}
  Assumed you're working in a company, that uses font Latin-Modern for all
  kind of documents. Because of this the company class, \Class{compycls}
  contains the lines:
\begin{lstcode}
  \RequirePackage[T1]{fontenc}
  \RequirePackage{lmodern}
\end{lstcode}
  But now, you want to use
  X\kern-.125em\lower.5ex\hbox{\reflectbox{E}}\LaTeX{} oder Lua\LaTeX{} the
  first time. In this case loading of \Package{fontenc} would not be a good
  suggestion and Latin-Modern would be the default font of the recommended
  package \Package{fontspec}. Because of this you want to prevent both
  packages from being loaded. This may be done, loading the class like this:
\begin{lstcode}
  \RequirePackage{scrlfile}
  \PreventPackageFromLoading{fontenc,lmodern}
  \documentclass{firmenci}
\end{lstcode}
\end{Example}
The example above also shows, that package \Package{scrlfile} may be loaded
before the class. In this case \Macro{RequirePackage}\IndexCmd{RequirePackage}
has to be used, because \Macro{usepackage} before \Macro{documentclass} is not
permitted.

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

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

\begin{Declaration}
  \Macro{StorePreventPackageFromLoading}\Parameter{\Macro{command}}\\
  \Macro{ResetPreventPackageFromLoading}
\end{Declaration}
\BeginIndex{Cmd}{StorePreventPackageFromLoading}%
\BeginIndex{Cmd}{ResetPreventPackageFromLoading}%
\Macro{StorePreventPackageFromLoad}\ChangedAt{v3.08}{\Package{scrlfile}}
defines \Macro{command} to be the current list of packages, that should be
prevented from being loaded. In opposite to this,
\Macro{ResetPreventPackageFromLoading}\ChangedAt{v3.08}{\Package{scrlfile}}
resets the list of packages, that should be prevented from being loaded. After
\Macro{ResetPreventPackageFromLoading} all packages may be loaded again.
\begin{Example}
  Assumed, you really need a package inside your own package and you want the
  user inhibit to prevent loading of that package with
  \Macro{PreventPackageFromLoading}\IndexCmd{PreventPackageFromLoading}. Because
  of this, you reset the package preventing list before loading the package:
\begin{lstcode}
  \ResetPreventPackageFromLoading
  \RequirePackage{foo}
\end{lstcode}
  Unfortunately the complete prevention list of the user would be lost after
  that. To avoid this, you first store the list and restore it at the end:
\begin{lstcode}
  \newcommand*{\Users@PreventList}{}%
  \StorePreventPackageFromLoading\Users@PreventList
  \ResetPreventPackageFromLoading
  \RequirePackage{foo}
  \PreventPackageFromLoading{\Users@PreventList}
\end{lstcode}
  Please\textnote{Attention!} note, that
  \Macro{StorePreventPackageFromLoading} would define
  \Macro{Users@PreventList} even if it already has been defined before. In other
  words: \Macro{StorePreventPackageFromLoading} overwrites existing
  \Macro{command} definitions without care. Because of this,
  \Macro{newcommand*} has been used in the example to get an error message, if
  \Macro{Users@PreventList} has already been defined.
\end{Example}
At this point please note, that everybody who manipulates the list, that has
been stored using \Macro{StorePreventPackageFromLoading} is responsible for
the correct restorability. For example the list elements must be separated by
comma, must not contain white space or group braces, and must be fully
expandable.

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

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

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

\endinput

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

% LocalWords:  restorability