diff options
author | Karl Berry <karl@freefriends.org> | 2008-11-12 00:44:32 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2008-11-12 00:44:32 +0000 |
commit | e0fa36719ae8b943d0c515ccc2a4f1e2670cc614 (patch) | |
tree | cfd7d451101897cf222cd885a36573ccacd922c4 /Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrbase.tex | |
parent | 6d06dddb5a2041f7c07b6502a3bfa973f0d86635 (diff) |
koma-script update (11nov08)
git-svn-id: svn://tug.org/texlive/trunk@11262 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrbase.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrbase.tex | 1139 |
1 files changed, 1139 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrbase.tex b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrbase.tex new file mode 100644 index 00000000000..c591afe687f --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/ngerman/scrbase.tex @@ -0,0 +1,1139 @@ +% ====================================================================== +% scrbase.tex +% Copyright (c) Markus Kohm, 2002-2008 +% +% 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. +% ---------------------------------------------------------------------- +% scrbase.tex +% Copyright (c) Markus Kohm, 2002-2008 +% +% 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. +% ====================================================================== +% +% Package scrbase for Package and Class Authors +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Paket scrbase für Paket- und Klassenautoren +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\ProvidesFile{scrbase.tex}[2008/07/31 KOMA-Script package scrbase] + +\chapter{Grundlegende Funktionen im Paket \Package{scrbase}} +\labelbase{scrbase} + +\BeginIndex{Package}{scrbase}% + +Das Paket \Package{scrbase} stellt einige grundlegende Funktionen bereit, die +sich an Autoren von Paketen und Klassen richten. Dabei kann es nicht nur für +Wrapper-Klassen genutzt werden, die ihrerseits eine \KOMAScript-Klasse +laden. Auch Autoren von Klassen, die ansonsten nichts mit \KOMAScript{} zu tun +haben, können von der Funktionalität von \Package{scrbase} profitieren. + +\section{Laden des Pakets} +\label{sec:scrbase.loadit} + +Während Anwender ein Paket mit Hilfe von \Macro{usepackage} laden, verwenden +Paket- und Klassenautoren \Macro{RequirePackage}. Autoren von Wrapper-Paketen +nutzen auch \Macro{RequirePackageWithOptions}. Bei Verwendung von +\Macro{RequirePackage} können wie bei \Macro{usepackage} Optionen angegeben +werden. Demgegenüber erhält das Paket bei \Macro{RequirePackageWithOptions} +die Optionen, mit denen das Wrapper-Paket geladen wurde. Näheres zu diesen +Anweisungen ist \cite{latex:clsguide} zu entnehmen. + +Das Paket \Package{scrbase} benötigt intern die Funktionalität des Pakets +\Package{keyval}\IndexPackage{keyval}. Diese kann auch vom Paket +\Package{xkeyval} zur Verfügung gestellt werden. Bei Bedarf lädt +\Package{scrbase} selbst \Package{keyval}. + +Das Paket \Package{keyval} erlaubt es, Schlüssel zu definieren und diesen +Werten zuzuweisen. Auch die Optionen, die \Package{scrbase} bereitstellt, +verwenden die \Package{keyval}-Syntax: \PName{Schlüssel}\texttt{=}\PName{Wert}. + +\BeginIndex{Option}{internalonly~=\PName{Wert}}% +\begin{Declaration} + \KOption{internalonly}\PName{Wert} +\end{Declaration} +Von \Package{scrbase} werden einige Verzweigungsanweisungen +bereitgestellt. Dabei verwendet es primär die Bezeichnungen +\Macro{scr@\PName{Anweisungsname}}. Es handelt sich somit um interne +Anweisungen. Diese werden auch intern von \KOMAScript{} verwendet. Paket- und +Klassenautoren können diese Anweisungen ebenfalls verwenden, sollten sie aber +nicht umdefinieren. Da einige dieser Anweisungen auch für Benutzer nützlich +sein können, werden die gleichen Anweisungen normalerweise auch als +\Macro{\PName{Anweisungsname}} bereitgestellt. Da eventuell andere Pakete +gleichnamige Anweisungen mit anderer Syntax bereitstellen könnten und es so zu +Konflikten kommen könnte, kann der Anwender die Definition von +\Macro{\PName{Anweisungsname}} verhindern. Dazu gibt er entweder die Option +ohne Wertangabe an. In diesem Fall werden nur die internen +Verzweigungsanweisungen definiert. Oder er gibt genau die Anweisungen, die +nicht definiert werden sollen, als Wert an, wobei er »\Macro{}« durch +»\texttt{/}« ersetzt. + +Paket- und Klassenautoren sollten diese Option normalerweise nicht verwenden. +Anwender können sie mit oder ohne Wertangabe entweder als globale Option bei +\Macro{documentclass} oder per \Macro{PassOptionsToPackage} angeben. +\begin{Example} + Der Anwender will nicht, dass die Anweisungen \Macro{ifVTeX} und + \Macro{ifundefinedorrelax} von \Package{scrbase} definiert werden. Also + verwendet er beim Laden der Klasse: + \begin{lstcode} + \documentclass% + [internalonly=/ifVTeX/ifundefinedorrelax]% + {foo} + \end{lstcode} + Der Klassenname \Class{foo} wird hier als Platzhalter für irgend eine Klasse + verwendet. Die Bedeutungen der Anweisungen \Macro{ifVTeX} und + \Macro{ifundefinedorrelax} sowie weitere Verzweigungsanweisungen sind + \autoref{sec:scrbase.if} zu entnehmen. +\end{Example} +% +\EndIndex{Option}{internalonly~=\PName{Wert}}% + + +\section{Schlüssel als Eigenschaften von Familien und deren Mitgliedern} +\label{sec:scrbase.keyvalue} + +Wie bereits in \autoref{sec:scrbase.loadit} erwähnt, setzt \Package{scrbase} +bei Schlüsseln und deren Werte auf das Paket \Package{keyval}. Allerdings +erweitert es dessen Funktionalität. Während bei \Package{keyval} ein Schlüssel +einer Familie gehört, kennt \Package{keyval} zu jeder Familie auch noch +Familienmitglieder. Ein Schlüssel kann dann sowohl einer Familie als auch +einem oder mehreren Familienmitgliedern gehören. Außerdem kann ein Wert einem +Schlüssel eines Familienmitglieds, einem Schlüssel einer Familie oder einem +Schlüssel aller Familienmitglieder zugewiesen werden. + +\BeginIndex{Cmd}{DefineFamily}% +\BeginIndex{Cmd}{DefineFamilyMember}% +\begin{Declaration} + \Macro{DefineFamily}\Parameter{Familienname}\\ + \Macro{DefineFamilyMember}\OParameter{Mitglied}\Parameter{Familienname} +\end{Declaration} +\Package{scrbase} muss aus verschiedenen Gründen die Mitglieder einer Familie +kennen. Daher ist es notwendig, eine neue Familie zunächst mit +\Macro{DefineFamily} zu definieren und so eine leere Mitgliederliste zu +erzeugen. Ist die Familie bereits definiert, so geschieht schlicht nichts. Es +wird also auch nicht eine bereits existierende Mitgliederliste überschrieben. + +Ein neues Mitglied wird der Familie dann mit \Macro{DefineFamilyMember} +bekannt gegeben. Existiert die Familie nicht, so führt dies zu einer +Fehlermeldung. Existiert das Mitglied bereits, so geschieht nichts. Wird kein +Mitglied angegeben, so bleibt das Mitglied nicht etwa leer, sondern es wird +»\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}« +angenommen. Während des Ladens einer Klasse oder eines Pakets sind +\Macro{@currname} und \Macro{@currext} zusammen der Dateiname. + +Theoretisch wäre es möglich, mit einem leeren optionalen Argument +\PName{Mitglied} auch ein Mitglied ohne Name zu definieren. Dies würde jedoch +der Familie selbst entsprechen. Es wird empfohlen als \PName{Familienname} nur +Buchstaben und Ziffern zu verwenden und das \PName{Mitglied} immer mit einem +anderen Zeichen zu verwenden. Anderenfalls könnte es passieren, dass sich +Mitglieder einer Familie mit Mitgliedern anderer Familien überdecken. + +\Package{scrbase} definiert selbst bereits die Familie »\PValue{KOMA}« und +fügt ihr das Mitglied »\PValue{.scrbase.sty}« hinzu. Grundsätzlich ist die +Familie »\PValue{KOMA}« \KOMAScript{} vorbehalten. Es wird empfohlen für +eigene Pakete den Namen des Gesamtpakets als Familie und den Namen einzelner +Pakete im Gesamtpaket als Mitglied zu verwenden. + +\begin{Example} + Angenommen Sie schreiben ein neues Gesamtpaket »Fleischermeister«. Darin + befinden sich die Pakete \File{Salami.sty}, \File{Mettwurst.sty} und + \File{Krakauer.sty}. Daher entscheiden Sie sich für den Familienname + »\PValue{Fleischermeister}« und fügen in jedem der Pakete die Zeilen + \begin{lstcode} + \DefineFamily{Fleischermeister} + \DefineFamilyMember{Fleischermeister} + \end{lstcode} + ein. Dadurch werden dann beim Laden der Pakete der Familie + »\PValue{Fleischermeister}« je nach Paket eines der drei Mitglieder + »\PValue{.Salami.sty}«, »\PValue{.Mettwurst.sty}« und + »\PValue{.Krakauer.sty}« zugefügt. +\end{Example} +% +\EndIndex{Cmd}{DefineFamilyMember}% +\EndIndex{Cmd}{DefineFamily}% + +\BeginIndex{Cmd}{DefineFamilyKey}% +\begin{Declaration} + \Macro{DefineFamilyKey}\OParameter{Mitglied}\Parameter{Familie}% + \Parameter{Schlüssel}\OParameter{Säumniswert}\Parameter{Aktion} +\end{Declaration} +Mit dieser Anweisung wird ein \PName{Schlüssel} definiert. Ist ein +\PName{Mitglied} angegeben, so ist der \PName{Schlüssel} eine Eigenschaft +dieses Mitglieds der angegebenen \PName{Familie}Familie. Ist kein Mitglied +angegeben, so wird wieder das Mitglied +»\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}« angenommen. Wird +später dem \PName{Schlüssel} ein Wert zugewiesen, so wird \PName{Aktion} +ausgeführt, wobei der Wert als Parameter übergeben wird. Innerhalb von +\PName{Aktion} steht also »\lstinline{#1}« für den übergebenen Wert. Wurde +kein Wert übergeben, so wird stattdessen der \PName{Säumniswert} +eingesetzt. Falls kein \PName{Säumniswert} angegeben wird, kann später der +\PName{Schlüssel} nur mit Wertübergabe verwendet werden. +\begin{Explain} + \phantomsection\label{explain:scrbase.macro.DefineFamilyKey}% + Letztlich führt + \begin{lstcode}[escapeinside=»«] + \DefineFamilyKey[»\PName{Mitglied}«]{»\PName{Familie}«}{»\PName{Schlüssel}«} + [»\PName{Säumniswert}«]{»\PName{Aktion}«} + \end{lstcode} +\iffalse% oder so + \begin{flushleft}\begin{tabular}{l@{}l} + \Macro{DefineFamilyKey}&\OParameter{Mitglied}\Parameter{Familie}% + \Parameter{Schlüssel}\\ + &\OParameter{Säumniswert}\Parameter{Aktion} + \end{tabular}\end{flushleft} +\fi + zu dem Aufruf + \begin{lstcode}[belowskip=\dp\strutbox, + moretexcs={define@key},escapeinside=»«] + \define@key{»\PName{Familie\,Mitglied}«}{»\PName{Schlüssel}«} + [»\PName{Säumniswert}«]{»\PName{Aktion}«} + \end{lstcode} +\iffalse% oder so + \begin{flushleft}\begin{tabular}{l@{}l} + \Macro{define@key}&\Parameter{Familie\,Mitglied}% + \Parameter{Schlüssel}\\ + &\OParameter{Säumniswert}\Parameter{Aktion} + \end{tabular}\end{flushleft} +\fi + wobei \Macro{define@key} im \Package{keyval}-Paket\IndexPackage{keyval} + definiert ist (siehe \cite{package:keyval}). +\iffalse% Umbruchkorrektur + Prinzipiell könnte daher dem + Schlüssel eines Familienmitglieds per + \begin{lstcode}[belowskip=\dp\strutbox, + moretexcs={setkeys},escapeinside=»«] + \setkeys{»\PName{Familie\,Mitglied}«}{»\PName{Schlüssel}«=»\PName{Wert}«} + \end{lstcode} +\iffalse% oder so + \begin{flushleft}\begin{tabular}{l@{}l} + \Macro{setkeys}&\Parameter{Familie\,Mitglied}\Parameter{Schlüssel=Wert} + \end{tabular}\end{flushleft} +\fi + ein Wert zugewiesen werden. +\fi +\end{Explain} +\begin{Example} + Nehmen wir an, jedes der drei Pakete aus dem letzten Beispiel soll einen + Schlüssel \PValue{Aufschnitt} erhalten. Wird dieser aufgerufen, so soll in + jedem der Pakete entsprechend dem Aufrufwert ein Schalter gesetzt + werden. Für das Paket \Package{Salami} könnte das beispielsweise so + aussehen: + \begin{lstcode} + \newif\if@Salami@Aufschnitt + \DefineFamilyKey{Fleischermeister}% + {Aufschnitt}[true]{% + \expandafter\let\expandafter\if@Salami@Aufschnitt + \csname if#1\endcsname + } + \end{lstcode} + Als Wert sind daher beim Aufruf \PValue{true} oder \PValue{false} + erlaubt. Ein Test auf unerlaubte Werte existiert in diesem Beispiel + nicht. Wird der Schlüssel später verwendet, so muss entweder einer der + erlaubten Werte zugewiesen oder ein Aufruf ohne Wertzuweisung verwendet + werden. In letzterem Fall wird der Säumniswert \PName{true} zugewiesen. + + Für die anderen beiden Pakete kann das fast identisch definiert + werden. Lediglich die Zeichenfolge »\texttt{Salami}« ist jeweils zu + ersetzen. +\end{Example} +% +\EndIndex{Cmd}{DefineFamilyKey}% + + +\BeginIndex{Cmd}{FamilyProcessOptions}% +\begin{Declaration} + \Macro{FamilyProcessOptions}\OParameter{Mitglied}\Parameter{Familie} +\end{Declaration} +Grundsätzlich ist die Erweiterung der Schlüssel von Familien auf Familien +und Familienmitglieder dazu gedacht, dass Schlüssel beziehungsweise die +Wertzuweisung an Schlüssel als ganz normale Klassen- oder Paketoptionen +verwendet werden kann. Diese Anweisung stellt daher ein Erweiterung von +\Macro{ProcessOptions*} aus dem \LaTeX-Kern dar (siehe +\cite{latex:clsguide}). Dabei verarbeitet die Anweisung nicht nur Optionen, +die mit \Macro{DeclareOption} definiert wurden. Es werden auch alle Schlüssel +eines angegebenen Familienmitglieds abgearbeitet. Wird das optionale Argument +\PName{Mitglied} nicht angegeben, so wird wieder das Mitglied +»\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}« verwendet. + +Eine Besonderheit sind Schlüssel, die nicht einem Familienmitglied, sondern +der Familie selbst zugeordnet sind, bei der also das Mitglied leer geblieben +ist. Diese werden ebenfalls gesetzt und zwar noch bevor der Schlüssel des +Mitglieds gesetzt wird. +\begin{Example} + Wenn in den Paketen aus den zurückliegenden Beispielen die Zeile + \begin{lstcode} + \FamilyProcessOptions{Fleischermeister} + \end{lstcode} + ergänzt wird, so kann der Anwender bereits beim Laden der Pakete, die + Eigenschaft \Option{Aufschnitt} wählen. Wird die Option global, also bei + \Macro{documentclass} angegeben, so wird die Eigenschaft automatisch bei + allen drei Paketen gesetzt, wenn alle drei Pakete geladen werden. +\end{Example} +Es wird darauf hingewiesen, dass bei Paketen globale Optionen vor den lokal +dem Paket zugewiesenen Optionen ausgeführt werden. + +Man kann die Anweisung statt als Erweiterung von \Macro{ProcessOption*} auch +als Erweiterung des \PName{Schlüssel=Wert}-Mechanismus von \Package{keyval} +verstehen. Mit Hilfe von \Macro{FamilyProcessOptions} werden aus +\PName{Schlüssel} oder \PName{Schlüssel=Wert}-Paaren Optionen. +% +\EndIndex{Cmd}{FamilyProcessOptions}% + + +\BeginIndex{Cmd}{FamilyExecuteOptions}% +\begin{Declaration} + \Macro{FamilyExecuteOptions}\OParameter{Mitglied}\Parameter{Familie}% + \Parameter{Optionenliste} +\end{Declaration} +Diese Anweisung stellt ein Erweiterung von +\Macro{ExecuteOptions} aus dem \LaTeX-Kern dar (siehe +\cite{latex:clsguide}). Dabei verarbeitet die Anweisung nicht nur Optionen, +die mit \Macro{DeclareOption} definiert wurden. Es werden auch alle Schlüssel +eines angegebenen Familienmitglieds abgearbeitet. Wird das optionale Argument +\PName{Mitglied} nicht angegeben, so wird wieder das Mitglied +»\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}« verwendet. + +Eine Besonderheit sind Schlüssel, die nicht einem Familienmitglied, sondern +der Familie selbst zugeordnet sind, bei der also das Mitglied leer geblieben +ist. Diese werden ebenfalls gesetzt und zwar noch bevor der Schlüssel des +Mitglieds gesetzt wird. +\begin{Example} + Angenommen, die Option \Option{Aufschnitt} soll in den zurückliegenden + Beispielen bereits als Voreinstellung gesetzt werden, so müssen die Pakete + nur um die Zeile + \begin{lstcode} + \FamilyExecuteOptions{Fleischermeister}{Aufschnitt} + \end{lstcode} + ergänzt werden. +\end{Example} +% +\EndIndex{Cmd}{FamilyExecuteOptions}% + + +\BeginIndex{Cmd}{FamilyOptions}% +\BeginIndex{Cmd}{Family@Options}% +\begin{Declaration} + \Macro{FamilyOptions}\Parameter{Familie}\Parameter{Optionenliste}\\ + \Macro{Family@Options}\Parameter{Familie}\Parameter{Optionenliste}% + \Parameter{Fehleraktion} +\end{Declaration} +Die \PName{Optionenliste} hat dabei die Form: +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \PName{Schlüssel}\texttt{=}\PName{Wert}\texttt{,}% + \PName{Schlüssel}\texttt{=}\PName{Wert}\dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +wobei für \PName{Schlüssel}, für die ein Säumniswert definiert ist, die +Wertzuweisung natürlich auch entfallen kann. + +Im Gegensatz zu normalen Optionen, die mit \Macro{DeclareOption} definiert +wurden, können die \PName{Schlüssel} auch noch nach dem Laden der Klasse oder +des Pakets gesetzt werden. Dazu verwendet der Anwender +\Macro{FamilyOptions}. Dabei werden die \PName{Schlüssel} aller Mitglieder der +angegebenen \PName{Familie} gesetzt. Existiert ein \PName{Schlüssel} auch als +Eigenschaft der Familie selbst, so wird dieser Familien-Schlüssel zuerst +gesetzt. Danach folgen die Mitglieder-Schlüssel in der Reihenfolge, in der die +Mitglieder definiert wurden. Existiert ein angegebener \PName{Schlüssel} weder +für die Familie noch für ein Mitglied der Familie, so wird von +\Macro{FamilyOptions} ein Fehler ausgegeben. Bei \Macro{Family@Options} kann +man hingegen die Fehleraktion selbst wählen. Diese interne Anweisung ist +Klassen- und Paketautoren vorbehalten. +\begin{Example} + Sie ergänzen das Fleischermeister-Projekt um ein weiteres Paket + Wurstsalat. Wird dieses Paket verwendet, so sollen alle Wurstpakete zunächst + einmal Aufschnitt produzieren: + % Umbruchkorrektur + \begin{lstcode}[aboveskip=.75\baselineskip] + \ProvidesPackage{Wurstsalat}% + [2008/05/06 nonsense package] + \DefineFamily{Fleischermeister} + \DefineFamilyMember{Fleischermeister} + \FamilyProcessOptions{Fleischermeister}\relax + \FamilyOptions{Fleischermeister}{Aufschnitt} + \end{lstcode} + Sollte noch kein Wurst-Paket geladen sein, so würde nun eine Fehlermeldung + wegen der nicht definierten Option »\Option{Aufschnitt}« ausgegeben. Das + kann vermieden werden, wenn die letzte Zeile in + % Umbruchkorrektur + \begin{lstcode}[moretexcs={Family@Options},aboveskip=.75\baselineskip] + \Family@Options{Fleischermeister}{Aufschnitt}{} + \end{lstcode} + geändert wird. Allerdings produzieren so Wurst-Pakete, die nach + \Package{Fleischwurst} geladen werden, keinen Aufschnitt. Dies kann man + ebenfalls ändern, wenn die letzte Zeile erneut überarbeitet wird: + % Umbruchkorrektur + \begin{lstcode}[moretexcs={Family@Options},aboveskip=.75\baselineskip] + \AtBeginDocument{% + \Family@Options{Fleischermeister}{Aufschnitt}{% + \PackageWarning{Wurstsalat}{% + Wurstsalat benötigt mindestens ein Wurst-Paket}% + }% + }% + \end{lstcode} + Statt auf jegliche Meldung zu verzichten, falls kein Wurst-Paket geladen + ist, wird nun auch gleich noch eine Warnung ausgegeben. +\end{Example} +% +\EndIndex{Cmd}{Family@Options}% +\EndIndex{Cmd}{FamilyOptions}% + +\BeginIndex{Cmd}{FamilyOption}% +\BeginIndex{Cmd}{Family@Option}% +\begin{Declaration} + \Macro{FamilyOption}\Parameter{Familie}% + \Parameter{Option}\Parameter{Werteliste}\\ + \Macro{Family@Option}\Parameter{Familie}% + \Parameter{Option}\Parameter{Werteliste}\Parameter{Fehleraktion} +\end{Declaration} +Neben Optionen, die sich gegenseitig ausschließende Werte besitzen, kann es +auch Optionen geben, die gleichzeitig mehrere Werte annehmen können. Für diese +wäre es bei Verwendung von \Macro{FamilyOptions} notwendig, der Option mehrfach +einen Wert zuzuweisen und dabei die Option selbst mehrfach +anzugeben. Stattdessen kann man einfach mit \Macro{FamilyOption} einer +einzigen \PName{Option} eine ganze \PName{Werteliste} zuweisen. Die +\PName{Werteliste} ist dabei eine durch Komma separierte Liste von Werten: +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \PName{Wert}\texttt{,}\PName{Wert}\dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +In diesem Zusammenhang sei darauf hingewiesen, dass die Verwendung eines +Kommas in einem Wert möglich ist, wenn man den Wert in geschweifte Klammern +setzt. Die weiteren Funktionsweise ist der vorhergehenden Erklärung zu +\Macro{FamilyOptions} und \Macro{Family@Options} zu entnehmen. +\begin{Example} + Das Paket \Package{Wurstsalat} soll eine Option bekommen, über die man + weitere Zutaten bestimmen kann. Für jede Zutat wird dabei wieder ein + Schalter gesetzt. + \begin{lstcode} + \newif\if@salatmit@Zwiebeln + \newif\if@salatmit@Gurken + \newif\if@salatmit@Peperoni + \DefineFamilyKey{Fleischermeister}{SalatZusatz}{% + \csname @salatmit@#1true\endcsname + } + \end{lstcode} + Es wurden hier die drei Zutaten »Zwiebeln«, »Gurken« und »Peperoni« + definiert. Eine Fehlerbehandlung für den Fall, dass der Anwender unbekannte + Zutaten fordert, existiert nicht. + + Für einen Salat mit Zwiebeln und Gurken, kann der Anwender + \begin{lstcode} + \FamilyOptions{Fleischermeister}{% + SalatZusatz=Zwiebeln,SalatZusatz=Gurken} + \end{lstcode} + oder einfach + \begin{lstcode} + \FamilyOption{Fleischermeister}% + {SalatZusatz}{Zwiebeln,Gurken} + \end{lstcode} + verwenden. +\end{Example} +% +\EndIndex{Cmd}{Family@Option}% +\EndIndex{Cmd}{FamilyOption}% + +\BeginIndex{Cmd}{FamilyBoolKey}% +\BeginIndex{Cmd}{FamilySetBool}% +\begin{Declaration} + \Macro{FamilyBoolKey}\OParameter{Mitglied}\Parameter{Familie}% + \Parameter{Schlüssel}\Parameter{Schaltername}\\ + \Macro{FamilySetBool}\Parameter{Familie}% + \Parameter{Schlüssel}\Parameter{Schaltername}\Parameter{Wert} +\end{Declaration} +In den vorherigen Beispielen wurden schon mehrfach Schalter gesetzt. Im +Beispiel der Option \Option{Aufschnitt} war es dabei notwendig, dass der +Anwender als Werte \PValue{true} oder \PValue{false} angibt. Es existierte +keine Fehlerbehandlung, falls der Anwender einen falschen Wert verwendet. Da +solche boolschen Schalter ein häufiger Anwendungsfall sind, kann man sie bei +\Package{scrbase} einfach mit \Macro{FamilyBoolKey} definieren. Dabei sind die +Argumente \PName{Mitglied}, \PName{Familie} und \PName{Schlüssel} die gleichen +wie bei \Macro{DefineFamilyKey} (siehe +\autopageref{desc:scrbase.cmd.DefineFamilyKey}). Das Argument +\PName{Schaltername} ist der Name eines Schalter ohne den Präfix +\Macro{if}. Existiert dieser Schalter noch nicht, so wird er automatisch +definiert und mit \PName{false} voreingestellt. Intern verwendet +\Macro{FamilyBoolKey} dann \Macro{FamilySetBool} als \PName{Aktion} für +\Macro{DefineFamilyKey}. Der Säumniswert für eine solche Option ist immer +\PValue{true}. + +\Macro{FamilySetBool} wiederum versteht als \PName{Wert} neben +\PValue{true} auch die Werte \PValue{on} und \PValue{yes} zum Einschalten und +neben \PValue{false} auch die Werte \PValue{off} und \PValue{no} zum +Ausschalten. Wird ein unbekannter Wert übergeben, so wird die Anweisung +\Macro{FamilyUnkownKeyValue} mit den Argumenten \PName{Familie}, +\PName{Schlüssel} und \PName{Wert} aufgerufen. Dadurch wird dann eine +Fehlermeldung über unbekannte Wertzuweisung ausgegeben (siehe auch +\autopageref{desc:scrbase.cmd.FamilyUnkownKeyValue}). +\begin{Example} + Der Schlüssel \Option{Aufschnitt} soll in den Wurstpaketen etwas robuster + definiert werden. Außerdem sollen alle Wurstpakete denselben Schalter + verwenden, so dass entweder alle Wurstpakete Aufschnitt produzieren oder + keines. + \begin{lstcode} + \FamilyBoolKey{Fleischermeister}{Aufschnitt}% + {@Aufschnitt} + \end{lstcode} + Ein Test, ob Aufschnitt produziert wird sähe dann so aus: + \begin{lstcode} + \if@Aufschnitt + ... + \else + ... + \fi + \end{lstcode} + Dies wäre dann in allen drei Wurstpaketen identisch. Damit könnte man + prinzipiell die Eigenschaft »Aufschnitt« auch als Eigenschaft der Familie + definieren: + \begin{lstcode}[moretexcs={define@key}] + \@ifundefined{if@Aufschnitt}{% + \expandafter\newif\csname if@Aufschnitt\endcsname + }{}% + \define@key{Fleischermeister}{Aufschnitt}[true]{% + \FamilySetBool{Fleischermeister}{Aufschnitt}% + {@Aufschnitt}{#1}% + } + \end{lstcode} + oder einfacher + \begin{lstcode} + \FamilyBoolKey[]{Fleischermeister}{Aufschnitt}% + {@Aufschnitt} + \end{lstcode} + unter Ausnutzung des weiterführenden Hinweises auf + \autopageref{explain:scrbase.macro.DefineFamilyKey}, der nicht nur für + \Macro{DefineFamilyKey}, sondern entsprechend auch für \Macro{FamilyBoolKey} + gilt. +\end{Example} +% +\EndIndex{Cmd}{FamilySetBool}% +\EndIndex{Cmd}{FamilyBoolKey} + +\BeginIndex{Cmd}{FamilyNumericalKey}% +\BeginIndex{Cmd}{FamilySetNumerical}% +\begin{Declaration} + \Macro{FamilyNumericalKey}\OParameter{Mitglied}\Parameter{Familie}\\ + \hphantom{\XMacro{FamilyNumericalKey}}% + \Parameter{Schlüssel}\OParameter{Säumniswert}\Parameter{Makroname}% + \Parameter{Werteliste}\\ + \Macro{FamilySetNumerical}\Parameter{Familie}\\ + \hphantom{\XMacro{FamilySetNumerical}}% + \Parameter{Schlüssel}\Parameter{Makroname}\Parameter{Werteliste}% + \Parameter{Wert} +\end{Declaration} +% +Während Schalter nur zwei Werte annehmen können, gibt es auch Schlüssel, die +mehrere Werte kennen. So kann beispielsweise eine Ausrichtung nicht nur links +oder nicht links, sondern beispielsweise links, mittig oder rechts +sein. Intern unterscheidet man solche Einstellungen dann gerne mit Hilfe von +\Macro{ifcase}. Diese \TeX-Anweisung erwartet wiederum einen nummerischen +Wert. Daher heißt bei \Package{scrbase} die Anweisung, mit der man via +\PName{Schlüssel} einem Makro eine Definition zuweisen kann, entsprechend +\Macro{FamilyNumericalKey}. Die \PName{Werteliste} hat dabei die Form +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \Parameter{Wert}\Parameter{Definition}\texttt{,}% + \Parameter{Wert}\Parameter{Definition}\texttt{,}% + \dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +Über diese \PName{Werteliste} werden so nicht nur die erlaubten Werte für den +\PName{Schlüssels} angegeben. Für jeden erlaubten \PName{Wert} wird auch +gleich angegeben, wie bei Verwendung desselben das Makro +\Macro{\PName{Makroname}} definiert werden soll. Üblicherweise werden als +\PName{Definition} schlicht Zahlenwerte angegeben. Es sind aber auch andere +Angaben möglich. Derzeit gibt es aber die Einschränkung, dass +\PName{Definition} voll expandierbar sein muss und bei der Zuweisung auch +expandiert wird. +\begin{Example} + Die Wurst für den Wurstsalat kann unterschiedlich geschnitten werden. So + wäre es denkbar, dass der Aufschnitt einfach ungeschnitten bleibt oder in + grobe oder feine Streifen geschnitten werden soll. Diese Information soll in + der Anweisung \Macro{Schnitt} gespeichert werden. + \begin{lstcode} + \FamilyNumericalKey{Fleischermeister}% + {SalatSchnitt}{Schnitt}{% + {Kein}{Kein},{Nicht}{Kein},% + {Grob}{Grob},% + {Fein}{Fein}% + } + \end{lstcode} + Dass nicht geschnitten werden soll, kann in diesem Fall vom Anwender sowohl + mit + \begin{lstcode} + \FamilyOptions{Fleischermeister}{SalatSchnitt=Kein} + \end{lstcode} + als auch mit + \begin{lstcode} + \FamilyOptions{Fleischermeister}{SalatSchnitt=Nicht} + \end{lstcode} + angegeben werden. In beiden Fällen würde \Macro{Schnitt} mit dem Inhalt + \PValue{Kein} definiert. Es kann durchaus sinnvoll sein, wie in diesem + Beispiel dem Anwender mehrere Werte für denselben Zweck anzubieten. + + Nun ist es sehr wahrscheinlich, dass die Schnittart nicht ausgegeben, + sondern später ausgewertet werden soll. In diesem Fall sind die textuellen + Definitionen aber eher unpraktisch. Definiert man den Schlüssel hingegen als + \begin{lstcode} + \FamilyNumericalKey{Fleischermeister}% + {SalatSchnitt}{Schnitt}{% + {Kein}{0},{Nicht}{0},% + {Grob}{1},% + {Fein}{2}% + } + \end{lstcode} + so kann später einfach in der Form + \begin{lstcode} + \ifcase\Schnitt + % ungeschnitten + \or + % grob geschnitten + \else + % fein geschnitten + \fi + \end{lstcode} + unterschieden werden. +\end{Example} +Intern verwendet \Macro{FamilyNumericalKey} wiederum \Macro{DefineFamilyKey} +mit der Anweisung \Macro{FamilySetNumerical}. Wird an einen solchen Schlüssel +ein unbekannter Wert übergeben, so wird von \Macro{FamilySetNumerical} die +Anweisung \Macro{FamilyUnkownKeyValue} mit den Argumenten \PName{Familie}, +\PName{Schlüssel} und \PName{Wert} aufgerufen. Dadurch wird dann eine +Fehlermeldung über unbekannte Wertzuweisung ausgegeben. +% +\EndIndex{Cmd}{FamilySetNumerical}% +\EndIndex{Cmd}{FamilyNumericalKey}% + +\BeginIndex{Cmd}{FamilyUnkownKeyValue}% +\BeginIndex{Cmd}{FamilyElseValues}% +\begin{Declaration} + \Macro{FamilyUnkownKeyValue}\Parameter{Familie}\Parameter{Schlüssel}% + \Parameter{Wert}\Parameter{Werteliste}\\ + \Macro{FamilyElseValues} +\end{Declaration} +Die Anweisung \Macro{FamilyUnkownKeyValue} gibt eine Fehlermeldung über einen +unbekannten Wert für einen bekannten Schlüssel aus. Als \PName{Werteliste} +wird dabei eine durch Komma separierte Liste von erlaubten Werten der Form +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + `\PName{Wert}'\texttt{,} `\PName{Wert}' \dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +erwartet. Darüber hinaus kann die Anweisung \Macro{FamilyElseValues} weitere +erlaubte Werte in der Form +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + , `\PName{Wert}'\texttt{,} `\PName{Wert}' \dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +enthalten, die dann ebenfalls in der Fehlermeldung mit ausgegeben werden. Die +Anweisungen \Macro{FamilySetBool} und \Macro{FamilySetNumerical} leeren das +Makro \Macro{FamilyElseValues} am Ende automatisch -- unabhängig davon, ob ein +Fehler zu melden war oder nicht. +\begin{Example} + Für den Aufschnitt soll nun zusätzlich wählbar sein, ob er grob oder + fein geschnitten werden soll. Dabei ist grob die Voreinstellung, die auch + dann verwendet werden soll, wenn nicht angegeben wird, wie der Aufschnitt zu + schneiden ist. + \begin{lstcode} + \@ifundefined{if@Feinschnitt}{% + \expandafter + \newif\csname if@Feinschnitt\endcsname}{}% + \@ifundefined{if@Aufschnitt}{% + \expandafter + \newif\csname if@Aufschnitt\endcsname}{} + \DefineFamilyKey{Fleischermeister}% + {Aufschnitt}[true]{% + \ifstr{#1}{fein}{% + \@Aufschnitttrue + \@Feinschnittrue + }{% + \@Feinschnittfalse + \def\FamilyElseValue{, `fein'}% + \FamilySetBool{Fleischermeister}{Aufschnitt}% + {@Aufschnitt}% + {#1}% + }% + }% + \end{lstcode} + Die hierbei verwendete Anweisung \Macro{ifstr} ist in + \autoref{sec:scrbase.if}, \autopageref{desc:scrbase.cmd.ifstr} + erklärt. +\end{Example} +% +\EndIndex{Cmd}{FamilyElseValues}% +\EndIndex{Cmd}{FamilyUnkownKeyValue}% + + +\section{Verzweigungen} +\label{sec:scrbase.if} + +Das Paket \Package{scrbase} stellt eine ganze Reihe von +Verzweigungsanweisungen zur Verfügung. Dabei wird nicht auf die \TeX-Syntax +von Verzweigungen, wie beispielsweise +% Umbruchkorrektur +\begin{lstcode}[belowskip=\dp\strutbox] + \iftrue + ... + \else + ... + \fi +\end{lstcode} +gebaut, sondern es wird die \LaTeX-Syntax mit Argumenten eingesetzt, wie man +sie auch von \LaTeX-Anweisungen wie \Macro{IfFileExists}, +\Macro{@ifundefined}, \Macro{@ifpackageloaded} und vielen weiteren +kennt. Einige Paketautoren ziehen es allerdings vor, die \TeX-Syntax auch für +Anwender in die \LaTeX-Ebene zu bringen. Da es sich bei den Verzweigungen von +\Package{scrbase} um recht grundlegende Möglichkeiten handelt, ist die +Wahrscheinlichkeit gegeben, dass dabei gleichnamige Anwenderanweisungen +verwendet würden. Dies würde selbst bei eigentlich gleicher Semantik +zwangsläufig zu einem Problem aufgrund der unterschiedlichen Syntax +führen. Deshalb definiert \Package{scrbase} einige dieser Anweisungen zunächst +als interne Anweisungen mit dem Präfix \Macro{scr@}. Für den Anwender werden +dann gleichbedeutende Anweisungen ohne diesen Präfix bereit +gestellt. Letzteres kann jedoch mit Hilfe der Option \Option{internalonly} +(siehe \autoref{sec:scrbase.loadit}, +\autopageref{desc:scrbase.option.internalonly}) verhindert werden. + +Paket- und Klassenautoren sollten wie \KOMAScript{} selbst auch die internen +Namen verwenden. Zur Vollständigkeit sind aber auch die Anwenderanweisungen +angegeben. + +\BeginIndex{Cmd}{scr@ifundefinedorrelax}% +\BeginIndex{Cmd}{ifundefinedorrelax}% +\begin{Declaration} + \Macro{scr@ifundefinedorrelax}% + \Parameter{Anweisungsname}\Parameter{Dann-Teil}\Parameter{Sonst-Teil}\\ + \Macro{ifundefinedorrelax}% + \Parameter{Anweisungsname}\Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Diese Anweisung funktioniert prinzipiell wie die Anweisung +\Macro{@ifundefined} aus dem \LaTeX-Kern (siehe \cite{latex:source2e}). Es +wird also der \PName{Dann-Teil} ausgeführt, wenn \PName{Anweisungsname} der +Name einer undefinierten Anweisung oder \Macro{\PName{Anweisungsname}} derzeit +\Macro{relax} ist. Im Unterschied zu der \LaTeX-Kern-Anweisung wird +allerdings \Macro{\PName{Anweisungsname}} nicht als \Macro{relax} definiert, +wenn es zuvor undefiniert war. Bei Verwendung von \eTeX{} wird in diesem Fall +noch nicht einmal Hash-Speicher belegt. +% +\EndIndex{Cmd}{ifundefinedorrelax}% +\EndIndex{Cmd}{scr@ifundefinedorrelax}% + +\BeginIndex{Cmd}{scr@ifpdftex} +\BeginIndex{Cmd}{ifpdftex} +\begin{Declaration} + \Macro{scr@ifpdftex}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil}\\ + \Macro{ifpdftex}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Wird mit pdf\TeX{} gearbeitet, so wird der \PName{Dann-Teil} ausgeführt, +anderenfalls der \PName{Sonst-Teil}. Dabei ist es unerheblich, ob tatsächlich +eine PDF-Datei ausgegeben werden soll, oder nicht. Diese Unterscheidung ist +nur sehr selten wirklich von Nutzen. In der Regel sollte man eher auf die +gewünschte Anweisung testen. +% +\EndIndex{Cmd}{ifpdftex} +\EndIndex{Cmd}{scr@ifpdftex} + +\BeginIndex{Cmd}{scr@ifVTeX} +\BeginIndex{Cmd}{ifVTeX} +\begin{Declaration} + \Macro{scr@ifVTeX}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil}\\ + \Macro{ifVTeX}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Wird mit V\TeX{} gearbeitet, so wird der \PName{Dann-Teil} ausgeführt, +anderenfalls der \PName{Sonst-Teil}. Diese Unterscheidung ist nur sehr selten +wirklich von Nutzen. In der Regel sollte man eher auf die gewünschte Anweisung +testen. +% +\EndIndex{Cmd}{ifVTeX} +\EndIndex{Cmd}{scr@ifVTeX} + +\BeginIndex{Cmd}{scr@ifpdfoutput} +\BeginIndex{Cmd}{ifpdfoutput} +\begin{Declaration} + \Macro{scr@ifpdfoutput}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil}\\ + \Macro{ifpdfoutput}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Wird eine PDF-Datei erzeugt, so wird der \PName{Dann-Teil} ausgeführt, +anderenfalls der \PName{Sonst-Teil}. Dabei ist es unerheblich, ob die +PDF-Datei mit Hilfe von pdf\TeX{} oder mit Hilfe von V\TeX{} erzeugt wird. +% +\EndIndex{Cmd}{ifpdfoutput} +\EndIndex{Cmd}{scr@ifpdfoutput} + +\BeginIndex{Cmd}{scr@ifpsoutput} +\BeginIndex{Cmd}{ifpsoutput} +\begin{Declaration} + \Macro{scr@ifpsoutput}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil}\\ + \Macro{ifpsoutput}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Wird eine PostScript-Datei erzeugt, so wird der \PName{Dann-Teil} ausgeführt, +anderenfalls der \PName{Sonst-Teil}. V\TeX{} unterstützt direkte +PostScript-Ausgabe, die hier auch erkannt wird. Wird hingegen kein V\TeX{} +erkannt, ist aber ein Schalter \Macro{if@dvips} definiert, so wird die +Entscheidung darüber getroffen. \KOMAScript{} stellt \Macro{if@dvips} in +\Package{typearea} bereit. +% +\EndIndex{Cmd}{ifpsoutput} +\EndIndex{Cmd}{scr@ifpsoutput} + +\BeginIndex{Cmd}{scr@ifdvioutput} +\BeginIndex{Cmd}{ifdvioutput} +\begin{Declaration} + \Macro{scr@ifdvioutput}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil}\\ + \Macro{ifdvioutput}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Wird eine DVI-Datei erzeugt, so wird der \PName{Dann-Teil} ausgeführt, +anderenfalls der \PName{Sonst-Teil}. Es wird immer dann davon ausgegangen, +dass eine DVI-Datei erzeugt wird, wenn keine direkte Ausgabe einer PDF- oder +Postscript-Datei erkannt werden kann. +% +\EndIndex{Cmd}{ifdvioutput} +\EndIndex{Cmd}{scr@ifdvioutput} + +\BeginIndex{Cmd}{ifnotundefined} +\begin{Declaration} + \Macro{ifnotundefined}\Parameter{Anweisungsname}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Bei Verwendung von \eTeX{} wird hier tatsächlich getestet, ob die Anweisung +mit dem angegebenen \PName{Anweisungsname} noch undefiniert ist. Dies ist der +Normalfall, da die Verwendung von \eTeX{} für \LaTeX{} offiziell empfohlen +ist. Wird trotzdem kein \eTeX{} verwendet, ist dies hingegen schlicht die +Umkehrung von \Macro{scr@ifundefinedorrelax}. Von dieser Anweisung gibt es +keine interne Variante. +% +\EndIndex{Cmd}{ifnotundefined} + +\BeginIndex{Cmd}{ifstr} +\begin{Declaration} + \Macro{ifstr}\Parameter{Zeichenfolge}\Parameter{Zeichenfolge}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Die beiden Argumente \PName{Zeichenfolge} werden expandiert und dann +verglichen. Sind sie dabei gleich, so wird der \PName{Dann-Teil} ausgeführt, +anderenfalls der \PName{Sonst-Teil}. Von dieser Anweisung gibt es keine +interne Variante. +% +\EndIndex{Cmd}{ifstr} + +\BeginIndex{Cmd}{ifnumber} +\begin{Declaration} + \Macro{ifnumber}\Parameter{Zeichenfolge}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Hier werden keine Zahlen verglichen. Stattdessen wird der \PName{Dann-Teil} +ausgeführt, wenn die Expansion der \PName{Zeichenfolge} nur aus Ziffern +besteht. Anderenfalls wird der \PName{Sonst-Teil} verwendet. Von dieser +Anweisung gibt es keine interne Variante. +% +\EndIndex{Cmd}{ifnumber} + +\BeginIndex{Cmd}{ifdimen} +\begin{Declaration} + \Macro{ifdimen}\Parameter{Zeichenfolge}% + \Parameter{Dann-Teil}\Parameter{Sonst-Teil} +\end{Declaration} +Hier werden keine Längen verglichen. Stattdessen wird der \PName{Dann-Teil} +ausgeführt, wenn die Expansion der \PName{Zeichenfolge} eine gültige Länge mit +einer gültigen Längeneinheit ist. Anderenfalls wird der \PName{Sonst-Teil} +verwendet. Von dieser Anweisung gibt es keine interne Variante. +% +\EndIndex{Cmd}{ifdimen} + +\BeginIndex{Cmd}{if@atdocument}% +\begin{Declaration} + \Macro{if@atdocument} +\end{Declaration} +Diese Verzweigung existiert ganz bewusst nur als interne +Anweisung. Dabei entspricht \Macro{if@atdocument} in der Dokumentpräambel +\Macro{iffalse}, nach \Macro{begin}\PParameter{document} entspricht +\Macro{if@document} hingegen \Macro{iftrue}. Klassen und Paketautoren können +dieses Anweisung manchmal sinnvoll nutzen, wenn sich Anweisungen in der +Dokumentpräambel anders verhalten sollen als innerhalb des Dokuments. Es ist +zu beachten, dass es sich bei dieser Anweisung um eine Verzweigung in +\TeX-Syntax und nicht in \LaTeX-Syntax handelt! +% +\EndIndex{Cmd}{if@atdocument} + + +\section{Definition sprachabhängiger Bezeichner} +\label{sec:scrbase.languageSupport} +\BeginIndex{}{Sprachdefinition} + +Normalerweise muss man zur Definition oder zur Änderung sprachabhängiger +Begriffe Anweisungen wie \Macro{captionsngerman} so umdefinieren, dass +zusätzlich zu den bisherigen Begriffen auch die neuen oder geänderten +definiert werden. Erschwert wird dieses Vorhaben dadurch, dass beim Laden +eines Paketes wie \Package{german}\IndexPackage{german} oder +\Package{ngerman}\IndexPackage{ngerman} diese Anweisungen von den Paketen +erneut definiert werden. Bei den genannten Paketen geschieht dies leider in +einer Form, die alle zuvor gemachten Änderungen zunichte macht. Aus diesem +Grund ist es sinnvoll die Änderungen mit Hilfe von \Macro{AtBeginDocument} bis +\Macro{begin}\PParameter{document}, also bis nach dem Laden aller Pakete, zu +verzögern. Auch der Anwender muss entweder von \Macro{AtBeginDocument} +Gebrauch machen oder aber seine Änderungen nicht in die Dokumentpräambel, +sondern hinter \Macro{begin}\PParameter{document} einfügen. Das Paket +\Package{scrbase} bietet ihm für die Definition selbst einige zusätzliche +Anweisungen. + +\BeginIndex{Cmd}{providecaptionname}% +\BeginIndex{Cmd}{newcaptionname}% +\BeginIndex{Cmd}{renewcaptionname}% +\begin{Declaration} + \Macro{providecaptionname}% + \Parameter{Sprache}\Parameter{Begriff}\Parameter{Inhalt}\\ + \Macro{newcaptionname}% + \Parameter{Sprache}\Parameter{Begriff}\Parameter{Inhalt}\\ + \Macro{renewcaptionname}% + \Parameter{Sprache}\Parameter{Begriff}\Parameter{Inhalt} +\end{Declaration} +Mit Hilfe dieser drei Anweisungen ist es möglich, einem \PName{Begriff} in +Abhängigkeit der \PName{Sprache} einen \PName{Inhalt} zuzuweisen. Der +\PName{Begriff} ist dabei immer ein Makro. Die Arbeitsweise der drei +Anweisungen unterscheidet sich je nachdem, ob eine \PName{Sprache} und ein +\PName{Begriff} innerhalb dieser \PName{Sprache} zum Zeitpunkt des Aufrufs +bereits definiert ist. + +Ist eine \PName{Sprache} nicht definiert, so tut \Macro{providecaptionname} +nichts weiter, als dies in der \File{log}-Datei zu vermerken. Dabei wird für +jede Sprache nur einmal eine entsprechende Information in die \File{log}-Datei +geschrieben. Ist die Sprache definiert, enthält aber bisher keinen +entsprechenden \PName{Begriff}, so wird er mit dem angegebenen \PName{Inhalt} +definiert. Ist der \PName{Begriff} hingegen in der \PName{Sprache} bereits +definiert, so wird er nicht umdefiniert, sondern ein entsprechender Hinweis in +die \File{log}-Datei geschrieben. + +Die Anweisung \Macro{newcaptionname} verhält sich etwas anders. Ist bei ihr +die \PName{Sprache} nicht definiert, dann wird diese neu definiert, indem eine +entsprechende Anweisung, beispielsweise \Macro{captionsngerman} definiert +wird. Außerdem wird darüber auch in der \File{log}-Datei informiert. Ist die +\PName{Sprache} definiert, der \PName{Begriff} in dieser \PName{Sprache} aber +noch nicht vorhanden, so wird er mit dem gewünschten \PName{Inhalt} +definiert. Ist der \PName{Begriff} in der \PName{Sprache} bereits vorhanden, +so wird eine Fehlermeldung ausgegeben. + +Noch einmal anders verhält sich die Anweisung \Macro{renewcaptionname}. Ist +die \PName{Sprache} nicht definiert, so wird eine Fehlermeldung +ausgegeben. Ist die \PName{Sprache} definiert, der \PName{Begriff} in dieser +\PName{Sprache} jedoch nicht, so wird ebenfalls eine Fehlermeldung +ausgegeben. Ist der \PName{Begriff} in der \PName{Sprache} definiert, so wird +er auf den gewünschten \PName{Inhalt} umdefiniert. + +\KOMAScript{} selbst verwendet \Macro{providecaptionname} um die Begriffe aus +\autoref{sec:scrlttr2-experts.languages} zu definieren. + +\begin{Example} + Möchten Sie statt »Abbildung« in den Abbildungsunterschriften lieber »Abb.« + stehen haben, so erreichen Sie dies mit + \begin{lstcode} + \renewcaptionname{ngerman}{\figurename}{Abb.} + \end{lstcode} + Da mit \Macro{renewcaptionname} nur bereits vorhandene Begriffe in + vorhandenen Sprachen umdefiniert werden können, müssen Sie diese Anweisung + nach \Macro{begin}\PParameter{document} setzen oder mit Hilfe von + \Macro{AtBeginDocument} verzögern. Außerdem werden Sie eine Fehlermeldung + erhalten, wenn Sie kein Paket zur Sprachumschaltung auf \PValue{ngerman} + verwenden. +\end{Example} + +In \autoref{tab:scrbase.commonNames} ist ein Überblick über die üblicherweise +von Klassen und Sprachpaketen definierten Begriffe und deren Verwendung zu +finden. +\begin{desctable} + \caption[{Überblick über übliche sprachabhängige Begriffe}]% + {Überblick über sprachabhängige Begriffe in den üblichen + Sprachpaketen\label{tab:scrbase.commonNames}}\\ + \Endfirsthead + \caption[]{Überblick über übliche sprachabhängige Begriffe + (\emph{Fortsetzung})}\\ + \Endhead% + \standardfoot% + \entry{\Macro{abstractname}}{% + \IndexCmd{abstractname}% + Überschrift für die Zusammenfassung}% + \entry{\Macro{alsoname}}{% + \IndexCmd{alsoname}% + »Siehe auch« bei ergänzenden Verweisen im Stichwortverzeichnis}% + \entry{\Macro{appendixname}}{% + \IndexCmd{appendixname}% + »Anhang« in der Kapitelüberschrift eines Anhangs}% + \entry{\Macro{bibname}}{% + \IndexCmd{bibname}% + Überschrift für das Literaturverzeichnis}% + \entry{\Macro{ccname}}{% + \IndexCmd{ccname}% + Spitzmarke für den Verteiler in Briefen}% + \entry{\Macro{chaptername}}{% + \IndexCmd{chaptername}% + »Kapitel« in der Kapitelüberschrift}% + \entry{\Macro{contentsname}}{% + \IndexCmd{contentsname}% + Überschrift für das Inhaltsverzeichnis}% + \entry{\Macro{enclname}}{% + \IndexCmd{enclname}% + Spitzmarke für die Anlagen bei Briefen}% + \entry{\Macro{figurename}}{% + \IndexCmd{figurename}% + Spitzmarke in der Abbildungsunterschrift}% + \entry{\Macro{glossaryname}}{% + \IndexCmd{glossaryname}% + Überschrift für das Glossar}% + \entry{\Macro{headtoname}}{% + \IndexCmd{headtoname}% + »An« im Briefkopf}% + \entry{\Macro{indexname}}{% + \IndexCmd{indexname}% + Überschrift für das Stichwortverzeichnis}% + \entry{\Macro{listfigurename}}{% + \IndexCmd{listfigurename}% + Überschrift für das Abbildungsverzeichnis}% + \entry{\Macro{listtablename}}{% + \IndexCmd{listtablename}% + Überschrift für das Tabellenverzeichnis}% + \entry{\Macro{pagename}}{% + \IndexCmd{pagename}% + »Seite« in der Seitennummer von Briefen}% + \entry{\Macro{partname}}{% + \IndexCmd{partname}% + »Teil« in der Teileüberschrift}% + \entry{\Macro{prefacename}}{% + \IndexCmd{prefacename}% + Überschrift für das Vorwort}% + \entry{\Macro{proofname}}{% + \IndexCmd{proofname}% + Spitzmarke bei Beweisen}% + \entry{\Macro{refname}}{% + \IndexCmd{refname}% + Überschrift für das Quellenverzeichnis}% + \entry{\Macro{seename}}{% + \IndexCmd{seename}% + »Siehe« bei Verweisen im Stichwortverzeichnis}% + \entry{\Macro{tablename}}{% + \IndexCmd{tablename}% + Spitzmarke in der Tabellenunter- bzw. "~überschrift}% +\end{desctable} +% +\EndIndex{Cmd}{renewcaptionname}% +\EndIndex{Cmd}{newcaptionname}% +\EndIndex{Cmd}{providecaptionname}% + +\EndIndex{}{Sprachdefinition}% + + +\section{Identifikation von \KOMAScript} +\label{sec:scrbase.identify} + +Auch wenn \Package{scrbase} unabhängig von \KOMAScript{} auch für andere +Pakete und Klassen verwendet werden kann, so ist es dennoch ein +\KOMAScript-Paket. Als solches enthält es auch Anweisungen, die es als +\KOMAScript-Paket identifizieren. + + +\BeginIndex{Cmd}{KOMAScript}% +\begin{Declaration} + \Macro{KOMAScript} +\end{Declaration} +Diese Anweisung setzt schlicht die Wortmarke »\KOMAScript« in serifenloser +Schrift und mit leichter Sperrung des Versalteils. \Macro{\KOMAScript} wird +übrigens bei Bedarf von allen \KOMAScript-Klassen und "~Paketen definiert. Die +Definition erfolgt mit \Macro{DeclareRobustCommand}. +% +\EndIndex{Cmd}{KOMAScript} + + +\BeginIndex{Cmd}{KOMAScriptVersion}% +\begin{Declaration} + \Macro{KOMAScriptVersion} +\end{Declaration} +Bei \KOMAScript{} ist in dieser Anweisung die Hauptversion von \KOMAScript{} +in der Form »\PName{Datum} \PName{Version} \texttt{KOMA-Script}« +abgelegt. Diese Hauptversion ist für alle \KOMAScript-Klassen und alle +\KOMAScript-Pakete, die von den Klassen verwendet werden, gleich. Daher kann +sie auch nach dem Laden von \Package{scrbase} abgefragt werden. Diese +Anleitung wurde beispielsweise mit der \KOMAScript-Version +»\KOMAScriptVersion« erstellt. +% +\EndIndex{Cmd}{KOMAScriptVersion}% + + +\section{Erweiterungen des \LaTeX-Kerns} +\label{sec:scrbase:latexkernel} + +In einigen Fällen stellt der \LaTeX-Kern selbst Anweisungen zur Verfügung, +lässt aber ganz ähnliche Anweisungen, die ebenfalls häufiger benötigt werden +oder eigentlich nahe liegen, vermissen. Einige wenige solcher Anweisungen +für Klassen- und Paketautoren stellt \Package{scrbase} zur Verfügung. + +\BeginIndex{Cmd}{PackageInfoNoLine}% +\BeginIndex{Cmd}{ClassInfoNoLine}% +\begin{Declaration} + \Macro{ClassInfoNoLine}\Parameter{Klassenname}\Parameter{Information}\\ + \Macro{PackageInfoNoLine}\Parameter{Paketname}\Parameter{Information} +\end{Declaration} +Der \LaTeX-Kern bietet dem Klassen- und Paketautor zwar Anweisungen wie +\Macro{PackageInfo} und \Macro{ClassInfo}, um Informationen mit aktueller +Zeilennummer in die Log-Datei zu schreiben. Er bietet neben +\Macro{PackageWarning} und \Macro{ClassWarning}, die Warnungen mit aktueller +Zeilennummer ausgeben, auch Anweisungen wie \Macro{PackageWarningNoLine} und +\Macro{ClassWarningNoLine}, um Warnungen ohne Zeilennummer auszugeben. Die +nahe liegenden Anweisungen \Macro{ClassInfoNoLine} und +\Macro{PackageInfoNoLine}, um auch Informationen ohne Zeilennummer in die +Log-Datei zu schreiben, fehlen jedoch. Diese werden von \Package{scrbase} +bereit gestellt. +% +\EndIndex{Cmd}{ClassInfoNoLine}% +\EndIndex{Cmd}{PackageInfoNoLine} + +\BeginIndex{Cmd}{l@addto@macro}% +\begin{Declaration} + \Macro{l@addto@macro}\Parameter{Anweisung}\Parameter{Erweiterung} +\end{Declaration} +Der \LaTeX-Kern bietet mit \Macro{g@addto@macro} eine interne Anweisung, um +die Definition eines Makro \PName{Anweisung} global um den Code +\PName{Erweiterung} zu erweitern. Dies funktioniert in dieser Form nur für +Makros ohne Argumente. Dennoch könnte man diese Anweisung in einigen Fällen +auch in einer Form benötigen, die lokal zur aktuellen Gruppe arbeitet. Diese +wird mit \Macro{l@addto@macro} von \Package{scrbase} bereit gestellt. +% +\EndIndex{Cmd}{l@addto@macro} + +\EndIndex{Package}{scrbase}% + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% coding: iso-latin-1 +%%% TeX-master: "guide.tex" +%%% End: |