summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/scrguide/english/loadfile.tex
blob: c8b3a6eb6a79836505259bd570d27ac76bbf1aa4 (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
\ProvidesFile{loadfile.tex}[2004/09/13 KOMA-Script Manual english]
% ============================================================================
% loadfile.tex 
% Copyright (c) 2001-2002 Markus Kohm and the authors.
%
% This file is part of the LaTeX2e KOMA-Script-Bundle
%
% This file can be redistributed and/or modified under the terms of the LaTeX
% Project Public License Version 1.0 distributed together with this file. See
% LEGAL.TXT or LEGALDE.TXT.
%
% This bundle is written specialy for use at german-language. So the main
% documentation is german. There may also be an english documentation. See
% readme.txt, if you search for it.
% ----------------------------------------------------------------------------
% loadfile.tex
% Copyright (c) 2001-2002 Markus Kohm und bei den weiteren Autoren.
%
% Diese Datei ist Teil des LaTeX2e KOMA-Script-Pakets.
%
% Diese Datei kann nach den Regeln der LaTeX Project Public Licence 
% Version 1.0, wie sie zusammen mit dieser Datei verteilt wird,
% weiterverbreitet und/oder modifiziert werden. Siehe dazu auch LEGAL.TXT oder
% LEGALDE.TXT.
%
% Dieses Paket ist fuer den deutschen Sprachraum konzipiert. Daher ist auch
% diese Anleitung komplett in Deutsch. Moeglicherweise existiert auch eine
% englische Version der Anleitung. Falls Sie eine solche benoetigen, schauen
% Sie bitte in liesmich.txt nach, ob eine solche vorhanden ist.
% ============================================================================
%
% Modul:    scrlfile
% Authors:  Markus Kohm (MJK) <markus.kohm@gmx.de>
% Contents: excecuting commands depending on one file is loaded
% Language: English
% Date of translated german file:
%           2002/08/30
% Charset of comments:
%           US-ASCII
%

\chapter{Control Package Dependencies with \Package{scrlfile}}
\label{cha:scrlfile}

\BeginIndex{Package}{scrlfile}

\section{About Package Dependencies}
\label{sec:scrlfile.dependency}
\begin{Explain}
  The introduction of \LaTeXe{} in 1994 brought many changes
  in the handling with \LaTeX-extensions.
  Today the package author has many macros in order 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 the package is loaded later.
  This has led to the expectation that the order of package-loading
  will be not important.
  But this hope has not been fulfilled, since often different packages
  define or redefine one macro again and again.
  In such a case the order of package-loading becomes very
  important.
  For the user this is sometimes difficult to understand the
  behaviour and in some cases the user wants only react
  on the loading of a package. This is also not really simple.
  
     
  Assuming the simple example that loads the package \Package{longtable}
  with a \KOMAScript{} document-class employed.
  The \Package{longtable} package defines table captions
  suitable for the standard classes, but the captions
  are totally unsuitable for documents using \KOMAScript{} and thus
  the provided configuration commands have no influence.
  In order to solve this problem the commands which are responsible
  for the table captions of the \Package{longtable} package
  have to be re-defined. But at the moment when the \Package{longtable}
  is loaded the \KOMAScript{} class is already processed.

  
  The only chance for \KOMAScript{} was to delay the re-definition
  until the begin 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.
  But this is impossible since later at \Macro{begin}\PParameter{document}
  \KOMAScript will again overwrite the user-definition with its own.
  Therefore the user has to delay his definition with
  \Macro{AtBeginDocument} as well.
  
  However, \KOMAScript{} shouldn't delay the re-definition
  until \Macro{begin}\PParameter{document}.
  It would be enough to delay until the package \Package{longtable}
  has been loaded. But unfortunately the basic \LaTeX{} 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 with any other file can be attended.
  For example the user can be warned if the not uncritical file
  \File{french.ldf} has been loaded.
  
  Though the package is particularly interesting for
  package authors, there are of course applications for
  normal \LaTeX{} users too.
  Therefore this chapter gives and explains examples
  for both groups of users.
\end{Explain}


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

\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} enables to execute \PName{instructions}
the next time the \PName{file} is loaded.
In the same way works \Macro{AfterFile}, but here the
\PName{instructions} will be executed after the \PName{file}
has been loaded.
If \PName{file} will never be loaded then the \PName{instructions}
will never be executed.

\begin{Explain}
  In order to implement those features \Package{scrlfile}
  re-defines the well known \LaTeX{} command
  \Macro{InputIfFileExists}.
  If this macro has not the expected definition \Package{scrlfile}
  gives a warning.
  This is for the case that in future \LaTeX{} versions
  the macro can have a different definition or an other package
  has already re-defined it.
  
  The command \Macro{InputIfFileExists} is used 
  everytime \LaTeX{} has to load a file.
  This is independent from whether the actual command was \Macro{LoadClass},
  \Macro{documentclass}, \Macro{usepackage}, \Macro{RequiresPackage},
  or \Macro{include}. Exclusively the command
\begin{verbatim}
  \input foo
\end{verbatim}
  loads the file \texttt{foo} without to utilize
  \Macro{InputIfFileExists}. Therefore one should always use
\begin{verbatim}
  \input{foo}
\end{verbatim}
  instead. Notice the parentheses surrounding the file name!
\end{Explain}
%
\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 both commands work 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 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{AfterPackage}\Parameter{package}\Parameter{instructions}\\
  \Macro{AfterPackage*}\Parameter{package}\Parameter{instructions}
\end{Declaration}%
\BeginIndex{Cmd}{AfterClass}%
\BeginIndex{Cmd}{AfterClass*}%
\BeginIndex{Cmd}{AfterPackage}%
\BeginIndex{Cmd}{AfterPackage*}%
The commands \Macro{AfterClass} und \Macro{AfterPackage} 
work 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 the file extensions \File{.cls} and \File{.sty}
can be omitted.
The starred versions execute the \PName{instructions} not
only next time the class or package is loaded, but also
immediately if the class or package has been loaded already.
%
\EndIndex{Cmd}{AfterClass}%
\EndIndex{Cmd}{AfterClass*}%
\EndIndex{Cmd}{AfterPackage}%
\EndIndex{Cmd}{AfterPackage*}%

\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{small}
\begin{verbatim}
\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{verbatim}
  \end{small}
  Old versions of the \Package{hyperref} package re-define
  a macro of the \Class{scrbook} class in a way that does not
  work with newer \KOMAScript{} versions.
  New versions of \Package{hyperref} neglect these changes
  if a new \KOMAScript{} version is detected.
  For the case that \Package{hyperref} is loaded the code
  in \Class{scrbook} verifies that a appropriate
  \Package{hyperref} version is used.   If not the command gives
  a warning.

  At other places in three \KOMAScript{} classes following can be found:
  \begin{small}
\begin{verbatim}
  \AfterPackage{caption2}{%
    \renewcommand*{\setcapindent}{%
\end{verbatim}
  \end{small}
  Next the package \Package{caption2} has been loaded, and only
  if the package has been loaded really, \KOMAScript{} re-defines
  its own command \Macro{setcapindent}.
  The exact code of the definition is not important.
  It should only be noted that \Package{caption2} claims the
  control over the \Macro{caption} macro.
  Thus the normal definition of the \Macro{setcapindent} macro
  would not work as expected.
  The re-definition improves the collaboration with \Package{caption2}.

  There are of course useful examples for normal \LaTeX{} user too.
  Suppose a document that should be availbale as PS file, using
  LaTeX{} and dvips, and as PDF file, using pdf\LaTeX.
  The document should contain hyper-links.
  In the List of Tables there are entries longer than one line.
  This is not a problem for the pdf\LaTeX{} way, since here
  hyper-links can run across multiple lines.  
  But if a \Package{hyperref} driver for dvips or
  hyper\TeX{} is used then this is not possible.
  In this case one wants that for the \Package{hyperref} setup
  the \Option{linktocpage} is used.
  
  The decision what \Package{hyperref} driver has to be used
  happens automatically via \File{hyperref.cfg}.
  The file has for example the content below.
  \begin{small}
\begin{verbatim}
  \ProvidesFile{hyperref.cfg}
  \@ifundefined{pdfoutput}{\ExecuteOptions{dvips}}
                          {\ExecuteOptions{pdftex}}
  \endinput
\end{verbatim}
  \end{small}

  All following is now the task of \Macro{AfterFile}.
  \begin{small}
\begin{verbatim}
  \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 long figure caption,
      but even though it does not employ the optional
         caption argument that would allow to write
         a short caption in the List of Figures.}
  \end{figure}
  \end{document}
\end{verbatim}
  \end{small}
  If now \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 an other \Package{hyperref} driver \File{hpdftex.def}
  will be used. That means neither \File{hdvips.def} nor
  \File{hypertex.def} will be loaded.
\end{Example}

\begin{Explain}
  Furthermore the loading of package \Package{scrlfile}
  and the \Macro{AfterFile} statement can be written
  in the private \File{hyperref.cfg}.
  But then instead of \Macro{usepackage} the macro
  \Macro{RequiresPackage} ought be used, see \cite{latex:clsguide}.
  The new lines have to be inserted directly after 
  \Macro{ProvidesFile} line, thus prior to the execution
  of the options \Option{dvips} or \Option{pdftex}.
\end{Explain}


\section{Authors}
\label{sec:scrlfile.authors}
The authors listed below are responsible for this chapter or have
contributed to this chapter in different ways.
% Please use \textit{} for the name of the translator add all the
% names of the untranslated german file. If the translator is the
% main author, simply use \textbf. 
\begin{itemize}
\item Markus Kohm \TextEMail{Markus.Kohm@gmx.de}
\item \textit{Jens-Uwe Morawski}
\end{itemize}

\EndIndex{Package}{scrlfile}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "main"
%%% End: