summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/scrlfile.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/scrlfile.dtx')
-rw-r--r--Master/texmf-dist/source/latex/koma-script/scrlfile.dtx525
1 files changed, 525 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/scrlfile.dtx b/Master/texmf-dist/source/latex/koma-script/scrlfile.dtx
new file mode 100644
index 00000000000..9f2290a6e2e
--- /dev/null
+++ b/Master/texmf-dist/source/latex/koma-script/scrlfile.dtx
@@ -0,0 +1,525 @@
+% \CheckSum{151}
+% \iffalse meta-comment
+% ======================================================================
+% scrlfile.dtx
+% Copyright (c) Markus Kohm, 2002-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.dtx
+% Copyright (c) Markus Kohm, 2002-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.
+% ======================================================================
+% \fi
+%
+% \CharacterTable
+% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+%
+% \iffalse
+%%% From File: scrlfile.dtx
+%<*driver|scrlfile|load>
+% \fi
+\def\scrlfileversion{2006/03/28 v2.95}
+% \iffalse
+%</driver|scrlfile|load>
+%<*driver>
+% \fi
+\ProvidesFile{scrlfile.dtx}[%
+% \iffalse
+%</driver>
+%<*driver|scrlfile>
+%<scrlfile>\ProvidesPackage{scrlfile}[%
+% \fi
+ \scrlfileversion\space KOMA-Script package (loading files)]
+% \iffalse
+%</driver|scrlfile>
+%<*driver>
+\IfFileExists{scrdoc.cls}{%
+ \documentclass[halfparskip-]{scrdoc}
+}{%
+ \documentclass{ltxdoc}
+}
+\providecommand*{\KOMAScript}{\textsf{KOMA-Script}}
+\usepackage[german,english]{babel}
+\CodelineIndex
+\RecordChanges
+\GetFileInfo{scrlfile.dtx}
+\title{\KOMAScript{} \partname\ \texttt{\filename}%
+ \thanks{This file is version \fileversion\ of file \texttt{\filename}.}}
+\date{\filedate}
+\author{Markus Kohm\thanks{mailto:kohm@gmx.de}~\thanks{Description
+ part of the documentation was written by Jens-Uwe Morawski.}}
+
+\begin{document}
+ \maketitle
+ \begin{abstract}
+ This package provides hooks before and after loading files, packages
+ or classes. It also provides a hook after the last \cs{clearpage} of
+ the document. It is inteded to be used by package and class authors
+ but may also be used by \LaTeX{} users.
+ \end{abstract}
+
+ \section{Legal Note}
+ This is the only part of \KOMAScript{} you are allowed to
+ redistribute without all the other files of \KOMAScript. You are
+ allowed to redistribute and/or modifie the files
+ ``\texttt{scrlogo.dtx}'', ``\texttt{scrlfile.dtx}'' and
+ ``\texttt{scrlfile.ins}'' under the conditions of \LaTeX{} Project
+ Public License, either version 1.2 of this license or (at your
+ option) any later version. The latest version of this license is in
+ \mbox{http://www.latex-project.org/lppl.txt} and version 1.2 or
+ later is part of all distributions of \LaTeX{} version 1999/12/01 or
+ later. You are not allowed to distribute one of the three files
+ ``\texttt{scrlogo.dtx}'', ``\texttt{scrlfile.dtx}'' and
+ ``\texttt{scrlfile.ins}'' without the others but all these files
+ together.
+
+ \KOMAScript{} is a versatile bundle of \LaTeX{} classes and
+ packages. Large german and english manuals, both with more than
+ 200~pages, are part of \KOMAScript{} bundle. You can find a longer
+ version of the \textsf{scrlfile}-documentation at the \KOMAScript{}
+ manuals.
+
+ You can find the latest version of \KOMAScript{} bundle and
+ \texttt{scrlfile} at
+ \mbox{CTAN:/macros/latex/contrib/supported/koma-script/} in the
+ course of which ``CTAN:'' is a short hand synonym for directory
+ ``tex-archive'' at every CTAN server and mirror, e.g.\
+ \mbox{ftp://ftp.dante.de/tex-archive/}. See
+ \mbox{http://www.ctan.org} for a list of CTAN servers and mirrors.
+
+ \DocInput{\filename}
+\end{document}
+%</driver>
+% \fi
+%
+% \selectlanguage{english}
+%
+% \changes{v2.95}{2002/06/11}{%
+% First version split from hugh scrclass.dtx}
+%
+%
+% \section[Hook loading files, packages or classes]{%
+% Hooks loading files, packages or classes\footnote{You'll find a
+% short version of \textsf{scrlfile} documentation here. A longer
+% version may be found at english and german \KOMAScript{} manual.}}
+%
+% 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 it 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 \textsf{longtable}
+% with a \KOMAScript{} document-class employed. The \textsf{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 \textsf{longtable} package have to be
+% re-defined. But at the moment when the \textsf{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 |\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 |\begin{document}| \KOMAScript will again overwrite the
+% user-definition with its own. Therefore the user has to delay his
+% definition with \verb|\AtBeginDocument| as well.
+%
+% However, \KOMAScript{} shouldn't delay the re-definition until
+% |\begin{document}|. It would be enough to delay until the package
+% \textsf{longtable} has been loaded. But unfortunately the basic
+% \LaTeX{} does not define appropriate commands. The package
+% \textsf{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
+% \textsf{scrlfile} allows this too.
+%
+% The employment of \textsf{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 \texttt{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.
+%
+%
+% \DescribeMacro{\BeforeFile}
+% \DescribeMacro{\AfterFile}
+% The command \cs{BeforeFile}\marg{file}\marg{instructions} enables to
+% execute \meta{instructions} the next time the \meta{file} is
+% loaded. In the same way works \cs{AfterFile}, but here the
+% \meta{instructions} will be executed after the \meta{file} has
+% been loaded. If \meta{file} will never be loaded then the
+% \meta{instructions} will never be executed.
+%
+% In order to implement those features \textsf{scrlfile} re-defines
+% the well known \LaTeX{} command \cs{InputIfFileExists}. If this
+% macro has not the expected definition \textsf{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 \cs{InputIfFileExists} is used everytime \LaTeX{} has to
+% load a file. This is independent from whether the actual command
+% was \cs{LoadClass}, \cs{documentclass}, \cs{usepackage},
+% \cs{RequiresPackage}, or \cs{include}. Exclusively the command
+% \begin{verbatim}
+% \input foo
+% \end{verbatim}\vspace{-\baselineskip}%
+% loads the file \meta{foo} without to utilize
+% \cs{InputIfFileExists}. Therefore one should always use
+% \begin{verbatim}
+% \input{foo}
+% \end{verbatim}\vspace{-\baselineskip}%
+% instead. Notice the parentheses surrounding the file name!
+%
+% \DescribeMacro{\BeforeClass}
+% \DescribeMacro{\BeforePackage}
+% The command \cs{BeforeClass}\marg{class}\marg{instructions} and the
+% command \cs{BeforePackage}\marg{package}\marg{instructions} work
+% the same way like the above described \cs{BeforeFile}. The only
+% difference is that the document \meta{class} and the \LaTeX{}
+% \meta{package} are specified with their names and not with their
+% file names. That means the file extensions ``\texttt{.cls}'' and
+% ``\texttt{.sty}'' have to be omitted.
+%
+% \DescribeMacro{\AfterClass}
+% \DescribeMacro{\AfterClass*}
+% \DescribeMacro{\AfterPackage}
+% \DescribeMacro{\AfterPackage*}
+% The command \cs{AfterClass}\marg{class}\marg{instructions} and the
+% command \cs{AfterPackage}\marg{package}\marg{instructions} work the
+% same way like command \cs{AfterFile}. The only difference is that
+% the document \meta{class} and the \LaTeX{} \meta{package} are
+% specified with their names and not with their file names. That
+% means the file extensions ``\texttt{.cls}'' and ``\texttt{.sty}''
+% have to be omitted. The starred versions execute the
+% \meta{instructions} not only next time the class or package is
+% loaded, but also immediately if the class or package has been loaded
+% already.
+%
+% \DescribeMacro{\BeforeClosingMainAux}
+% The command \cs{BeforeClosingMainAux}\marg{instructions}
+% works different from all the commands above. Is isn't a
+% load-file-hook. Package authors often have the problem, that they
+% need to write something to \texttt{aux}-file after output of the
+% last page. This is often done with:
+% \begin{flushleft}
+% | \AtEndDocument{\if@filesw|\\
+% | \write\@auxout{%|\\
+% | |\texttt{\emph{Write this to aux.}}\\
+% | }%|\\
+% | \fi}|
+% \end{flushleft}
+% But this fails, if the last \cs{shipout} was already done
+% e.g. because of someone used a different solution:
+% \begin{flushleft}
+% | \AtEndDocument{\if@filesw\clearpage|\\
+% | \immediate\write\@auxout{%|\\
+% | |\texttt{\emph{Write this to aux.}}\\
+% | }%|\\
+% | \fi}|
+% \end{flushleft}
+% The best solution would be to immediate write to \texttt{aux}-file
+% just after the \cs{clearpage} and before closing \texttt{aux}-file
+% at \cs{end\{document\}}. That's the goal of
+% \cs{BeforeClosingMainAux}:
+% \begin{flushleft}
+% | \BeforeClosingMainAux{\if@filesw|\\
+% | \immediate\write\@auxout{%|\\
+% | |\texttt{\emph{Write this to aux.}}\\
+% | }%|\\
+% | \fi}|
+% \end{flushleft}
+% This even works, if \cs{clearpage} at \cs{end\{document\}} will not
+% result in \cs{shipout} or if typessetting code\,---\,even
+% \cs{clearpage}\,---\,has been used at \cs{AtEndDocument}.
+%
+% The \cs{BeforeClosingMainAux} hook should not be used for code that
+% does any typesetting since the result of \cs{BeforeClosingMainAux}
+% would be unpredictable.
+%
+%
+% \StopEventually{\PrintIndex\PrintChanges}
+%
+% \iffalse
+%<*scrlfile>
+% \fi
+%
+% \subsection{Preamble}
+%
+% First of all we show the package and version at terminal and
+% log-file:
+% \begin{macrocode}
+\typeout{Package scrlfile, \csname ver@scrlfile.sty\endcsname%
+ ^^J\@spaces\@spaces\@spaces\@spaces\space\space
+ Copyright (C) Markus Kohm^^J}
+% \end{macrocode}
+%
+%
+% \subsection{Options}
+%
+% Currently there are no options.
+% \begin{macrocode}
+\ExecuteOptions{}
+\ProcessOptions\relax
+% \end{macrocode}
+%
+%
+% \subsection{The macros}
+%
+% \begin{macro}{\InputIfFileExists}
+% \LaTeX{} uses this macro for loading files with
+% \cs{input}\marg{filename}, \cs{include}, \cs{LoadClass},
+% \cs{LoadClassWithOptions}, \cs{documentclass}, \cs{documentstyle},
+% \cs{RequirePackage}, \cs{usepackage}. Only
+% \cs{input}~\meta{filename} loads \meta{filename} without using
+% \cs{InputIfFileExists}.
+%
+% Because of this, it's very easy to add stuff before and after
+% loading a file. We simply change this macro and add to
+% macros\,---\,one before loading the file and one after loading the
+% file. But before we redefine the macro, we test, if the macro was
+% defined like we expected. \LaTeX{} will warn, if not.
+% \begin{macrocode}
+\CheckCommand{\InputIfFileExists}[2]{%
+ \IfFileExists{#1}%
+ {#2\@addtofilelist{#1}\@@input \@filef@und}}
+% \end{macrocode}
+% Now we can redefine the macro like described above:
+% \begin{macrocode}
+\renewcommand{\InputIfFileExists}[2]{%
+ \IfFileExists{#1}{%
+ \scr@load@hook{before}{#1}%
+ #2\@addtofilelist{#1}\@@input \@filef@und
+ \scr@load@hook{after}{#1}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\scr@load@hook}
+% This macro simply calls a load-file-hook, either the \emph{before}
+% or the \emph{after} one, if the hook exists. After calling the hook
+% it will be deleted. First argument is the type of hook
+% (\meta{before} or \meta{after}), second argument is a filename.
+% \begin{macrocode}
+\newcommand*{\scr@load@hook}[2]{%
+ \@ifundefined{#2-@#1}{}{%
+ \@nameuse{#2-@#1}%
+ \expandafter\let\csname #2-@#1\endcsname=\relax}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\scr@set@load@hook}
+% This command adds stuff to a load-file-hook, either the
+% \emph{before} or the \emph{after} one. First argument is the type of
+% hook (\meta{before} or \meta{after}), second is a filename. There's
+% a third argument not parsed by the macro itself but
+% \cs{g@addto@macro}. This third argument is the stuff, which will be
+% added to the hook. Because of using \cs{g@addto@macro} the hook must
+% be defined. So we define it, if it isn't.
+% \begin{macrocode}
+\newcommand*{\scr@set@load@hook}[2]{%
+ \@ifundefined{#2-@#1}{\@namedef{#2-@#1}{}}{}%
+ \expandafter\g@addto@macro\csname #2-@#1\endcsname}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\BeforeFile}
+% \begin{macro}{\AfterFile}
+% \begin{macro}{\BeforeClass}
+% \begin{macro}{\AfterClass}
+% \begin{macro}{\@AfterClass}
+% \begin{macro}{\@sAfterClass}
+% \begin{macro}{\BeforePackage}
+% \begin{macro}{\AfterPackage}
+% \begin{macro}{\@AfterPackage}
+% \begin{macro}{\@sAfterPackage}
+% These macros add stuff to a load-file-hook of a file, class or
+% package. First argument is the name of the file (with extension),
+% class (without extension) or package (without extension). There's a
+% second argument parsed by wether the macros themself nor
+% \cs{scr@set@load@hook} but \cs{g@addto@macro}. See
+% \cs{scr@set@load@hook} for more information. The star-forms
+% \cs{AfterClass*} and \cs{AfterPackage*} does the action immediate,
+% if the class or package was already loaded.
+% \begin{macrocode}
+\newcommand*{\BeforeFile}{\scr@set@load@hook{before}}
+\newcommand*{\AfterFile}{\scr@set@load@hook{after}}
+\newcommand*{\BeforeClass}[1]{%
+ \scr@set@load@hook{before}{#1.\@clsextension}}
+\newcommand*{\AfterClass}{%
+ \@ifstar {\@sAfterClass}{\@AfterClass}}
+\newcommand*{\@AfterClass}[1]{%
+ \scr@set@load@hook{after}{#1.\@clsextension}}
+\newcommand*{\@sAfterClass}[1]{%
+ \begingroup
+ \@ifclassloaded{#1}{%
+ \aftergroup\@secondoftwo
+ }{%
+ \aftergroup\@AfterClass
+ }%
+ \endgroup
+ {#1}%
+}
+\newcommand*{\BeforePackage}[1]{%
+ \scr@set@load@hook{before}{#1.\@pkgextension}}
+\newcommand*{\AfterPackage}{%
+ \@ifstar {\@sAfterPackage}{\@AfterPackage}}
+\newcommand*{\@AfterPackage}[1]{%
+ \scr@set@load@hook{after}{#1.\@pkgextension}}
+\newcommand*{\@sAfterPackage}[1]{%
+ \begingroup
+ \@ifpackageloaded{#1}{%
+ \aftergroup\@secondoftwo
+ }{%
+ \aftergroup\@AfterPackage
+ }%
+ \endgroup
+ {#1}%
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\BeforeClosingMainAux}
+% \changes{v2.95}{2002/09/03}{new}
+% This is completly different. First we have to establish a new hook
+% at \cs{end\{document\}}, just after closing the group and after the
+% final \cs{clearpage}.
+% \begin{macrocode}
+\AtEndDocument{%
+ \let\scr@saved@checkend=\@checkend
+ \renewcommand*{\@checkend}[1]{%
+ \def\reserved@a{#1}\def\reserved@b{document}%
+ \scr@saved@checkend{#1}%
+ \ifx\reserved@a\reserved@b
+ \let\scr@saved@clearpage=\clearpage
+ \renewcommand*{\clearpage}{\scr@saved@clearpage
+ \scr@hook@bcma\let\clearpage=\scr@saved@clearpage}%
+ \fi%
+ }%
+}
+% \end{macrocode}
+% \begin{macro}{\scr@saved@checkend}
+% \changes{v2.95}{2002/09/03}{new (internal)}
+% You may see above, that we need a save-to macro.
+% \begin{macrocode}
+\newcommand*{\scr@saved@checkend}{}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\scr@hook@bcma}
+% \changes{v2.95}{2002/09/03}{new (internal)}
+% We also need a macro, that saves the commands at the hook and is
+% extendable using \cs{g@addto@macro}. Here we also warn, if we detect
+% one more \cs{newpage}\,---\,maybe at a \cs{clearpage} or
+% \cs{cleardoublepage}.
+% \begin{macrocode}
+\newcommand*{\scr@hook@bcma}{%
+ \renewcommand*{\BeforeClosingMainAux}[1]{##1}%
+ \renewcommand*{\newpage}{%
+ \PackageError{%
+ scrlfile%
+ }{%
+ \string\newpage\space at \string\BeforeClosingMainAux
+ }{%
+ You should never use \string\newpage\space or
+ \string\clear(double)page or other output material at the\MessageBreak
+ argument of \string\BeforeClosingMainAux!\MessageBreak
+ If you'll continue, the \string\newpage\space will be ignored to
+ avoid corruption of\MessageBreak
+ every prior use of \string\BeforeClosingMainAux.
+ }%
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+% Now we are able to write the user command.
+% \begin{macrocode}
+\newcommand*{\BeforeClosingMainAux}{%
+ \g@addto@macro\scr@hook@bcma%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \Finale
+%
+% \iffalse
+%</scrlfile>
+%<*load>
+% Used at \KOMAScript{} classes.
+% \begin{macrocode}
+\edef\@tempa{\noexpand\RequirePackage{scrlfile}[\scrlfileversion]}
+\@tempa
+% \end{macrocode}
+%</load>
+% \fi
+%
+\endinput
+%
+% end of file `scrlfile.dtx'
+
+%%% Local Variables:
+%%% mode: doctex
+%%% Text-master: t
+%%% End: