diff options
author | Karl Berry <karl@freefriends.org> | 2012-05-16 23:12:50 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-05-16 23:12:50 +0000 |
commit | 33a91552392adacad1480db2e7ea4e966c0f4533 (patch) | |
tree | 6e4a4f772fcce778b4726d75f2ae00a217ca41d1 /Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex | |
parent | 20572a9d0911336a8588b561872220d6aba8e208 (diff) |
koma-script (15may12)
git-svn-id: svn://tug.org/texlive/trunk@26455 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex | 1209 |
1 files changed, 1209 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex new file mode 100644 index 00000000000..ce472d81292 --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex @@ -0,0 +1,1209 @@ +% ====================================================================== +% scrbase.tex +% Copyright (c) Markus Kohm, 2002-2012 +% +% 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.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c 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-2012 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c 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 fuer Paket- und Klassenautoren +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\ProvidesFile{scrbase.tex}[2012/03/04 KOMA-Script package scrbase] +\translator{Markus Kohm} + +% Date of the translated German file: 2012/03/04 + +\chapter{Basic Functions at Package \Package{scrbase}} +\labelbase{scrbase} + +\BeginIndex{Package}{scrbase}% + +The package \Package{scrbase} provides basic features, that are designed and +implemented to be used by authors of packages and classes. Thereby it may not +only used for wrapper classes, that use a \KOMAScript{} class. Authors of +classes, that aren't related to anything else from \KOMAScript{}, may also +benefit from the functionality of \Package{scrbase}. + +\section{Loading the Package} +\label{sec:scrbase.loadit} + +Whereas users load packages using \Macro{usepackage}, authors of packages or +classes should use \Macro{RequirePackage}\IndexCmd{RequirePackage}. Authors of +wrapper packages may also use \Macro{RequirePackageWithOptions}. Command +\Macro{RequirePackage} has the same optional argument for package options like +\Macro{usepackage}. In opposite to this \Macro{RequirePackageWithOptions} +doesn't have an optional argument but passes all options given while loading +the wrapper package to the required package. See \cite{latex:clsguide} for +more information about these commands. + +The package \Package{scrbase} needs the functionality of package +\Package{keyval}\IndexPackage{keyval} internally. This may be provided by +package \Package{xkeyval} alternatively. Package \Package{scrbase} loads +\Package{keyval} as needed. + +The package \Package{keyval} provides definition of keys and assignment of +values to this keys. The options provided by \Package{scrbase} also use +\Package{keyval} syntax: \PName{key}\texttt{=}\PName{value}. + +\begin{Declaration} + \KOption{internalonly}\PName{value} +\end{Declaration} +\BeginIndex{Option}{internalonly~=\PName{value}}% +Package \Package{scrbase} provides some commands for conditional +execution. The primary names of those are build like +\Macro{scr@\PName{name}}. With this those are internal commands. \KOMAScript{} +really uses this internal commands internally. Authors of packages and classes +may use those internal commands too, but should not redefine them. Because +some of those commands may be useful for users too, they are also provided as +\Macro{\PName{name}} normally. But eventually other packages provide commands +with the same name but different syntax or different functionality. This would +result in an conflict. So \Package{scrbase} provides to suppress the +definition of the user commands, \Macro{\PName{name}}, only. Using option +\Option{internalonly} without \PName{value} will define only the internal +commands and suppress definition of all the user commands for conditional +execution. Alternatively, the user may give all the commands, that shouldn't +be defined as \PName{value}, but replaces ``\Macro{}'' by ``\texttt{/}''. + +Authors of packages and classes normally should not use this option. Users may +use it with or without \PName{value} either as a global option with +\Macro{documentclass} or using \Macro{PassOptionsToPackage}. +\begin{Example} + The user doesn't want \Package{scrbase} to define commands \Macro{ifVTeX} + and \Macro{ifundefinedorrelax}. Because of this, user uses: +\begin{lstcode} + \documentclass% + [internalonly=/ifVTeX/ifundefinedorrelax]% + {foo} +\end{lstcode} + to load the class. Class name \Class{foo} has been used as an placeholder + for any class in this example. The meanings of commands \Macro{ifVTeX} and + \Macro{ifundefinedorrelax} and many more commands for conditional execution + may be found in \autoref{sec:scrbase.if}. +\end{Example} +% +\EndIndex{Option}{internalonly~=\PName{value}}% + + +\section{Keys as Attributes of Families and their Members} +\label{sec:scrbase.keyvalue} + +As already mentioned in \autoref{sec:scrbase.loadit}, \Package{scrbase} uses +package \Package{keyval} for keys and values of keys. Nevertheless +\Package{scrbase} extends the functionality of \Package{keyval}. Whereas only +one family owns all keys of \Package{keyval}, \Package{scrbase} knows also +family members. Now, a key may be owned by a family or by one or more family +members. Additionally a value may be assigned to the key of a family member, +of a family or of all family members. + +\begin{Declaration} + \Macro{DefineFamily}\Parameter{family}\\ + \Macro{DefineFamilyMember}\OParameter{family member}\Parameter{family} +\end{Declaration} +\BeginIndex{Cmd}{DefineFamily}% +\BeginIndex{Cmd}{DefineFamilyMember}% +\Package{scrbase} needs to know the members of a family for different +reasons. So it's necessary first to define a new family using +\Macro{DefineFamily}, that produces also an empty member list. If the family +has already been defined nothing would happen. Nothing means also, that an +already existing member list would not be overwritten. + +A new member may be added to the family using \Macro{DefineFamilyMember}. If +the family doesn't exist, this would result in an error message. If the member +already exists, nothing happens. If the member is omitted, the member won't +stay empty, but ``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' will +be assumed. While loading a class or package \Macro{@currname} and +\Macro{@currext} together represent the file name of the class or package. + +Theoretically is would be possible, to define a member without a name using an +empty optional argument \PName{family member}. But this would be same like the +family itself. It is recommended to use only letters and digits at the +\PName{family} an start the \PName{family member} with another char like a +period. Otherwise it could happen, that members of one family are same like +members of another family. + +\Package{scrbase} itself defines family ``\PValue{KOMA}'' and adds member +``\PValue{.scrbase.sty}'' to is. Generally family ``\PValue{KOMA}'' is +reserved to \KOMAScript{}. For your own packages it is recommended to use the +name of the bundle as \PName{family} and the name of the package as +\PName{family member} of that \PName{family}. +% +\begin{Example} + Assumed you're writing a bundle ``master butcher''. Within that bundle you + have packages \File{salami.sty}, \File{liversausage.sty}, and + \File{kielbasa.sty}. Therefor you decide to use family name + ``\PValue{butcher}'' and add the lines +\begin{lstcode} + \DefineFamily{butcher} + \DefineFamilyMember{butcher} +\end{lstcode} + to each of the package files. While loading the three packages this will + all the members ``\PValue{.salami.sty}'', ``\PValue{.liversausage.sty}'', + and ``\PValue{.kielbasa.sty}'' to the family ``\PValue{butcher}''. After + loading all three packages, all three member will be defined. +\end{Example} +% +\EndIndex{Cmd}{DefineFamilyMember}% +\EndIndex{Cmd}{DefineFamily}% + + +\begin{Declaration} + \Macro{DefineFamilyKey}\OParameter{family member}\Parameter{family}% + \Parameter{key}\OParameter{default}\\ + \hphantom{\Macro{DefineFamilyKey}}\Parameter{action} +\end{Declaration} +\BeginIndex{Cmd}{DefineFamilyKey}% +This command defines a \PName{key}. If a \PName{family member} is given, the +\PName{key} will become an attribute of that member of the also given +\PName{family}. If no \PName{family member} is given, the member +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' will be assumed. If +later a value will be assigned to the \PName{key}, the \PName{action} will be +executed and the value will be an argument of this. So inside of +\PName{action} ``\lstinline{#1}'' would be that value. If the value will be +omitted, the \PName{default} will be used instead. If there's no +\PName{default}, the \PName{key} can be used only with value. +\begin{Explain} + \phantomsection\label{explain:scrbase.macro.DefineFamilyKey}% + At least +\begin{lstcode}[escapeinside=`'] + \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} + [`\PName{default}']{`\PName{action}'} +\end{lstcode} + will result in a call of +\begin{lstcode}[moretexcs={define@key},escapeinside=`'] + \define@key{`\PName{family\,member}'}{`\PName{key}'} + [`\PName{default}']{`\PName{action}'} +\end{lstcode} + with \Macro{define@key} is provided by package + \Package{keyval}\IndexPackage{keyval} (see \cite{package:keyval}). +\end{Explain} +\begin{Example} + Assumed, each of the three packages from the previous example should get a + key \PValue{coldcuts}. If this is used, a switch should be set at each of + the packages. For package \Package{salami} this may be, e.\,g., +\begin{lstcode} + \newif\if@Salami@Aufschnitt + \DefineFamilyKey{butcher}% + {coldcut}[true]{% + \expandafter\let\expandafter\if@salami@coldcut + \csname if#1\endcsname + } +\end{lstcode} + Available values for the key are \PValue{true} or \PValue{false} in this + case. There's no test on inappropriate values in this example. If the key + will be used later, this has to be done with one of the allowed values or + without assignment. In the second case the default \PName{true} will be + used. + + The definitions in the other packages are similar. Only ``\texttt{salami}'' + has to be replaced by the corresponding names. +\end{Example} +% +\EndIndex{Cmd}{DefineFamilyKey}% + + +\begin{Declaration} + \Macro{FamilyProcessOptions}\OParameter{family member}\Parameter{family} +\end{Declaration} +\BeginIndex{Cmd}{FamilyProcessOptions}% +Generally the extension of keys of families to keys of families and family +members was mentioned to use keys or key-value settings as class or package +options. This command therefor is an extension of \Macro{ProcessOption*} from +\LaTeX{} kernel (see \cite{latex:clsguide}. Thereby the command processes not +only options that has been declared using \Macro{DeclareOption}. It processes +even all keys of the given family member. If the optional argument +\PName{family member} is omitted, family member +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' will be used. + +Somehow special are keys, that are not attached to a family member, but to a +family. These are keys with an empty family member. Such keys will be set also +and before the keys of the family members. +\begin{Example} + If a package in the previous example would be extended by the line +\begin{lstcode} + \FamilyProcessOptions{butcher} +\end{lstcode} + then the user may select the option \Option{coldcut} while loading the + package. If the option will be used globally, this means at the optional + argument of \Macro{documentclass}, then the option would be passed + automatically to all three packages, if all three packages will be loaded + later. +\end{Example} +Please note\textnote{Attention!} that packages process global options always +before local options, that has been assigned locally to the package. In +opposite to unknown options while processing of global options, that will only +result in an information in the \File{log}-file, unknown options assigned to +the package result in error messages. + +\Macro{FamilyProcessOptions} may be interpreted either as an extension of +\Macro{ProcessOption*} or as an extension of the \PName{key=value} mechanism +of \Package{keyval}. Finally \PName{key=value} pairs become options with help +of \Macro{FamilyProcessOptions}.% +% +\EndIndex{Cmd}{FamilyProcessOptions}% + + +\begin{Declaration} + \Macro{FamilyExecuteOptions}\OParameter{family member}\Parameter{family}% + \Parameter{options list} +\end{Declaration} +\BeginIndex{Cmd}{FamilyExecuteOptions}% +This command is an extension of \Macro{ExecuteOptions} from the \LaTeX{} +kernel (see \cite{latex:clsguide}). Thereby the command processes not only +options, that has been defined using \Macro{DeclareOption}. Also all keys of +the given family member will be processed. If the optional argument +\Macro{family member} is omitted, then +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. + +Somehow special are keys, that are not attached to a family member, but to a +family. These are keys with an empty family member. Such keys will be set also +and before the keys of the family members. +\begin{Example} + Assumed, option \Option{coldcut} should be set by default already in the + previous example. In this case only line +\begin{lstcode} + \FamilyExecuteOptions{butcher}{coldcut} +\end{lstcode} + has to be added. +\end{Example} +% +\EndIndex{Cmd}{FamilyExecuteOptions}% + + +\begin{Declaration} + \Macro{FamilyOptions}\Parameter{family}\Parameter{options list}\\ + \Macro{Family@Options}\Parameter{family}\Parameter{options list}% + \Parameter{error action} +\end{Declaration} +\BeginIndex{Cmd}{FamilyOptions}% +\BeginIndex{Cmd}{Family@Options}% +Thereby \PName{options list} is like: +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \PName{key}\texttt{=}\PName{value}\texttt{,}% + \PName{key}\texttt{=}\PName{value}\dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +whereby the value assignment may be omitted for \PName{key}s, that have a +defined default. + +In opposite to average options, that has been defined using +\Macro{DeclareOption}, the \PName{key}s may also be set after loading a class +or package. For this the user uses \Macro{FamilyOptions}. Thereby the +\PName{key}s of all members of the given family will be set. If a \PName{key} +also exists as an family attribute, then the family key will be set +first. After this the member keys will follow in the order, the members has +been defined. If a given \PName{key} does exist neither in the family nor in +any member of the family, then \Macro{FamilyOptions} will result in an +error. In opposite to this with \Macro{Family@Options} the user may declare +his own \PName{error action}. But this internal command is reserved for +authors of classes and packages. +\begin{Example} + You extend your butcher project by a package \Package{sausagesalad}. If this + package has been loaded, all sausage package should generate cold cut: +\begin{lstcode} + \ProvidesPackage{sausagesalad}% + [2008/05/06 nonsense package] + \DefineFamily{butcher} + \DefineFamilyMember{butcher} + \FamilyProcessOptions{butcher}\relax + \FamilyOptions{butcher}{coldcut} +\end{lstcode} + If currently non of the sausage packages has been loaded, then an error + message would result because of undefined option ``\Option{coldcut}''. Dies + may be avoided changing the last line of the previous code into: +\begin{lstcode}[moretexcs={Family@Options}] + \Family@Options{butcher}{coldcut}{} +\end{lstcode} + Nevertheless, sausage packages, that will be loaded after + \Package{sausagesalad}, won't produce cold cut. This may be changed + additionally, by changing the last line again: +\begin{lstcode}[moretexcs={Family@Options}] + \AtBeginDocument{% + \Family@Options{butcher}{coldcut}{% + \PackageWarning{sausagesalad}{% + sausage salad needs at least + one sausage package}% + }% + }% +\end{lstcode} + This will also throw a warning message, if non of the sausage packages will + be loaded. +\end{Example} +% +\EndIndex{Cmd}{Family@Options}% +\EndIndex{Cmd}{FamilyOptions}% + + +\begin{Declaration} + \Macro{FamilyOption}\Parameter{family}% + \Parameter{option}\Parameter{values list}\\ + \Macro{Family@Option}\Parameter{family}% + \Parameter{option}\Parameter{values list}% + \Parameter{error action} +\end{Declaration} +\BeginIndex{Cmd}{FamilyOption}% +\BeginIndex{Cmd}{Family@Option}% +Beside options that have concurrently excluding values, there may be options, +that have several values at the same time. Using \Macro{FamilyOptions} for +that kind of options would result in using the same option several times with +different value assignments. Instead of this, \Macro{FamilyOption} may be used +to assign a whole \PName{values list} to the same \PName{option}. The +\PName{values list} is a comma separated list of values: +\begin{flushleft}\begin{tabular}{l} + \PName{value}\texttt{,}\PName{value}\dots +\end{tabular}\end{flushleft} +By the way please note, that usage of a comma inside a value may be done only, +if the value is put into braces. The general functionality of these commands +is the same like that of the previous commands \Macro{FamilyOptions} and +\Macro{Family@Options}. +\begin{Example} + Package \Package{sausagesalad} should have one mire option, to add + additional ingredients. Each of the ingredients will set a switch like done + before for the cold cut. +\begin{lstcode} + \newif\if@saladwith@onions + \newif\if@saladwith@gherkins + \newif\if@saladwith@chillies + \DefineFamilyKey{butcher}{ingredient}{% + \csname @saladwith@#1true\endcsname + } +\end{lstcode} + Here the three ingredients ``onions'', ``gherkins'', and ``chillies'' has + been defined. An error message for not defined ingredients doesn't exist. + + For a salad with onions and gherkins the user may use +\begin{lstcode} + \FamilyOptions{butcher}{% + ingredient=onions,ingredient=gherkins} +\end{lstcode} + or shorter +\begin{lstcode} + \FamilyOption{butcher} + {ingredient}{onions,gherkins} +\end{lstcode} +\end{Example} +% +\EndIndex{Cmd}{Family@Option}% +\EndIndex{Cmd}{FamilyOption}% + + +\begin{Declaration} + \Macro{FamilyBoolKey}\OParameter{family member}\Parameter{family}% + \Parameter{key}\Parameter{switch name}\\ + \Macro{FamilySetBool}\Parameter{family}% + \Parameter{key}\Parameter{switch name}\Parameter{value} +\end{Declaration} +\BeginIndex{Cmd}{FamilyBoolKey}% +\BeginIndex{Cmd}{FamilySetBool}% +In the previous examples boolean switches often have been used. In the example +with option \Option{coldcut} is was necessary, that the user assigns either +value \PValue{true} or value \PValue{false}. No error message existed on wrong +value assignment. Because of such boolean switches are an often needed +feature, \Package{scrbase} provides \Macro{FamilyBoolKey} for definition of +such options. Thereby the arguments \PName{family member}, \PName{family}, +and \PName{key} are same like used by \Macro{DefineFamilyKey} (see +\autopageref{desc:scrbase.cmd.DefineFamilyKey}). Argument \PName{switch name} +is the name of the switch without the prefix \Macro{if}. If a switch with this +name doesn't exist already, \Macro{FamilyBoolKey} will define it and +initialize it to \PName{false}. Internally \Macro{FamilyBooKey} uses +\Macro{FamilySetBool} as \PName{action} of \Macro{DefineFamilyKey}. The +\PName{default} for those options is always \PValue{true}. + +\Macro{FamilySetBool} on the other side understands \PName{value} \PValue{on} +and \PValue{yes} beside \PName{true} for switching on and \PName{off} and +\PName{no} beside \PName{false} for switching off. Unknown values will result +in a call of \Macro{FamilyUnknownKeyValue} with the arguments \PName{family}, +\PName{key}, and \PName{value}. This will normally result in an error message +about unknown value assignment (see also +\autopageref{desc:scrbase.cmd.FamilyUnkownKeyValue}). +\begin{Example} + The key \Option{coldcut} should be declared somehow more robust. Additionally + all sausage packages should use the same key. So either all or none of them + will produce cold cut. +\begin{lstcode} + \FamilyBoolKey{butcher}{coldcut}% + {@coldcut} +\end{lstcode} + A test, whether or not to produce cold cut, may be: +\begin{lstcode} + \if@coldcut + ... + \else + ... + \fi +\end{lstcode} + This would be the same in each of the three sausage packages. With this the + attribute ``coldcut'' may be defined as a family option: +\begin{lstcode}[moretexcs={define@key}] + \@ifundefined{if@coldcut}{% + \expandafter\newif\csname if@coldcut\endcsname + }{}% + \define@key{butcher}{coldcut}[true]{% + \FamilySetBool{butcher}{coldcut}% + {@coldcut}% + {#1}% + } +\end{lstcode} + or shorter: +\begin{lstcode} + \FamilyBoolKey[]{butcher}{coldcut}% + {@coldcut} +\end{lstcode} + using the additional information at + \autopageref{explain:scrbase.macro.DefineFamilyKey}, that's not only valid + for \Macro{DefineFamilyKey} but for \Macro{FamilyBoolKey} too. +\end{Example} +% +\EndIndex{Cmd}{FamilySetBool}% +\EndIndex{Cmd}{FamilyBoolKey} + + +\begin{Declaration} + \Macro{FamilyNumericalKey}\OParameter{family member}\Parameter{family}% + \Parameter{key}\\ + \hphantom{\XMacro{FamilyNumericalKey}}% + \OParameter{default}\Parameter{command}% + \Parameter{values list}\\ + \Macro{FamilySetNumerical}\Parameter{family}\Parameter{key}\\ + \hphantom{\XMacro{FamilySetNumerical}}% + \Parameter{command}\Parameter{values list}% + \Parameter{value} +\end{Declaration} +\BeginIndex{Cmd}{FamilyNumericalKey}% +\BeginIndex{Cmd}{FamilySetNumerical}% +In opposite to switches that may be either true or false, also key exists, +that accept several values. For example an alignment may not only be left or +not left, but, e.\,g., left, centered, or right. Internally such +differentiations are often made using \Macro{ifcase}. This \TeX{} command +expects a numerical value. Because of this the command to define a macro by +a \PName{key} has been named \Macro{FamilyNumericalKey} in +\Package{scrbase}. The \PName{values list} thereby has the form: +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \Parameter{value}\Parameter{definition}\texttt{,}% + \Parameter{value}\Parameter{definition}\texttt{,}% + \dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +So the \PName{values list} does not only define the supported values to the +\PName{key}. For each of the \PName{value}s it also gives the +\PName{definition} of macro \Macro{\PName{command}}. Usually +\PName{definition} is just a numerical value. Nevertheless other content is +possible and allowed. Currently the only limitation is, that +\PName{definition} has to be fully expandable and will be expanded while the +assignment. +\begin{Example} + The sausage may be cut different. For example the cold cut may stay uncut or + will by cut roughly or may be cut thinly. This information should be stored + in command \Macro{cuthow}. +\begin{lstcode} + \FamilyNumericalKey{butcher}% + {saladcut}{cuthow}{% + {none}{none},{no}{none},{not}{none}% + {rough}{rough},% + {thin}{thin}% + } +\end{lstcode} + Not cutting anything may be selected either by +\begin{lstcode} + \FamilyOptions{butcher}{saladcut=none} +\end{lstcode} + or +\begin{lstcode} + \FamilyOptions{butcher}{saladcut=no} +\end{lstcode} + or +\begin{lstcode} + \FamilyOptions{butcher}{saladcut=not} +\end{lstcode} + In all three cases \Macro{cuthow} would be defined with content + \PValue{none}. It may be very useful to provide several values for the same + result like shown in this example. + + Now, it's most likely, that the kind of cutting will not be printed, but + should be evaluated later. In this case a textual definition wouldn't be + useful. If the key is defined like this: +\begin{lstcode} + \FamilyNumericalKey{butcher}% + {saladcut}{cuthow}{% + {none}{0},{no}{0},{not}{0}% + {rough}{1},% + {thin}{2}% + } +\end{lstcode} + then a condition like this: +\begin{lstcode} + \ifcase\cuthow + % no cut + \or + % rough cut + \else + % thin cut + \fi +\end{lstcode} + may be used. +\end{Example} +Internally \Macro{FamilyNumericalKey} uses \Macro{FamilySetNumerical} as +\PName{action} of \Macro{DefineFamilyKey}. If a unknown value is assigned to +such a key, \Macro{FamilySetNumerical} will call \Macro{FamilyUnkownKeyValue} +with the arguments \PName{family}, \PName{key} and \PName{value}. This will +normally result in an error message about assigning an unknown value. +% +\EndIndex{Cmd}{FamilySetNumerical}% +\EndIndex{Cmd}{FamilyNumericalKey}% + + +\begin{Declaration} + \Macro{FamilyStringKey}\OParameter{family member}\Parameter{family}% + \Parameter{key}\\ + \hphantom{\XMacro{FamilyStringKey}}% + \OParameter{default}\Parameter{command} +\end{Declaration} +\BeginIndex{Cmd}{FamilyStringKey}% +This defines\ChangedAt{v3.08}{\Package{scrbase}} a \PName{key}, that accepts +every value. The value will be stored into the given \Macro{command}. If their +is no optional argument for the \PName{default}, \Macro{FamilyStringKey} is +the same like +\begin{quote} +\Macro{DefineFamilyKey}\OParameter{family member}\Parameter{family}% +\Parameter{key}\\ +\hphantom{\Macro{DefineFamilyKey}}% +\PParameter{\Macro{def}\PName{command}\string{\#1\string}}. +\end{quote} +If an optional argument \PName{default} has been used, \Macro{FamilyStringKey} +is the same like +\begin{quote} +\Macro{DefineFamilyKey}\OParameter{family member}\Parameter{family}% +\Parameter{key}\\ +\hphantom{\Macro{DefineFamilyKey}}% +\OParameter{default}% +\PParameter{\Macro{def}\PName{command}\string{\#1\string}}. +\end{quote} +If \PName{command} hasn't been defined already, an empty macro will be +defined. +\begin{Example} + By default an amount of 250\Unit{g} sausage salad should be produced. The + amount should be configurable by an option. The wanted amount will be stored + in the macro \Macro{saladweight}. The option should be named + \PValue{saladweight} too: +\begin{lstcode} + \newcommand*{\saladweight}{250g} + \FamilyStringKey{butcher}% + {saladweight}[250g]{\saladweight} +\end{lstcode} + To switch back to the default weight after changing it, the user may simply + use the option without weight: +\begin{lstcode} + \FamilyOptions{butcher}{saladweight} +\end{lstcode} + That may be done, because the default weight has been set as default at the + definition of the option above. +\end{Example} +In this case there are no unknown values, because all values are simply used +for a macro definition. Nevertheless, you should note, that paragraph breaks +at the value assignment to the key are not allowed. +% +\EndIndex{Cmd}{FamilyStringKey}% + + +\begin{Declaration} + \Macro{FamilyUnkownKeyValue}\Parameter{family}\Parameter{key}% + \Parameter{value}\Parameter{values list}\\ + \Macro{FamilyElseValues} +\end{Declaration} +\BeginIndex{Cmd}{FamilyUnkownKeyValue}% +\BeginIndex{Cmd}{FamilyElseValues}% +The command \Macro{FamilyUnknownKeyValue} throws and error message about +unknown values assigned to a known key. The \PName{values list} is a comma +separated list of allowed values in the form: +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + `\PName{value}'\texttt{,} `\PName{value}' \dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +Additional allowed values may be set by \Macro{FamilyElseValues} in +the form: +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \texttt{,} `\PName{value}'\texttt{,} `\PName{value}' \dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +These will also be shown in the error message. \Macro{FamilySetBool} as well +as \Macro{FamilySetNumerical} will reset \Macro{FamilyElseValue} to an empty +definition automatically\,---\,independent of whether or not a error has been +thrown. +\begin{Example} + Now, for the cold cut the choices should be cut or no cut and in case of cut + rough or thin. Rough should be the default for cutting. +\begin{lstcode} + \@ifundefined{if@thincut}{% + \expandafter + \newif\csname if@thincut\endcsname}{}% + \@ifundefined{if@coldcut}{% + \expandafter + \newif\csname if@coldcut\endcsname}{} + \DefineFamilyKey{butcher}% + {coldcut}[true]{% + \ifstr{#1}{thin}{% + \@coldcuttrue + \@thincuttrue + }{% + \@thincutfalse + \def\FamilyElseValue{, `thin'}% + \FamilySetBool{butcher}{coldcut}% + {@coldcut}% + {#1}% + }% + }% +\end{lstcode} + Command \Macro{ifstr} used at the example code above will be described at + \autopageref{desc:scrbase.cmd.ifstr} in \autoref{sec:scrbase.if}. +\end{Example} +% +\EndIndex{Cmd}{FamilyElseValues}% +\EndIndex{Cmd}{FamilyUnkownKeyValue}% + + +\section{Conditional Execution} +\label{sec:scrbase.if} + +The package \Package{scrbase} provides several commands for conditional +execution. Thereby not the \TeX{} syntax of conditionals, e.\,g., +% Umbruchkorrektur +\begin{lstcode}[belowskip=\dp\strutbox] + \iftrue + ... + \else + ... + \fi +\end{lstcode} +but the \LaTeX{} syntax also known from \LaTeX{} commands like +\Macro{IfFileExists}, \Macro{@ifundefined}, \Macro{@ifpackageloaded}, and many +others will be used. Nevertheless, some package authors prefer to use the +\TeX{} syntax even for users at the \LaTeX{} interface level. In fact the +conditionals of \Package{scrbase} are very basic conditionals, this could +result in conditionals with the same name but different syntax and though in +naming conflicts. Because of this \Package{scrbase} firstly defines these +conditionals as internal commands with prefix \Macro{scr@}. Additional user +commands without this prefix are additionally defined. But the definition of +the user commands may be suppressed with option \Option{internalonly} (see +\autoref{sec:scrbase.loadit}, \autopageref{desc:scrbase.option.internalonly}). + +Authors of packages and classes should use the internal commands like +\KOMAScript{} itself does. Nevertheless, for completeness the user commands +are described additionally. + + +\begin{Declaration} + \Macro{scr@ifundefinedorrelax}% + \Parameter{name}\Parameter{then instructions}\Parameter{else instructions}\\ + \Macro{ifundefinedorrelax}% + \Parameter{name}\Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{scr@ifundefinedorrelax}% +\BeginIndex{Cmd}{ifundefinedorrelax}% +This command has almost the same functionality as \Macro{@ifundefined} from +the \LaTeX{} kernel (see \cite{latex:source2e}). So the \PName{then + instructions} will be executed, if \PName{name} is the name of a command, +that is currently either not defined or \Macro{relax}. Otherwise the +\PName{else instructions} will be executed. In opposite to +\Macro{@ifundefined} \Macro{\PName{name}} won't be defined to be \Macro{relax} +in the case it wasn't defined before. Using \eTeX{} this case won't at least +consume any hash memory.% +% +\EndIndex{Cmd}{ifundefinedorrelax}% +\EndIndex{Cmd}{scr@ifundefinedorrelax}% + + +\begin{Declaration} + \Macro{scr@ifpdftex}% + \Parameter{then instructions}\Parameter{else instructions}\\ + \Macro{ifpdftex}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{scr@ifpdftex}% +\BeginIndex{Cmd}{ifpdftex}% +If pdf\TeX{} has been used, the \PName{then instructions} will be executed, +otherwise the \PName{else instructions}. Whether or not a PDF-file will be +out, doesn't matter. Nevertheless, this pdf\TeX{} test seems so make sense +seldom only. Generally it's recommended to test for the wanted commands +instead (see previous \Macro{scr@ifundefinedorrelax} and +\Macro{ifundefinedorrelax}). +% +\EndIndex{Cmd}{ifpdftex}% +\EndIndex{Cmd}{scr@ifpdftex}% + + +\begin{Declaration} + \Macro{scr@ifVTeX}% + \Parameter{then instructions}\Parameter{else instructions}\\ + \Macro{ifVTeX}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{scr@ifVTeX}% +\BeginIndex{Cmd}{ifVTeX}% +If V\TeX{} has been used, the \PName{then instructions} will be executed, +otherwise the \PName{else instructions}. This test seems so make sense +seldom only. Generally it's recommended to test for the wanted commands instead +(see previous \Macro{scr@ifundefinedorrelax} and \Macro{ifundefinedorrelax}). +% +\EndIndex{Cmd}{ifVTeX}% +\EndIndex{Cmd}{scr@ifVTeX}% + + +\begin{Declaration} + \Macro{scr@ifpdfoutput}% + \Parameter{then instructions}\Parameter{else instructions}\\ + \Macro{ifpdfoutput}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{scr@ifpdfoutput}% +\BeginIndex{Cmd}{ifpdfoutput}% +While PDF-file generation the \PName{then instructions} will be executed, +otherwise the \PName{else instructions}. Whether, e.\,g., pdf\TeX{} or V\TeX{} +is used to generate the PDF-file doesn't matter. +% +\EndIndex{Cmd}{ifpdfoutput}% +\EndIndex{Cmd}{scr@ifpdfoutput}% + + +\begin{Declaration} + \Macro{scr@ifpsoutput}% + \Parameter{then instructions}\Parameter{else instructions}\\ + \Macro{ifpsoutput}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{scr@ifpsoutput}% +\BeginIndex{Cmd}{ifpsoutput}% +While PostScript-file generation the \PName{then instructions} will be executed, +otherwise the \PName{else instructions}. V\TeX{} provides direct PostScript +generation, that will be recognized here. If V\TeX{} is not used but a switch +\Macro{if@dvips} has been defined, the decision depends on that +switch. \KOMAScript{}, e.\,g., provides \Macro{if@dvips} in +\Package{typearea}. +% +\EndIndex{Cmd}{ifpsoutput}% +\EndIndex{Cmd}{scr@ifpsoutput}% + + +\begin{Declaration} + \Macro{scr@ifdvioutput}% + \Parameter{then instructions}\Parameter{else instructions}\\ + \Macro{ifdvioutput}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{scr@ifdvioutput}% +\BeginIndex{Cmd}{ifdvioutput}% +While DVI-file generation the \PName{then instructions} will be executed, +otherwise the \PName{else instructions}. If neither a direct PDF-file +generation nor a direct PostScript-file generation has been detected, DVI-file +generation is assumed. +% +\EndIndex{Cmd}{ifdvioutput}% +\EndIndex{Cmd}{scr@ifdvioutput}% + + +\begin{Declaration} + \Macro{ifnotundefined}\Parameter{name}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifnotundefined}% +\eTeX{} will be used to test, whether or not a command with the given +\PName{name} has already been defined. The \PName{then instructions} will be +executed, if the command is defined, the \PName{else instructions} +otherwise. There's no corresponding internal command for this. +% +\EndIndex{Cmd}{ifnotundefined}% + + +\begin{Declaration} + \Macro{ifstr}\Parameter{string}\Parameter{string}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifstr}% +Both \PName{string} arguments will be expanded and afterward compared. If the +expansions are same, the \PName{then instructions} will be +executed, otherwise the \PName{else instructions}. There's no corresponding +internal command for this. +% +\EndIndex{Cmd}{ifstr}% + + +\begin{Declaration} + \Macro{ifnumber}\Parameter{string}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifnumber}% +Note, that this does not compare numbers. The \PName{then instructions} will +be executed, if the expansion of \PName{string} consists of digits +only. Otherwise the \PName{else instructions} will be used. There's no +corresponding internal command for this. +% +\EndIndex{Cmd}{ifnumber}% + + +\begin{Declaration} + \Macro{ifdimen}\Parameter{string}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifdimen}% +Note, that this does not compare dimensions. The \PName{then instructions} will +be executed, if the expansion of \PName{string} consists of digits and a valid +unit of length. Otherwise the \PName{else instructions} will be used. There's no +corresponding internal command for this. +% +\EndIndex{Cmd}{ifdimen}% + + +\begin{Declaration} + \Macro{if@atdocument}\ \PName{the instructions} + \Macro{else}\ \PName{else instructions} \Macro{fi} +\end{Declaration} +\BeginIndex{Cmd}{if@atdocument}% +This command exists intentionally as internal command only. In the document +preamble \Macro{if@atdocument} is same like \Macro{iffalse}. After +\Macro{begin}\PParameter{document} it's same like \Macro{iftrue}. Authors of +classes and packages may use this, if a command should work somehow different +depending in whether it has been used in the preamble or inside the documents +body. Please note\textnote{Attention!}, that this is a condition in \TeX{} +syntax not in \LaTeX{} syntax! +% +\EndIndex{Cmd}{if@atdocument}% + + +\section{Definition of Language-Dependent Terms} +\label{sec:scrbase.languageSupport} +\BeginIndex{}{language>definition} +\index{language>dependent terms|see{language definition}} +\index{terms>language-dependent|see{language definition}} + +Normally one has to change or define language-dependent terms like +\Macro{captionsenglish} in such a way that in addition to the available terms +the new or redefined terms are defined. This is made more difficult by the +fact that some packages like \Package{german}\IndexPackage{german} or +\Package{ngerman}\IndexPackage{ngerman} redefine those settings when the +packages are loaded. This definitions unfortunately occurs in such a manner as +to destroy all previous private settings. That is also the reason why it makes +sense to delay own changes with \Macro{AtBeginDocument} until +\Macro{begin}\PParameter{document}, that is, after package loading is +completed. The user can also use \Macro{AtBeginDocument}, or redefine the +language-dependent terms after \Macro{begin}\PParameter{document}, that is, +not put them in the preamble at all. The package \Package{scrbase} +provides some additional commands for defining language-dependent terms. + + +\begin{Declaration} + \Macro{providecaptionname}% + \Parameter{language}\Parameter{term}\Parameter{definition}\\ + \Macro{newcaptionname}% + \Parameter{language}\Parameter{term}\Parameter{definition}\\ + \Macro{renewcaptionname}% + \Parameter{language}\Parameter{term}\Parameter{definition} +\end{Declaration} +\BeginIndex{Cmd}{providecaptionname}% +\BeginIndex{Cmd}{newcaptionname}% +\BeginIndex{Cmd}{renewcaptionname}% +Using one of these commands, the user can assign a \PName{definition} for a +particular \PName{language} to a \PName{term}. The \PName{term} is always a +macro. The commands differ dependent on whether a given \PName{language} or a +\PName{term} within a given \PName{language} are already defined or not at the +time the command is called. + +If \PName{language} is not defined, then \Macro{providecaptionname} does +nothing other than writes a message in the log file. This happens only once +for each language. If \PName{language} is defined but \PName{term} is not yet +defined for it, then it will be defined using \PName{definition}. The +\PName{term} will not be redefined if the \PName{language} already has such a +definition; instead, an appropriate message is written to the log file. + +The command \Macro{newcaptionname} has a slightly different behaviour. If the +\PName{language} is not yet defined, then a new language command will be +created and a message written to the log file. For \PName{language} +\PValue{USenglish}, e.\,g.\, this would be the language command +\Macro{captionsUSenglish}. If \PName{term} is not yet defined in +\PName{language}, then it will be defined using \PName{definition}. If +\PName{term} already exists in \PName{language}, then this results in an error +message. + +The command \Macro{renewcaptionname} again behaves differently. It requires an +existing definition of \PName{term} in \PName{language}. If neither +\PName{language} nor \PName{term} exist or \PName{term} is unknown in a +defined language then a error message will be given. Otherwise, the +\PName{term} for \PName{language} will be redefined according to +\PName{definition}. + +\KOMAScript{} itself employs \Macro{providecaptionname} in order to define the +commands in \autoref{sec:scrlttr2-experts.languages}. + +\begin{Example} + If you prefer ``fig.'' instead of ``figure'', you may achieve this using: +\begin{lstcode} + \renewcaptionname{USenglish}{\figurename}{fig.} +\end{lstcode} +\end{Example} + +Since\textnote{Attention!} only existing terms in available languages can be +redefined using \Macro{renewcaptionname}, you have to put the command after +\Macro{begin}\PParameter{document} or delay the command by using +\Macro{AtBeginDocument}. Furthermore, you will get an error message if there +is no package used that switches language selection to, e.\,g., +\PName{USenglish} in the example above. + +Language dependent terms usually defined by classes and language +packages are listed and described in \autoref{tab:scrbase.commonNames}. + +\begin{desclist} + \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% + \desccaption[{% + Overview of usual language dependent terms% + }]{% + Overview of language dependent terms of usual language packages% + \label{tab:scrbase.commonNames}% + }{% + Overview of usual language dependent terms + (\emph{continuation})% + }% + \entry{\Macro{abstractname}}{% + heading of the abstract% + \IndexCmd{abstractname}% + }% + \entry{\Macro{alsoname}}{% + ``see also'' in additional cross references of the index% + \IndexCmd{alsoname}% + }% + \entry{\Macro{appendixname}}{% + ``appendix'' in the heading of an appendix chapter% + \IndexCmd{appendixname}% + }% + \entry{\Macro{bibname}}{% + heading of the bibliography% + \IndexCmd{bibname}% + }% + \entry{\Macro{ccname}}{% + prefix heading for the distribution list of a letter% + \IndexCmd{ccname}% + }% + \entry{\Macro{chaptername}}{% + ``chapter'' in the heading of a chapter% + \IndexCmd{chaptername}% + }% + \entry{\Macro{contentsname}}{% + heading of the table of contents% + \IndexCmd{contentsname}% + }% + \entry{\Macro{enclname}}{% + prefix heading for the enclosure of a letter% + \IndexCmd{enclname}% + }% + \entry{\Macro{figurename}}{% + prefix heading of figure captions% + \IndexCmd{figurename}% + }% + \entry{\Macro{glossaryname}}{% + heading of the glossary% + \IndexCmd{glossaryname}% + }% + \entry{\Macro{headtoname}}{% + ``to'' in header of letter pages% + \IndexCmd{headtoname}% + }% + \entry{\Macro{indexname}}{% + heading of the index% + \IndexCmd{indexname}% + }% + \entry{\Macro{listfigurename}}{% + heading of the list of figures% + \IndexCmd{listfigurename}% + }% + \entry{\Macro{listtablename}}{% + heading of the list of tables% + \IndexCmd{listtablename}% + }% + \entry{\Macro{pagename}}{% + ``page'' in the pagination of letters% + \IndexCmd{pagename}% + }% + \entry{\Macro{partname}}{% + ``part'' in the heading of a part% + \IndexCmd{partname}% + }% + \entry{\Macro{prefacename}}{% + heading of the preface% + \IndexCmd{prefacename}% + }% + \entry{\Macro{proofname}}{% + prefix heading of mathematical proofs% + \IndexCmd{proofname}% + }% + \entry{\Macro{refname}}{% + heading of the list of references% + \IndexCmd{refname}% + }% + \entry{\Macro{seename}}{% + ``see'' in cross references of the index% + \IndexCmd{seename}% + }% + \entry{\Macro{tablename}}{% + prefix heading at table captions% + \IndexCmd{tablename}% + }% +\end{desclist} +% +\EndIndex{Cmd}{providecaptionname}% +\EndIndex{Cmd}{newcaptionname}% +\EndIndex{Cmd}{renewcaptionname}% +% +\EndIndex{}{language>definition} + + +\section{Identification of \KOMAScript} +\label{sec:scrbase.identify} + +\Package{scrbase} may be used independent of \KOMAScript{} with +other packages and classes, nevertheless it's a \KOMAScript{} package. For +this is also provides commands to identify \KOMAScript{} and itself as a +\KOMAScript{} package. + +\begin{Declaration} + \Macro{KOMAScript} +\end{Declaration} +\BeginIndex{Cmd}{KOMAScript}% +This command only sets the word ``\KOMAScript'' with sans-serif font and +a little bit tracking of the capitals. Bay the way: All \KOMAScript{} classes +and packages define this command, if it hasn't been defined already. The +definition is robust using \Macro{DeclareRobustCommand}. +% +\EndIndex{Cmd}{KOMAScript} + + +\begin{Declaration} + \Macro{KOMAScriptVersion} +\end{Declaration} +\BeginIndex{Cmd}{KOMAScriptVersion}% +\KOMAScript{} defines the main version of \KOMAScript{} in this command. It +has the form ``\PName{date} \PName{version} \texttt{KOMA-Script}''. This main +version is same for all \KOMAScript{} classes and the \KOMAScript{} packages, +that are essential for the classes. Because of this, it may be inquired after +loading \Package{scrbase} too. This document has been made, e.\,g., using +\KOMAScript{} version ``\KOMAScriptVersion''. +% +\EndIndex{Cmd}{KOMAScriptVersion}% + + +\section{Extension of the \LaTeX{} Kernel} +\label{sec:scrbase:latexkernel} + +Sometimes the \LaTeX{} kernel itself provides commands, but lacks of other, +similar commands, that would often be useful too. Some of those commands for +authors of packages and classes are provided by \Package{scrbase}. + +\begin{Declaration} + \Macro{ClassInfoNoLine}\Parameter{class name}\Parameter{information}\\ + \Macro{PackageInfoNoLine}\Parameter{package name}\Parameter{information}% +\end{Declaration}% +\BeginIndex{Cmd}{PackageInfoNoLine}% +\BeginIndex{Cmd}{ClassInfoNoLine}% +For authors of classes and package the \LaTeX{} kernel already provides +commands like \Macro{ClassInfo} and \Macro{PackageInfo} to write information +together with the current line number into the log-file. Beside +\Macro{PackageWarning} and \Macro{ClassWarning} to throw warning messages with +line numbers, it also provides \Macro{PackageWarningNoLine} and +\Macro{ClassWarningNoLine} for warning messages without line +numbers. Nevertheless, the commands \Macro{ClassInfoNoLine} and +\Macro{PackageInfoNoLine}, to write information without line numbers into the +log-file, are missing. Package \Package{scrbase} provides them. +% +\EndIndex{Cmd}{ClassInfoNoLine}% +\EndIndex{Cmd}{PackageInfoNoLine} + + +\begin{Declaration} + \Macro{l@addto@macro}\Parameter{command}\Parameter{extension}% +\end{Declaration}% +\BeginIndex{Cmd}{l@addto@macro}% +The \LaTeX{} kernel already provides an internal command \Macro{g@addto@macro} +to extend the definition of macro \Macro{command} by \PName{extension} +globally. This may be used only for macros that have no +arguments. Nevertheless, sometimes a command like this, that works locally to +a group instead of globally, could be useful. Package \Package{scrbase} +provides such a command with \Macro{l@addto@macro}. An alternative may be +usage of package \Package{etoolbox}\IndexPackage{etoolbox}, that provides +several of such commands for different purpose (see \cite{package:etoolbox}). +% +\EndIndex{Cmd}{l@addto@macro} + + +\section{Extension of the Mathematical Features of \eTeX} +\label{sec:scrbase:etex} + +\eTeX{}, that is meanwhile used by \LaTeX{} and needed by \KOMAScript{}, +provides with \Macro{numexpr}\IndexCmd{numexpr} an extended feature for +calculation of simple arithmetic with \TeX{} counters and +integers. The four basic arithmetic operations and brackets are +supported. Correct rounding is done while division. Sometimes additional +operators would be useful. + +\begin{Declaration} + \Macro{XdivY}\Parameter{dividend}\Parameter{divisor}\\ + \Macro{XmodY}\Parameter{dividend}\Parameter{divisor}% +\end{Declaration}% +\BeginIndex{Cmd}{XdivY}% +\BeginIndex{Cmd}{XmodY}% +Having a division with remainder, command\ChangedAt{v3.05a}{\Package{scrbase}} +\Macro{XdivY} gives the value of the integer quotient, command \Macro{XmodY} +the value of the remainder. This kind of division is defined: +\[ +\textit{dividend} = \textit{divisor} \cdot +\textit{integer quotient} + \textit{remainder} +\] +with \textit{dividend} and \textit{remainder} are integer, \textit{remainder} +is greater or equal to \textit{divisor}, and \textit{divisor} is a natural +number greater than 0. + +The value may be used for assignment to a counter or directly in the +expression of \Macro{numexpr}. For output the value as an Arabic number is has +to be prefixed by \Macro{the}.% +% +\EndIndex{Cmd}{XmodY}% +\EndIndex{Cmd}{XdivY}% +% +\EndIndex{Package}{scrbase}% + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% ispell-local-dictionary: "english" +%%% coding: us-ascii +%%% TeX-master: "../guide.tex" +%%% End: |