diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/scrlfile.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/scrlfile.dtx | 525 |
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: |