summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex')
-rw-r--r--Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex292
1 files changed, 145 insertions, 147 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex
index fd1ce916852..d55e5f98219 100644
--- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex
+++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex
@@ -40,13 +40,15 @@
%
% ----------------------------------------------------------------------------
%
-% Kapitel über scrlfile in der KOMA-Script-Anleitung
+% Kapitel ueber scrlfile in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ============================================================================
-\ProvidesFile{scrlfile.tex}[2005/11/27 KOMA-Script guide (chapter: scrlfile)]
-% Date of translated german file: 2005/08/10
+\ProvidesFile{scrlfile.tex}[2007/09/26 KOMA-Script guide (chapter: scrlfile)]
+\translator{Gernot Hassenpflug\and Markus Kohm}
+
+% Date of translated german file: 2007/08/07
\chapter{Control Package Dependencies with \Package{scrlfile}}
\labelbase{scrlfile}
@@ -54,104 +56,111 @@
\BeginIndex{Package}{scrlfile}
\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
+ The introduction of {\LaTeXe} in 1994 brought many changes in the
+ handling of {\LaTeX} extensions. Today the package author has many
+ macros available to determine if another package or class is
+ employed and whether specific options are used. The author can load
+ other packages or can specify options in the the case that the
+ package is loaded later. This has led to the expectation that the
+ order in which package are loaded would not be important. Sadly
this hope has not been fulfilled.
\end{Explain}
\section{About Package Dependencies}
\label{sec:scrlfile.dependency}
\begin{Explain}
- 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.
+ 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.
- 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.
+ 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.
- 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.
+ 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}.
- 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.
+ Actually, {\KOMAScript} should not need to delay the redefinition
+ until \Macro{begin}\PParameter{document}. It would be enough to
+ delay exactly until the package \Package{longtable} has been
+ loaded. Unfortunately, the {\LaTeX} kernel does not define
+ appropriate commands. The package \Package{scrlfile} provides
+ redress here.
- Likewise, it might be conceivable that before a package is loaded one would
- like to save the definition of a macro in a help-macro, in order to restore
- its meaning after the package has been loaded. The package
- \Package{scrlfile} allows this too.
+ Likewise, it might be conceivable that before a package is loaded
+ one would like to save the definition of a macro in a help-macro, in
+ order to restore its meaning after the package has been loaded. The
+ package \Package{scrlfile} allows this, too.
- The employment of \Package{scrlfile} is not limited to package dependencies
- only. Even dependencies 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.
+ 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.
- 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.
+ Although the package is particularly of interest for package
+ authors, there are of course applications for normal {\LaTeX} users,
+ too. Therefore, this chapter gives and explains examples for both
+ groups of users.
\end{Explain}
-\section{Actions Prior and After Loading}
+\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} 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.
+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.
\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.
+ 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
- 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{lstlisting}
- \input foo
-\end{lstlisting}
- loads the file \texttt{foo} without to utilize
- \Macro{InputIfFileExists}. Therefore one should always use
-\begin{lstlisting}
- \input{foo}
-\end{lstlisting}
+ The command \Macro{InputIfFileExists} is used by {\LaTeX} every time
+ a file is to be loaded. This is independent of whether the actual
+ load command is \Macro{include}, \Macro{LoadClass},
+ \Macro{documentclass}, \Macro{usepackage}, \Macro{RequirePackage},
+ or similar. Exceptionally, the command
+ \begin{lstlisting}
+ \input foo
+ \end{lstlisting}
+ loads the file \texttt{foo} without utilizing
+ \Macro{InputIfFileExists}. Therefore, one should always use
+ \begin{lstlisting}
+ \input{foo}
+ \end{lstlisting}
instead. Notice the parentheses surrounding the file name!
\end{Explain}
%
@@ -164,12 +173,11 @@ will never be executed.
\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.
+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}%
@@ -184,15 +192,13 @@ can be omitted.
\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
+The commands \Macro{AfterClass} and \Macro{AfterPackage} work in the
+same way as \Macro{AfterFile}. The only difference is that the
+document class \PName{class} and the {\LaTeX} package \PName{package}
+are specified with their names and not with their file names. That
+means that the file extensions \File{.cls} and \File{.sty} can be
+omitted. The starred versions execute the \PName{instructions} not
+only at next time that the class or package is loaded, but also
immediately if the class or package has been loaded already.
%
\EndIndex{Cmd}{AfterClass}%
@@ -201,9 +207,8 @@ immediately if the class or package has been loaded already.
\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.
+ In the following, an example for class and package authors shall be
+ given. It shows how {\KOMAScript} itself employs the new commands.
The class \Class{scrbook} contains:
\begin{lstlisting}
\AfterPackage{hyperref}{%
@@ -218,46 +223,41 @@ immediately if the class or package has been loaded already.
Please update hyperref to at least version
6.71b}}}
\end{lstlisting}
- 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.
+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 following can be found:
+At other places in three {\KOMAScript} classes the following can be
+found:
\begin{lstlisting}
\AfterPackage{caption2}{%
\renewcommand*{\setcapindent}{%
\end{lstlisting}
- 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}.
+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 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.
+There are however also useful examples for normal {\LaTeX} user.
+Suppose a document that should be available as a PS file, using
+{\LaTeX} and dvips, as well as a PDF file, using pdf{\LaTeX}. In
+addition, the document should contain hyperlinks. In the list of
+tables there are entries longer than one line. This is not a problem
+for the pdf{\LaTeX} method, since here hyperlinks can be broken across
+multiple lines. However, if a \Package{hyperref} driver for dvips or
+hyper{\TeX} is used then this is not possible. In this case one
+desires that for the \Package{hyperref} setup \Option{linktocpage} is
+used. The decision which \Package{hyperref} driver to use happens
+automatically via \File{hyperref.cfg}. The file has, for example, the
+following content:
\begin{lstlisting}
\ProvidesFile{hyperref.cfg}
\@ifundefined{pdfoutput}{\ExecuteOptions{dvips}}
@@ -265,7 +265,7 @@ immediately if the class or package has been loaded already.
\endinput
\end{lstlisting}
- All following is now the task of \Macro{AfterFile}.
+All the rest can now be left to \Macro{AfterFile}.
\begin{lstlisting}
\documentclass{article}
\usepackage{scrlfile}
@@ -276,35 +276,33 @@ immediately if the class or package has been loaded already.
\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.}
+ \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{lstlisting}
- 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.
+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}
\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}.
+ Furthermore, the loading of package \Package{scrlfile} and the
+ \Macro{AfterFile} statement can be written in a private
+ \File{hyperref.cfg}. If you do so, then instead of
+ \Macro{usepackage} the macro \Macro{RequirePackage} ought be used
+ (see \cite{latex:clsguide}). The new lines have to be inserted
+ directly after the \Macro{ProvidesFile} line, thus immediately prior
+ to the execution of the options \Option{dvips} or \Option{pdftex}.
\end{Explain}%
\EndIndex{Package}{scrlfile}
%%% Local Variables:
%%% mode: latex
+%%% coding: iso-latin-1
%%% TeX-master: "../guide"
%%% End: