diff options
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.tex | 310 |
1 files changed, 310 insertions, 0 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 new file mode 100644 index 00000000000..52e3f8e610a --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex @@ -0,0 +1,310 @@ +% ====================================================================== +% scrlfile.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% 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.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b 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-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b 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 über 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 + +\chapter{Control Package Dependencies with \Package{scrlfile}} +\labelbase{scrlfile} + +\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 + 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. + + 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{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} + 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{lstlisting} +\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{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. + + At other places in three \KOMAScript{} classes 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}. + + 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{lstlisting} + \ProvidesFile{hyperref.cfg} + \@ifundefined{pdfoutput}{\ExecuteOptions{dvips}} + {\ExecuteOptions{pdftex}} + \endinput +\end{lstlisting} + + All following is now the task of \Macro{AfterFile}. +\begin{lstlisting} + \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{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. +\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}% +\EndIndex{Package}{scrlfile} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "../guide" +%%% End: |