diff options
Diffstat (limited to 'Master/texmf-dist/source/latex3/template/template.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex3/template/template.dtx | 2053 |
1 files changed, 2053 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex3/template/template.dtx b/Master/texmf-dist/source/latex3/template/template.dtx new file mode 100644 index 00000000000..286449af968 --- /dev/null +++ b/Master/texmf-dist/source/latex3/template/template.dtx @@ -0,0 +1,2053 @@ +% \iffalse +%% +%% (C) Copyright 1999 David Carlisle, Frank Mittelbach +%% All rights reserved. +%% +%% Not for general distribution. In its present form it is not allowed +%% to put this package onto CD or an archive without consulting the +%% the authors. +%% +%<*dtx> + \ProvidesFile{template.dtx} +%</dtx> +%<package>\NeedsTeXFormat{LaTeX2e} +%<package>\ProvidesPackage{template} +%<driver>\ProvidesFile{template.drv} +% \fi +% \ProvidesFile{template.dtx} + [1999/09/28 v0.14 template parsing (DPC,FMi)] +% +% \iffalse +%<*driver> + \documentclass{ltxdoc} +\makeatletter + \newenvironment{decl}[1][]% + {\par\small\addvspace{4.5ex plus 1ex}% + \vskip -\parskip + \ifx\relax#1\relax + \def\@decl@date{}% + \else + \def\@decl@date{\NEWfeature{#1}}% + \fi + \noindent\hspace{-\leftmargini}% + \begin{tabular}{|l|}\hline\ignorespaces}% + {\\\hline\end{tabular}\nobreak\@decl@date\par\nobreak + \vspace{2.3ex}\vskip -\parskip\@afterheading} +\makeatother + + \begin{document} + \DocInput{template.dtx} + \end{document} +%</driver> +% \fi +% +% +% \CheckSum{864} +% +% \GetFileInfo{template.dtx} +% +% \title{The \textsf{template} package\thanks{This file +% has version number \fileversion, last +% revised \filedate.}} +% \author{DPC, FMi} +% \date{\filedate} +% \maketitle +% +% \changes{0.06}{1998/12/17}{generic functions reborn as templates} +% +% \tableofcontents +% +% \section{Introduction} +% A \emph{Template} is a named `function' that has a fixed number +% of \emph{mandatory arguments} and an additional set of \emph{keys} +% or `named attributes' that are set in a `key value list'. That is, +% a comma separated set of assignments of the form:\\ +% \meta{key$_1$} |=| \meta{value$_1$} |,| +% \meta{key$_2$} |=| \meta{value$_2$} \ldots +% +% More specific instances of the template may be declared by +% specifying settings of the parameters. The key value list is parsed +% at the time the instance is declared, and an `internal' set of +% parameter assignments is passed to the template code. It is normally +% not parsed at run-time, though it is possible to enforce this +% behaviour. +% +% Templates have a \emph{type} and a \emph{name}. Templates +% of the same type have the same argument and parameter +% structure. That is, templates of the same type are expected to be +% exchangeable semantically. (However, except for checking that +% templates of the same type always have the same number of arguments +% this is not enforced by the code.) +% +% A template type is declared via the |\DeclareTemplateType| +% declaration which takes two arguments: the name for the type and the +% number of arguments a template of this type requires. +% +% Templates are declared via the |\DeclareTemplate| +% command which takes five arguments +% \begin{itemize} +% \item The \emph{type} of the template (no |\|). +% \item The \emph{name} of the template (no |\|). +% \item The number of arguments for the template (same as on type +% declaration). +% \item A list declaring the keys accepted by the template, +% with information about the action to take when the key is specified +% with a value. +% \item The code for the template. This may be arbitrary \TeX\ +% code. At some point it should execute |\DoParameterAssignments| +% to run the parameter assigments. +% +% The mandatory arguments are accessed via |#1|, |#2|, \ldots +% \end{itemize} +% +% +% Each element of the key specification list is of the form: +% \begin{flushleft} +% \meta{key name} |=| +% \meta{key type} \meta{optional default} \meta{internal code} +% \end{flushleft} +% +% The \meta{key types} are essentially specified by giving a symbolic +% representation of the assignment function to be used by \TeX. +% +% Currently the possibilities are +% +% \begin{center}\catcode`|=12 +% \begin{tabular}{l|ll|l} +% key type& letter& internal code& argument form\\\hline +% Command & f\emph{n}&command name & command definition\\ +% name & n & command name & command definition\\ +% length & l & length register& calc length syntax\\ +% fake length & L & command name & calc length syntax\\ +% count & c & count register& calc count syntax\\ +% fake count & C & command name & calc count syntax\\ +% boolean & b & name of \verb|\newif| switch& true or false\\ +% switch & s & \marg{true code}\marg{false code}& true or false\\ +% instance& i\marg{type}& command name& instance of this \emph{type}\\ +% direct & x & Internal code& any\\ +% general & g & general code & any +% \end{tabular} +% \end{center} +% +% In addition, any of these types may be prefixed by |+| to +% denote a global assignment (described below). +% |f| takes a digit from 0--9 to denote the number of arguments. +% |n| is in fact the same as |f0|. When an instance is declared +% The value assigned to the key should be the definition of +% the command, using |#1|\ldots|#9| to denote the specified arguments. +% +% |c| takes an internal form a count register, +% not a \LaTeX\ counter name. +% +% For |f|, |n|, |l|, and |c|, the assignment is done twice, once +% at the time an instance is \emph{declared}. (This may involve +% using \textsf{calc} expresions. Then the `primitive assignment' +% of the value (not using calc) is copied to the internal parameter +% list, to be executed when an instance is run. Sometimes you need the +% expression to be evaluated at the time an instance is run rather +% than the time it is declared. For example it may be an expression +% involving some values that are not fixed throughout a document. +% In this case the instance declaration may give a value in the +% form |\DelayedEvaluation|\marg{calc expression}. In this case +% the value is not evaluated when the instance is declared, and +% instead the entire expression is copied to the `internal parameter +% list' and is evaluated whenever the instance is used. +% +% |L| and |C| take the same value types as |l| and |c| but the internal +% assignments are to macros not registers. +% +% Keys declared with |b| and |s| each take values either \emph{true} or +% \emph{false}. if the key zzz is declared with |b| then specifying +% |zzz=true| will essentially pass |\zzztrue| to the internal parameter +% list (although in fact |\zzztrue| need not be defined) . If instead +% zzz had been declared via |s|, then |zzz=true| would pass the tokens +% of the \marg{true code} to the internal parameter list. +% +% If a key is specified as |x|, then when used the \emph{internal code} +% will be copied to the internal parameter lists. This code may use |#1| +% to denote the value supplied to the key in the instance declaration. +% Note that this code is \emph{only} copied at the time the instance is +% declared. It is not executed at this time. It is executed when the +% instance is executed.\footnote{Despite the question of whether or +% not x and g are still necessary these days, they have the wrong +% `names' since x is the one that is not executed during delcaration +% while g is.} +% +% If a key is declared with |g| then the code is run at the time the +% instance is declared. By default \emph{nothing} is passed to the +% internal parameter list. This code may use |#1| to denote the +% value that will be supplied when an instance is declared. +% Any code that should be run when an instance is executed should +% be explicitly passed to the internal parameter list using +% |\addto@hook\TP@toks{|\ldots|}| +% +% A key declared with |i|\marg{type} takes as value the name of a +% declared instance of that type. The command token associated with +% the key will store a command essentially equivalent to a call +% to |\UseInstance|\marg{type}\marg{name}, but in a slightly optimised +% internal form. +% As an exception to this rule the replacement code may be of the form +% |\UseTemplate| followed by the key settings for the template +% but without the mandatory arguments. In this case the `inner' +% instance declaration is `pre compiled' and the token assigned to +% the store the value assigned to this key will execute an instance +% of the template directly, it will not re-parse the keyword settings +% each time the instance is used. +% +% \section{Commands} +% +% +% \subsection{Template declaration commands} +% +% \begin{decl} +% |\DeclareTemplateType| \marg{type}\marg{num} +% \end{decl} +% Declare a template type. +% +% \begin{decl} +% |\DeclareTemplate| +% \marg{type}\marg{tname}\marg{num}\marg{keyspec}\marg{code} +% \end{decl} +% Declare a template \meta{tname} of type \meta{type} with the set of +% keys as defined by \meta{keyspec}. From this template instances can +% be declared using |\DeclareInstance| At runtime such instances will run +% \meta{code} and expect \meta{num} mandatory arguments (same number +% for all templates of one type).\footnote{The \meta{num} argument is +% redundent as it can be deduced from the type. However, for practical +% reasons it seems better to keep that information with each +% individual template declaration.} +% +% \begin{decl} +% |\DeclareRestrictedTemplate| +% \marg{type}\marg{new-tname}\marg{old-tname}\marg{keyvals} +% \end{decl} +% Declare as new template \meta{new-tname} for type \meta{type} by +% taking template \meta{old-tname} as the basis and setting one or +% more of its keys to specific values. +% +% \begin{decl} +% |\DoParameterAssignments| +% \end{decl} +% The list of key value assignments made (and saved) during template +% declaration is evaluated at this point in the template code. +% +% +% \subsection{Instance declaration commands} +% +% \begin{decl} +% |\DeclareInstance| \marg{type}\marg{iname}\marg{tname}\marg{keyvals} +% \end{decl} +% Declare an instance of type \meta{type} named \meta{iname} build +% from using template \meta{tname} with key settings as given by +% \meta{keyvals}. +% +% \begin{decl} +% |\DeclareCollectionInstance| +% \marg{collection}\marg{type}\marg{iname}\marg{tname}\marg{keyvals} +% \end{decl} +% Same as |\DeclareInstance| except that this instance is only active +% when for the type \meta{type} the collection \meta{collection} was +% selected via |\UseCollection|. E.g., within the frontmatter one +% could make all headings behave differently by defining collection +% instances for template type `head'. +% +% \subsection{Key value commands} +% +% \begin{decl} +% |\DelayEvaluation|\marg{code} +% \end{decl} +% Used in the value spec for an instance to declare that the value +% \meta{code} should not be evaluated at declaration time but at +% run-time. Can also be used in the defaults for keys (given in square +% brackets) in the declaration of templates. +% +% \begin{decl} +% |\MultiSelection| \meta{counter} \marg{cases} \marg{else} +% \end{decl} +% Used in the value spec for an instance key to declare that the value of +% this key depends on the current setting of \meta{counter} at run-time. +% The \meta{cases} argument is a comma-separated list of ``values'', +% the \meta{else} argument a single ``value''. If at run-time +% \meta{counter} has the value $i$ then the $i$-th element of the +% \meta{cases} list is selected. If that does not exist the +% \meta{else} case is returned. +% +% +% \subsection{Processing commands} +% +% \begin{decl} +% |\UseTemplate| \marg{type}\marg{tname}\marg{keyval} +% \end{decl} +% Execute a template \meta{tname} of type \meta{type} at run-time +% using \meta{keyvals} as the value assignments for its keys. In this +% case the keys are evaluated at run-time thus this method is far +% slower than using a predeclared instance of this template (see +% below). This command can also appear as the value for a key of type +% `i' in which case the evaluation happens at declaration time of the +% template that contains this key! +% +% +% \begin{decl} +% |\UseInstance| \marg{type}\marg{iname} +% \end{decl} +% Run the instance \meta{iname} of template type \meta{type}. If a +% collection is in force see if there is a collection instance of name +% \meta{iname} and if so run that instead. +% +% \begin{decl} +% |\UseCollection| \marg{type}\marg{collection} +% \end{decl} +% Declare that from now on (normal scoping rules) the collection +% \meta{collection} for template type \meta{type} is in force. This +% means that a call to |\UseInstance| will first check if there is a +% collection instance defined, and if so use that instance, otherwise +% use the normal instance. +% +% +% \subsection{Test commands} +% +% \begin{decl} +% |\IfExistsInstanceTF| \marg{type}\marg{iname}\marg{true}\marg{false} +% \end{decl} +% Test if for template type \meta{type} an instance with name +% \meta{iname} exists. Select \meta{true} or \meta{false} code +% accordingly. +% +% +% +% \section{Examples of template key types} +% +% The general syntax for key specification in templates (fourth argument +% of the command |\DeclareTemplate|) is: +%\begin{flushleft} +%| {| \\ +%| | \meta{key-name$_1$} |=|\meta{key-type$_1$} +% \meta{optional-default$_1$} \meta{storage-bin$_1$}|,|\\ +%| | \meta{key-name$_2$} |=|\meta{key-type$_2$} +% \meta{optional-default$_2$} \meta{storage-bin$_2$}|,|\\ +%| ...|\\ +%| }| +%\end{flushleft} +% In this section we look at all possible key types and give examples +% for them. +% +% +% \subsection{Attributes that receive names as values} +% +% The type |n| expects to receive a \LaTeX{} name as a value. Used, +% for example, to specify the name of a \LaTeX{} counter to use. +%\begin{verbatim} +% heading-id =n \heading@id, +% counter-id =n [\DelayEvaluation{\heading@id}] \heading@counter, +%\end{verbatim} +% Notice the use of |\DelayEvaluation| in the default of +% |counter-id|. It is necessary to make the default the token +% |\heading@id| if we want to inherit the value from the |heading-id| +% key. Otherwise it gets value of |\heading@id| at the time the +% instance is declared. +% +% +% \subsection{Attributes that receive functions as values} +% +% +% The type |f|\meta{num} expects a function with \meta{num} arguments +% as a value. The arguments are denoted by |#1|, |#2|, etc. In most +% cases either |f0| (for declarations) or |f1| (to format one argument) are +% needed. +%\begin{verbatim} +% initial-font =f0 \initial@font, +% initial-format =f1 [#1] \initial@boxhandling, +%\end{verbatim} +% +% \subsection{Attributes that receive dimensions as values} +% +% As far as specifying instances the |l| and |L| type behave +% identically. They differ only in the type of internal storage-bin +% they need: |l| expects a length register while |L| expects an +% ordinary macro name and assigns its value via |\def|. +%\begin{verbatim} +% pre-sep =l \topsep, +% post-sep =L \botsep, +%\end{verbatim} +% +% +% +% \subsection{Attributes that receive integers as values} +% +% The |c| and |C| type receive integers as values. Again either of +% them can be transparently used. In case of |c| the +% \meta{storage-bin} has to be a \TeX{} count register not a \LaTeX{} +% counter name, i.e., set up via |\newcount|. (\LaTeX{} counters can +% be used as well if they are accessed via their internal name, i.e., +% via |\c@|\meta{\LaTeX-counter}) +%\begin{verbatim} +% pre-penalty =c \@beginparpenalty, +% penalty =C \hmaterial@penalty, +%\end{verbatim} +% +% +% +% \subsection{Attributes that receive template instances as values} +% +% The type |i|\marg{type} takes as value the name of a declared +% instance of that type. The \meta{storage-bin} associated with the +% key will store a command essentially equivalent to a call to +% |\UseInstance|\marg{type}\marg{name}, but in a slightly optimised +% internal form. +% +% As an exception to this rule the replacement code may be of the form +% |\UseTemplate| followed by the key settings for the template but +% without the mandatory arguments. In this case the `inner' instance +% declaration is `pre compiled' and the token assigned to the store +% the value assigned to this key will execute an instance of the +% template directly, it will not re-parse the keyword settings each +% time the instance is used. +%\begin{verbatim} +% justification-setup =i{justification} \list@justification, +%\end{verbatim} +% +% Usage within an instance declaration is either +%\begin{verbatim} +% justification-setup = raggedright, +%\end{verbatim} +% i.e., name of a declared instance or a call to |\UseTemplate| +%\begin{verbatim} +% justification-setup = \UseTemplate{justification}{TeX} +% { startskip = 0pt, ... }, +%\end{verbatim} +% +% +% +% \subsection{Attributes that receive true or false values} +% +% The type |s| expects the strings |true| or |false| as values. In +% this case the declaration has no \meta{storage-bin}. Instead the +% declaration consists of two brace groups containing code. Depending +% on the value one of the groups gets copied verbatim into the +% internal parameter list of the instance and gets executed at +% run-time at the point where |\DoParameterAssignments| is seen. +%\begin{verbatim} +% item-implicit-boolean =s +% { \def\item@implicit@code{\item\relax} }{}, +% numbered-boolean =b [true] @heading@nums, +%\end{verbatim} +% +% +% \subsection{Attributes that accept any value} +% +% The type |g| is a low-level specification which contains arbitrary +% code in place of the \meta{storage-bin}. This code is evaluated at +% declaration time of the instance and by default \emph{nothing} is +% passed to the internal parameter list (this has to happen explicitly +% from within the code). |#1| may be used to access the value +% specified. + +% The main purpose for this type is of historical nature (originally +% most of the other types have been implemented internally using |g|). +% +% The type |x| also requires code in place of the \meta{storage-bin}. +% However with this type all of the code is copied unevaluated to the +% internal parameter list. There are some applications for this type +% when implementing customisable defaults. However, it is likely that +% it will not survive a final release. +%\begin{verbatim} +% generic-key =g \typeout{#1}, +% extra-assigns =x \typeout{#1}, +%\end{verbatim} +% +% +% +% +% +% +% \section{A complete example} +% +% The following example shows a sketch of a template for typesetting +% captions to be used as part of a larger mechanism setting whole +% floats.\footnote{I made it up while I went along so if you spot the +% ``missing brace'' or some other blunder tell me, FMi.} +% +% We declare a template type \texttt{caption} then define an example +% template for that type and finally produce some instances from that. +% +% \subsection{Declaring the template type} +% +% To define the template type we first have to ask ourselves what +% information would be varying each time such a template is used? A +% potential answer could be the following: +% \begin{itemize} +% \item +% The float name, e.g., `Table' or `Fig.' etc. +% \item +% The float +% number e.g., `10' or `3--c' etc. +% \item +% The actual caption text as specified in the document. +% \end{itemize} +% Since the above items would be differed in each instantiation of +% such a template we would pass them as mandatory argument to the +% template. +% +% Are there others? Possibly. Here are two more that seem to be +% useful, at least in a number of cases: +% \begin{itemize} +% \item +% The text of the legend in document classes that distinguish +% between caption text (heading to the figure/table) and legend +% (explanatory material) +% \item +% Measure to which the caption should be typeset. +% \end{itemize} +% The last one of these might need some extra explanation. Suppose a +% design requires that the caption width is decided depending on the +% width of the table of figure, e.g., the caption is supposed to +% typeset below some illustration and should not be wider than that +% illustration, or the caption is typeset aside to the illustration +% using the remaining space. In that case the process that formats the +% whole float needs to communicate with the current template to pass +% that (varying) information along. Of course, that could happen by +% using global variables, e.g., the outer process sets the measure as +% desired before calling the caption formatting template. What makes +% more sense is likely to be a matter of taste but it also has to do +% with the precise semantics of the template type. Staying with our +% example: if the the semantics of the template type \texttt{caption} +% is supposed to produce a formatted box (in \TeX{} terms) then we +% should pass the measure as an argument if we ever intend to allow +% for variations. If on the other hand the semantics are to format a +% certain set of text into the current galley (which has measure of +% its own) then a measure argument would not belong to this template +% type. +% +% Are there other variations sensible? Yes, for example, instead of +% passing a fixed string like ``Fig.'' as the first argument one could +% pass an abstract float type identifier and let the template worry to +% deduce from that information what fixed string to produce. +% +% Another question: why should we pass the fixed text (or an abstract +% identifier from which it can be deduced) and the number as separate +% arguments to the template instead of passing a combined string (like +% it is done in the |\@makecaption| command of \LaTeXe{})? Answer: +% because this allows to build templates that can individually +% manipulate both bits of information, e.g., to format the number in a +% different font, etc. +% +% So what are the conclusions of this discussion? Defining the +% semantics of a template type is difficult and often needs several +% trials to come up with something that is covering the anticipated +% use. There is clearly not a cardinal way for defining template +% types; how the overall separation into smaller units is done is +% partly a matter of taste and partly a matter of the major layout +% characteristics that one tries to support. +% +% Returning to our example: let's assume we settle for the first four +% arguments, i.e., the calling template is responsible for setting the +% measure for the caption text if necessary. +% +% What we also have to do is to define (at least for ourselves) what +% data the arguments accept and what their semantics are. An informal +% summary of that could be the following: +% \begin{center} +% \begin{tabular}{rrl} +% \textit{Arg} & \textit{Data Type} & \textit{Description} \\[3pt] +% 1 & text & fixed float description +% \\ +% 2 & text/|\NoValue| & float number +% \\ +% 3 & text & caption text +% \\ +% 4 & text/|\NoValue| & legend text +% \\ +% \end{tabular} +% \end{center} +% The second and the fourth argument are allowed to be missing (i.e., +% can get |\NoValue| passed as a value). Note that the empty string in +% case of a text argument is different from |\NoValue|. +% +% We further declare that it is permissible for a template of this +% type to ignore the information provided by all arguments except 3, +% i.e., the caption text. +% +% Finally the result of the template formatting should is to typeset +% text into a current galley (paragraph mode in \LaTeX{} lingua). +% +% All the above is semantic information that (at least right now) is +% not being enforced by declaring a template type (except for the +% number of arguments) but each template of a certain type is supposed +% to conform to this specification nonetheless.\footnote{To make this +% even clearer we are thinking of extending the template type +% declaration with another argument in which one has to formally or +% informally (?) specifies information like the one in the table +% above.} +% +% This finally leads to the following declaration: +%\begin{verbatim} +%\DeclareTemplateType{caption}{4} +%\end{verbatim} +% +% \subsection{Defining a first template} +% +% We start by defining a simple template of type \texttt{caption} +% which roughly formats a caption like those being presented in +% \LaTeXe{}'s article class, i.e., the caption is typeset as a +% paragraph if it is longer than a single line, otherwise it is +% centered. The legend even if present is ignored. Above and below we +% give the designer the possibility to add some space. +% +% In fact the examples is more or less identical in code to +% |\@makecaption| except that if the second argument (i.e., the +% number) is |\NoValue| it and its preceding space\footnote{For those +% who wonder: spaces are by default ignored within definitions when +% the new packages are used due to a command \texttt{\textbackslash +% IgnoreWhiteSpace}, do get a normal space one has to use +% \texttt{\textasciitilde} and to obtain an unbreakable space +% \texttt{\textbackslash nobreakspace}.} gets ignored. +% +% We start by declaring the template \texttt{toosimple} of type +% \texttt{caption} having four mandatory arguments (as described in +% the discussion of the template type). +%\begin{verbatim} +%\DeclareTemplate{caption}{toosimple}{4} +%\end{verbatim} +% The next argument of |\DeclareTemplate| lists all keys for the +% template. In this case we have keys for the vertical spaces above +% and below. We make them type |L| to save on registers but with a bit +% of care we could also have used scratch registers like |\@tempskipa| +% etc. Their default values are both zero. +%\begin{verbatim} +% { +% above-skip =L [0pt] \caption@above@skip , +% below-skip =L [0pt] \caption@below@skip , +% } +%\end{verbatim} +% The final argument of |\DeclareTemplate| contains the actual +% processing code. We start with looking at the second mandatory +% argument (caption number) to find out if it is |\NoValue| and +% depending on the result define a helper command |\caption@start|. +%\begin{verbatim} +% { +% \IfNoValueTF{#2} +% { \def\caption@start{#1:~} } +% { \def\caption@start{#1~#2:~} } +%\end{verbatim} +% Having dealt with the prelims we now run |\DoParameterAssigments| at +% which point the keys of the template are made available, e.g., at +% this point all those right hand containers such as +% |\caption@above@skip| get assigned the value specified in an +% instantiation of the template. (That scheme allows to do preliminary +% processing up front, e.g., defaults for the keys could be assigned +% prior to that point in which case they are overwritten if the +% template instance specifies a different value. the use of specifying +% defaults via the |[..]| syntax as done above is slightly faster at +% run-time but needs more memory.) +%\begin{verbatim} +% \DoParameterAssigments +%\end{verbatim} +% The rest of the code should look familiar to anybody who ever looked +% at \texttt{article.cls}. The only point worth mentioning are the +% |\relax| commands after |\caption@above@skip| and +% |\caption@below@skip|. Since we have decided to use |L| as key type +% these commands are macros and not registers containing the +% dimensions as strings. This means that we have to be careful to +% ensure that \TeX{} knows where the dimension ends. In certain cases +% text following such a command might be mistaken as being part of the +% dimension (e.g., if followed by the word \texttt{plus}, etc.). In +% the code below this could only happen for the second |\vskip| but it +% is good practice to always add a terminating |\relax| to avoid such +% hidden traps. +%\begin{verbatim} +% \vskip \caption@above@skip \relax +% \sbox \@tempboxa {\caption@start #3} +% \ifdim \wd\@tempboxa >\hsize +% \caption@start #3\par +% \else +% \global \@minipagefalse +% \hb@xt@\hsize{\hfil\box\@tempboxa\hfil} +% \fi +% \vskip \caption@below@skip \relax +% } +%\end{verbatim} +% +% Why is the above template of not much use? Simply because it doesn't +% offer any flexibility to declare different designs. The only +% alteration offered to the designer is to modify the space above and +% below the caption, e.g., the following declaration would mimic the +% definition within the \texttt{article.cls} class of \LaTeXe: +%\begin{verbatim} +%\DeclareInstance{caption}{article}{toosimple} +% { +% above-skip = 0pt, +% below-skip = 10pt, +% } +%\end{verbatim} +% And that's all that can be manipulated. All items that people asking +% to change, e.g., not having a colon after the number, using +% different fonts and font sizes, etc.\ are still hard-wired and thus +% inaccessible. So we have to do better if we want to make use of the +% power the template mechanism offers. +% +% +% +% \subsection{Defining a better template} +% +% First step in defining better templates is to ask ourselves a couple +% of questions: +% \begin{itemize} +% \item What are the main characteristics of the layout the template +% is supposed to support? +% \item What are the elements that we want to allow (or can allow) the +% designer to modify? +% \end{itemize} +% +% Take the first question first: the layout supported by the template +% of the previous section had as its main characteristics that it +% would center the caption if it would fit in a single line in the +% current measure. We could consider this being an unchangable +% characteristic of the layout this template produces (and a designer +% would need to use a different template of type \texttt{caption} if a +% design compatible with this restriction is desired) or we could try +% to make our template smarter by adding bells and wistles that allow +% the designer to say stuff like: +%\begin{verbatim} +% one-line-format = \hfil #1 \hfil, +%\end{verbatim} +% or +%\begin{verbatim} +% one-line-action = center, +%\end{verbatim} +% depending on how we intend to offer changing the behavior of the +% template. Like when trying to define sensible template types we have +% no single road to heaven (and probably as many to hell) --- it has a +% lot to do with how we think about design. +% +% My advice, after having tried to work with these concepts for a +% while, is to keep templates simple in so far as that most of not all +% attribute for a template should be relevant for the design. In other +% words, if you have attributes that, depending on their setting, make +% half of the other attributes not applicable then it may be +% appropriate to think about providing several templates instead. To +% give an example from \LaTeXe: instead of having |\@startsection| +% deal with both vertical heads and run-in heads provide individual +% templates. (|\@startsection| is this famous command where design +% switches are build in by making dimensions negative to signal +% something and afterwards use the absolute value.) +% Another way to look at this is to say that a template should +% normally not contain large amounts of code which is only selected in +% a subset of attribute settings. +% +% As said before there are no golden rules, it is perfectly possible +% to make hugely complicated templates that solve every possible +% aspect of layout one could think of in one go --- it is just that +% with keeping it more simple one can get the same functionality with +% less headaches for the template writer as well as the template user +% later on. +% +% Returning to our example: allowing to handle the case of a single +% line caption specially could well be considered part of the +% template. In contrast: layouts that would put the caption number +% sideways, i.e., which would need totally different internal coding +% should probably be coded as a separate template of type +% \texttt{caption}. +% +% So for our next example template we settle for the fixed caption +% text plus number (if any) being at the beginning of the variable +% caption text (coming from the document) and being together formatted +% as some sort of a pargraph. In case of the whole caption being a +% single line we allow the designer to specify how to lay it out +% (e.g., centered, flush left, etc.). If there is a legend it will get +% formatted by a vertical space followed by the legend formatted as +% another paragraph. +% +% More precisely we allow for the following bells and wistles: +%\begin{verbatim} +%\DeclareTemplate{caption}{lesssimple}{4} +% { +%\end{verbatim} +% The designer can specify the space above and below the caption like +% we did in our first example. +%\begin{verbatim} +% above-skip =L [0pt] \caption@above@skip , +% below-skip =L [0pt] \caption@below@skip , +%\end{verbatim} +% Regarding the caption number we support the case where no number is +% present (the value being |\NoValue|) as well as the number being +% present. For both cases the designer has to specify what formatting +% should be attached. By default all is being typeset in the font the +% whole caption is presented but if there is a need for it the +% designer can use the following keys to attach special formatting +% devices to each particular item beside specifying special spacing +% information or replacing the default colon after the number with +% something else. +%\begin{verbatim} +% number-format =f2 [#1~#2:~] \caption@number@format, +% nonumber-format =f1 [#1:~] \caption@nonumber@format, +%\end{verbatim} +% If the caption is fitting onto a single line we make it possible +% for the designer to specify how this single line should be +% positioned (the default is to center the line). +%\begin{verbatim} +% single-line-format =f1 [\hfil#1\hfil] \caption@single@line@format, +%\end{verbatim} +% The font for the caption (including the fixed text and the number +% unless specified differently above) is going to be the one decided +% by the next key. +%\begin{verbatim} +% caption-font =f0 [\normalfont] \caption@font, +%\end{verbatim} +% The next attribute deserves some extra explanation: here we make use +% of an interface which is explained in more detail when we reveil the +% support for galley formatting.\footnote{Guess I have to apologize +% for the fact that i partly make use of that interface in this +% example while on other occasions (like the use of vertical spacing) +% within the example I do not---consistency around midnight is not my +% strength I fear (FMi).} In a nutshell the template type \texttt{hj} +% (hyphenation \& justification) allows one to define a) the +% justification concepts applied to the upcoming paragraphs, e.g., +% whether they should be set flush left, adjusted, first line +% centered, etc.\ b) the linebreaking strategy used and c) the +% hyphenation rules which should apply. All this is done by selecting +% an appropriate (predefined) instance of this type as will hopefully +% become somewhat clearer in the example instances shown below. +%\begin{verbatim} +% caption-hj-setup =i {hj} [default] \caption@hj@instance, +%\end{verbatim} +% In case there is a legend to format we give the designer the +% possibility to specify by how much vertical space it should be +% separated from the preceding paragraph (i.e., the caption text). The +% attributes for font and hj setup are comparable to those for the +% caption text itself (except that they will only apply to the +% legend). The only addition is the key \texttt{legend-text} which is +% allowed to take a fixed text (plus any formating and spacing for it) +% which will be added to the front of the legend in case it is +% provided at all (by default it is empty). +%\begin{verbatim} +% legend-sep =L [0pt] \caption@legend@sep , +% legend-text =f0 [] \caption@legend@text, +% legend-font =f0 [\normalfont] \caption@legend@font, +% legend-hj-setup =i {hj} [default] \caption@legend@hj@instance, +% } +%\end{verbatim} +% The actual code for the template should hold few if any +% surprises. In fact it is more or less identical to the one of the +% first template example, except that now we have now taken out some +% of the hardwired decisions and placed them into attributes. +%\begin{verbatim} +% { +% \IfNoValueTF{#2} +% { \def\caption@start{\caption@number@format{#1}{#2}} } +% { \def\caption@start{\caption@nonumber@format{#1}} } +% \DoParameterAssigments +% \vskip \caption@above@skip \relax +%\end{verbatim} +% To properly measure the caption to determine if it fits a single +% line we have to set it in the right font, so here as well as below +% we have to apply |\caption@font|. +%\begin{verbatim} +% \sbox \@tempboxa {\caption@font \caption@start #3} +% \ifdim \wd\@tempboxa >\hsize +% \begingroup +% \caption@font \caption@hj@instance +% \caption@start #3\par +% \endgroup +% \else +% \global \@minipagefalse +% \hb@xt@\hsize{\caption@single@line@format{\box\@tempboxa}} +% \fi +%\end{verbatim} +% To decide whether or not we have to set any legend we have to test +% |#4| for being |\NoValue|. This part of the code was not present in +% the previous example but otherwise should be straight forward. +%\begin{verbatim} +% \IfNoValueF{#4} +% { +% \vskip \caption@legend@sep \relax +% \begingroup +% \caption@legend@font \caption@legend@hj@instance +% \caption@legend@text +% #4\par +% \endgroup +% } +% \vskip \caption@below@skip \relax +% } +%\end{verbatim} +% +% I wouldn't claim the the above template is good or contains +% everything that would be desired and I'm sure that in the end we +% will have several such template for typesetting the caption part and +% perhaps decide on a different template type in the first place. So +% this is only to give a glimpse of how the template interface could +% be applied and I hope that reading it can see a) how they can apply +% it to other areas as well as see what is wrong with the example +% itself. +% +% To just note one point that i thought of being wrong after writing +% the above paragraphs: the key \texttt{single-line-format} was +% declared to be a function with one argument with the idea that +% besides specifying the single line should be centered (|\hfil|) on +% both sides, or flush left, or flush right (|\hfil| on one side) one +% could also specify something like +%\begin{verbatim} +% single-line-format = \hspace{10pt}#1\hfil, +%\end{verbatim} +% that is a fixed indentation on the left in case where the caption is +% a single line. However, of course one can't. Or at least it is not +% safe to do so since our test in the code tests the width of the line +% without taking into account such a finite fixed space and guess what +% might happen? So in summary, flexibility needs some thought and +% often some afterthoughts as well --- happy thinking :-) +% +% +% +% \subsection{Defining a few instances} +% +% So let us conclude this example with a few sample instances. We +% start with one that repeats what current \LaTeXe{} provides in the +% article class. It shows all keys with values. However in fact only +% the first key is actually needed since all others are the same as +% the default values in the template (and of course a legend is not +% specifiable in standard \LaTeX{} coding so those settings simply do +% not apply anyway). +%\begin{verbatim} +%\DeclareInstance{caption}{article}{lesssimple} +% { +% above-skip = 10pt, +% below-skip = 0pt, +% number-format = #1~#2:~, +% nonumber-format = #1:~, +% single-line-format = \hfil#1\hfil, +% caption-font = \normalfont, +% caption-hj-setup = default, +% legend-sep = 0pt, +% legend-text = , +% legend-font = \normalfont, +% legend-hj-setup = default, +% } +%\end{verbatim} +% +% The next examples are taken from books on the shelf essentially a +% random selection I fear. This one is from \emph{Introduction to +% Database Design} by C.~J.~Date and it uses Helvetica for the caption +% text with the caption flush left, with the figure and the fixed +% string (e.g., `Fig.' in bold face) separated by a quad of space. No +% legend either so this is not set up. The \texttt{hj} instance +% \texttt{noindentflushleft} is supposed to produce a ragged right paragraph +% without any indentation. It would have to be set up elsewhere +% (instance to the template of type \texttt{hj}). +%\begin{verbatim} +%\DeclareInstance{caption}{DATE}{lesssimple} +% { +% above-skip = 10pt, +% below-skip = 0pt, +% number-format = \textbf{#1~#2}\quad, +% nonumber-format = \textbf{#1}\quad, +% single-line-format = #1\hfil, +% caption-font = \fontfamily{phv} \normalfont, +% caption-hj-setup = noindentflushleft, +% } +%\end{verbatim} +% +% The final example is from the book ``Methods of Book Design'' by +% H.~Williamson which sets the caption centered if it fits a single +% line but adjusted as a paragraph without any indentation if longer +% than a single line. It uses old style numerals followed by a period +% for the number (though the example isn't quite right as i guess the +% text font used already has oldstyle numerals as default, so +% |\oldstylenums| is in fact not necessary). +%\begin{verbatim} +%\DeclareInstance{caption}{WILLIAMSON}{lesssimple} +% { +% above-skip = 10pt, +% below-skip = 0pt, +% number-format = #1~\oldstylenums{#2}.~, +% nonumber-format = #1~, +% single-line-format = \hfil#1\hfil, +% caption-font = \normalfont, +% caption-hj-setup = noindentadjusted, +% } +%\end{verbatim} +% +% +% +% \section{Notes} +% +% \subsection{Note on multi-valued parameters} +% +% +% The following code\footnote{docu taken from trial implementation in +% xlists.dtx, FMi} implements for registers (ie L,l,C,c keys) and +% for names (ie n key) a multi-selection mechanism of the following +% form: +% \begin{verbatim} +% key = \MultiSelection \@listdepth { +% \DelayEvaluation {2.5em}, +% 20pt + 34pt } +% { \DelayEvaluation {1em} }, +% \end{verbatim} +% where the first argument to |\MultiSelection| is a counter, the +% second argument is a comma separated list of values denoting the +% values for the cases 1, 2,\ldots, and the third argument contains +% the value for all other cases. +% +% The values are evaluated at declaration time in case of registers +% and therefore can contain calc expressions as well as +% |\DelayEvaluation|. +% +% Due to the implementation the case list is not allowed to have a +% trailing comma! And of course no checks are made whatsoever :-( +% +% A probably much nicer syntax would be something like this: +% \begin{verbatim} +% key = \MultiSelection { +% selector = \@listdepth, +% 1 = \DelayEvaluation {2.5em}, +% 2 = 20pt + 34pt, +% else = \DelayEvaluation {1em} +% }, +% \end{verbatim} +% but i found that too difficult to implement right now. +% +% I think it should also be considered if this kind of thing should be +% a generally available feature on all key types especially on the +% f\meta{number} ones. +% +% Anyway it is what i need for lists right now and as such it is +% sufficient. +% +% +% \subsection{Notes on template restriction} +% +% Possible semantics: +% +% a: just:-) changes the defaults ie the new template has as +% defaults those of its source as modified by the supplied +% keyvals; +% +% b: similar to a: but also removes some keywords ie the new template +% will not accept the keywods whose values are set by the suppied +% keyvals; +% +% c: plan C. +% +% +% Towards an implementation of b: but without a restriction on what +% keys appear where. +% +% +% +% +% \subsection{Open issues} +% +% In this section unresolved issues or ideas to think about and +% perhaps implement are collected. There is no particular order to +% them. +% +% \begin{itemize} +% \item The order of arguments in |\UseCollection| is illogical in my +% eyes! A collection typically modifies the behavior of several +% types and thus should perhaps be first (as it is in the +% |\DeclareCollectionInstance| case). Or not, or what? +% +% \item How should |\IfExistsInstanceTF| behave for Collection +% instances? Do we need a special check for those or a default +% action? Or do we need an additional test for the existence of +% collection instances? +% +% \item It was suggested that the template type declaration should get +% another argument in which (in?)formally the semantics for the +% template types are described, e.g., data type of arguments, +% resulting output, \ldots{} (somewhat like the description arguments +% for functions and variables in Emacs-Lisp). The advantage being +% that this helps employing the templates better as well as perhaps +% guiding context sensitive editors to support the work with such +% templates (e.g., providing help texts). +% +% \item The same might be of interest for the keys of individual +% templates though here syntax support is already available to some +% extend by the declaration of key types. +% +% \item There might be a need to distinguish between \TeX's dimen and +% skip registers. Right now this is not done and both |l| and |L| +% accepts what \LaTeX{} calls ``rubber length'' specifications. +% +% \item The type |b| can probably vanish. It is equivalent to +% specifying the mutators of a |\newif| command in the brace groups, +% e.g. +%\begin{verbatim} +% numbered-boolean =b [true] @heading@nums, +% numbered-boolean =s [true] {\@heading@numstrue} +% {\@heading@numsfalse}, +%\end{verbatim} +% +% \item See issue raised about syntax (and semantics) for +% |\Multiselection|. +% +% \end{itemize} +% +% \StopEventually{} +% +% \section{Implementation} +% \begin{macrocode} +%<*package> +% \end{macrocode} +% +% \begin{macrocode} +\RequirePackage{ldcsetup} +% \end{macrocode} +% +% Ignore white space in this package. +% \begin{macrocode} +\IgnoreWhiteSpace +% \end{macrocode} +% +% Declare a private token register for building parameter lists. +% Having the number saves a few expandafters +% (probably not needed in the end). +% \begin{macrocode} +\newtoks\TP@toks +\newtoks\TP@toksb +\newtoks\TP@toksc +% \end{macrocode} +% +% +% \begin{macro}{\functiondefine} +% |\def| setup with a latex style `number of arguments' argument. +% definition setup left in toksb for possible future use. +% \begin{macrocode} +\def\functiondefine#1#2#3{% + \def\@tempa##1#1##2##{% + \TP@toksb\expandafter{\expandafter\def\expandafter#2\@gobble##1#1} + \the\TP@toksb}% + \@tempa0##1##2##3##4##5##6##7##8##9{#3}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@DCI} +% Declare a command name to be an instance of a template +% ie with a particular setting of the parameters.\\ +% |#1| internal command name for instance to be (globally) declared\\ +% |#2| template type/template name\\ +% |#3| key value assignments for parameters of |#2| +% \begin{macrocode} +\def\TP@DCI#1#2#3{ + \begingroup + \TP@get@restrictions {#2} % puts stuff in \TP@toks + \toks@\expandafter\expandafter\expandafter + {\csname TPD>/#2\endcsname\relax\relax} + \setkeys{\the\TP@toksc} % temp OK? + {#3} % adds stuff to \TP@toks + \expandafter\TP@add@default \the\toks@ % prepends stuff to \TP@toks + \xdef#1{ + \expandafter\ifx\csname TP>/#2\endcsname\TP@dpa + \the\TP@toks + \else + \noexpand\TP@assignments{\the\TP@toks} + \expandafter\noexpand\csname TP>/#2\endcsname + \fi} + \endgroup} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@dpa} +% \begin{macrocode} +\long\def\TP@dpa{\DoParameterAssignments} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@add@default} +% \begin{macrocode} +\def\TP@add@default#1#2{ + \ifx#1\relax + \else + \@temptokena{#2} + \edef\@tempa{{\the\@temptokena\the\TP@toks}} + \TP@toks\@tempa + \expandafter\TP@add@default + \fi} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\UseTemplate} +% |{type}{templatename}{keyval}| +% Directly use a template with a particular parameter setting. +% This is also picked up if used in a nested fashion inside a parameter +% list.\\ +% |#1| type of a template.\\ +% |#2| name of a template.\\ +% |#3| key value assignments for parameters of |#1|. +% \begin{macrocode} +\def\UseTemplate#1#2#3{ + \TP@get@restrictions {#1/#2} % from here ... + \toks@\expandafter\expandafter\expandafter + {\csname TPD>/#1/#2\endcsname\relax\relax} + \setkeys{\the\TP@toksc}{#3} + \expandafter \TP@add@default \the\toks@ % to here is : + % Shared with \def\DeclareCommandInstance + \TP@push + \csname TP>/#1/#2\endcsname} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\DoParameterAssignments} +% Acces the list stored in |\TP@toks|. +% \begin{macrocode} +\def\DoParameterAssignments{ + \expandafter\TP@pop\the\TP@stack\@@} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\TP@pop} +% \begin{macrocode} +\def\TP@pop#1#2\@@{ + \global\TP@stack{#2} + #1} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@stack} +% \begin{macrocode} +\newtoks\TP@stack +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@stack} +% \begin{macrocode} +\global\TP@stack{\relax}% avoid brace loss +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@assignments} +% Access the list stored in |\TP@toks|. +% \begin{macrocode} +\def\TP@assignments{ + \afterassignment\TP@push\TP@toks} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\TP@push} +% \begin{macrocode} +\def\TP@push{ + \global\TP@stack\expandafter + {\expandafter{\the\expandafter\TP@toks\expandafter} + \the\TP@stack}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\DeclareTemplateType} +% |{type}{nofarg}| +% \begin{macrocode} +\def\DeclareTemplateType#1#2{ + \expandafter\def\csname TP@<#1>\endcsname{{}#2}} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\TP@prefix} +% |{type}| returns prefix for csnames for type, based on current collection. +% \begin{macrocode} +\def\TP@prefix#1{ + <\expandafter\expandafter\expandafter + \@firstoftwo\csname TP@<#1>\endcsname>#1/} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\TP@args} +% |{type}| returns arg count for type, +% \begin{macrocode} +\def\TP@args#1{ + \expandafter\expandafter\expandafter + \@secondoftwo\csname TP@<#1>\endcsname} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\DeclareTemplate} +% |{type}{templatename}{nofarg}{keywordspec}{code}| +% \begin{macrocode} +\long\def\DeclareTemplate#1#2#3#4#5{ + \@ifundefined{TP@<#1>} + {\undefinedtype\DeclareTemplateType{#1}#3} + {\ifnum#3=\TP@args{#1}\relax\else + \BadArgCount\fi} +% \end{macrocode} +% Parse the key declaration, and execute the list with a suitable +% definition of |\KV@elt|. +% \begin{macrocode} + \let\KV@elt\TP@elt + \def\KV@default@elt##1{ + \PackageError{template}{Missing = after ##1}\@ehd} + \def\TP@name{#1/#2} + \toks@{} + \KV@parse{#4} +% \end{macrocode} +% +% Define the defaults +% \begin{macrocode} + \expandafter\edef\csname TPD>/\TP@name\endcsname{\the\toks@} +% \end{macrocode} +% +% Define the template +% \begin{macrocode} + \expandafter\newcommand\csname TP>/\TP@name\endcsname[#3]{#5}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@elt} +% The list of undefined keys and values is put in the list of the form\\ +% |\KV@elt|\marg{key}\marg{val}%^^A +% |\KV@elt|\marg{key}\marg{val}\ldots\\ +% So just need to give this macro a suitable definition. We just need +% to look at the first token of the value, to see what sort of key +% it is, so call a helper function to split that off. +% \begin{macrocode} +\def\TP@elt#1#2{% + \let\TP@global\@empty + \TP@do{#1}#2\TP@do} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@f@shift} +% Helper for |\TP@do|. +% \begin{macrocode} +\def\TP@f@shift#1#2{% + \TP@testopt{#1}{\TPkeycommand{#1}{#2}}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@i@shift} +% Helper for |\TP@do|. +% \begin{macrocode} +\def\TP@i@shift#1#2{% + \TP@testopt{#1}{\TP@instance{#1}{#2}}} +% \end{macrocode} +% +% declaration |hd =i{head} \fooo| \\ +% use |hd = mine|\\ +% makes |\fooo| shorthand for |\UseInstance{head}{mine}| +% +% also allowed: |hd = \UseTemplate{head}{...}{...}|\\ +% in case you want to use an unnamed instance of type |head| +% in this place. +% \end{macro} +% +% \begin{macro}{\TP@instance} +% \begin{macrocode} +\def\TP@instance#1#2#3{ + \TP@define@key{#1}{ + \TPinstance#3{#2}{##1}}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TPinstance} +% \begin{macrocode} +\def\TPinstance#1#2#3{ + \expandafter\ifx\@car#3.\@nil\UseTemplate + \typeout{\string\UseTemplate\space seen} +% \end{macrocode} +% +% code below from |\TPkeycommand| (should be combined and cleaned up) +% at this point one should also check if first arg of |\UseTemplate| +% corresponds to |#2| and if not complain (not done) +% +% \begin{macrocode} + {\TP@fudge#3} + \expandafter\addto@hook\expandafter\TP@toks\expandafter{ + \expandafter\KV@toks\expandafter{\TP@gtemp} + \edef#1{\the\KV@toks}} + \else + \@letinstance#1{#2}{#3} + \expandafter\expandafter\expandafter\addto@hook + \expandafter\expandafter\expandafter\TP@toks + \expandafter\expandafter\expandafter{ + \@letinstance#1{#2}{#3}} + \fi} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\TP@do} +% Case switch on the possible key types. +% \begin{macrocode} +\def\TP@do#1#2#3\TP@do{ + \ifx#2f + \TP@f@shift{#1}#3\@@ + \else\ifx#2n + \TP@testopt{#1}{\TPnamecommand{#1}}#3\@@ + \else\ifx#2l + \TP@testopt{#1}{\TP@register\setlength{#1}}#3\@@ + \else\ifx#2L + \TP@testopt{#1}{\TP@fakeregister\setlength\fake@length + {#1}}#3\@@ + \else\ifx#2c + \TP@testopt{#1}{\TP@register\SetInternalCounter{#1}}#3\@@ + \else\ifx#2C + \TP@testopt{#1}{\TP@fakeregister\SetInternalCounter\@tempcnta + {#1}}#3\@@ + \else\ifx#2b + \TP@testopt{#1}{\TP@setboolean{#1}}#3\@@ + \else\ifx#2s + \TP@testopt{#1}{\TP@booltest{#1}}#3\@@ + \else\ifx#2g + \TP@testopt{#1}{\TP@setgeneral{#1}}#3\@@ + \else\ifx#2x + \TP@testopt{#1}{\TP@setx{#1}}#3\@@ + \else\ifx#2i + \TP@i@shift{#1}#3\@@ + \else\ifx#2+ + \def\TP@global{\addto@hook\TP@toks{\global}} + \TP@do{#1}#3\TP@do + \else + \PackageError{template}{Unknown~key~type~ (#2)~for~#1}\@eha + \fi + \fi + \fi + \fi + \fi + \fi + \fi + \fi + \fi + \fi + \fi + \fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@testopt} +% \begin{macrocode} +\def\TP@testopt#1#2{ + \@ifnextchar[%] + {\TP@test@pt{#1}{#2}} + {\TP@zap@@{#2}}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@zap@@} +% \begin{macrocode} +\def\TP@zap@@#1#2\@@{ + #1{#2}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@test@pt} +% \begin{macrocode} +\def\TP@test@pt#1#2[#3]#4\@@{ + #2 + {#4} + \begingroup + \TP@toks{} + \let\TP@remove\@gobble + \csname KV@\TP@name @#1\endcsname{#3} + \expandafter + \endgroup + \expandafter + \toks@\expandafter{ + \csname KV@\TP@name @#1\expandafter\endcsname\expandafter + {\the\expandafter\TP@toks\expandafter}\the\toks@}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@setgeneral} +% \begin{macrocode} +\def\TP@setx#1#2{ + \TP@define@key{#1}{\addto@hook\TP@toks{#2}}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@setgeneral} +% \begin{macrocode} +\def\TP@setgeneral#1#2{ + \TP@define@key{#1}{#2}} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\TP@setboolean} +% \begin{macrocode} +\def\TP@setboolean#1#2{ + \expandafter\let\csname if#2\endcsname\iftrue + \TP@define@key{#1}{ + \TPsetboolean{#2}{##1}} +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TPsetboolean} +% Modify so the boolean does not need to have been +% declared with |\newif| +% \begin{macrocode} +\def\TPsetboolean#1#2{ + \expandafter\ifx\csname if#2\endcsname\relax + \PackageError{template}{Bad~boolean~setting~#1=#2}\@eha + \else + \expandafter\let\csname if#1\expandafter\endcsname + \csname if#2\endcsname + \expandafter\addto@hook\expandafter\TP@toks\expandafter{ + \expandafter\let + \csname if#1\expandafter\endcsname\csname if#2\endcsname} + \fi} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\TP@booltest} +% \begin{macrocode} +\def\TP@booltest#1#2{ + \TP@define@key{#1}{ + \TPbooltest{##1}#2}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@true} +% \begin{macrocode} +\def\TP@true{true} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TPbooltest} +% \begin{macrocode} +\def\TPbooltest#1#2#3{ +% no error check on this yet. + \def\@tempa{#1} + \ifx\@tempa\TP@true + \addto@hook\TP@toks{#2} + \else + \addto@hook\TP@toks{#3} + \fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@register} +% This is normally called automatically by |\DeclareTemplate|. +% +% Command for setting a template attribute whose name +% corresponds directly to a tex count or length register\\ +% |#1| the fuction to set the value eg \setlength.\\ +% |#2| key name.\\ +% |#3| the register to set. +% +% This command \emph{fully evaluates} the argument at declare time, +% and assigns the value to the register. It also passes an assignment +% of the register to the final value into the parameter list for the +% template. +% +% If the value is a call to |\DelayEvaluation|, don't evaluate it now, +% just pass the whole assignment to the template. +% +% [Note that the code below contains some : being used in csnames in other files +% this is currently being allowed by default but in this one it is right now +% manually added --- need fixing either way] +% \begin{macrocode} +\catcode`\:=11\relax +\def\TP@register#1#2#3{ + \TP@define@key{#2}{ + \expandafter\ifx\@car##1\@nil\DelayEvaluation + \addto@hook\TP@toks{#1#3{##1}} + \else +% \end{macrocode} +% +% +% check for |\MultiSelection| creeping up and if so add something like +% +% \begin{verbatim} +% \setlength\register{\ifcase\selector \or value1 \or value2 +% ... \else valueotherwise \fi} +% \end{verbatim} +% to |\TP@toks|. +% +% \begin{macrocode} + \expandafter\ifx\@car##1..\@nil\MultiSelection + \begingroup + \TP@multi#1#3##1 + \endgroup +% \end{macrocode} +% +% +% there are probably better ways to do this :-) +% +% \begin{macrocode} + \expandafter\in@\expandafter\DelayEvaluation + \expandafter{\the\TP@multi@toks} + \ifin@ + \addto@hook:No\TP@toks + {\expandafter#1\expandafter#3\expandafter + {\the\TP@multi@toks}} + \else + \addto@hook:No\TP@toks + {\expandafter #3 + \expandafter= \the\TP@multi@toks\relax} + \fi +% \end{macrocode} +% +% +% otherwise do as before +% +% \begin{macrocode} + \else + #1#3{##1} + \addto@hook:No\TP@toks + {\expandafter #3 + \expandafter= \the#3\relax} + \fi\fi}} +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}{\addto@hook:No} +% \begin{macrocode} +\def\addto@hook:No#1#2 { + \expandafter\addto@hook\expandafter#1\expandafter{#2}} +\catcode`\:=12\relax +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}{\DelayEvaluation} +% \begin{macrocode} +\let\DelayEvaluation\@firstofone +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TPkeycommand} +% Same for macro names. Again usually called automatically when +% declaring a new template.\\ +% |#1| the key.\\ +% |#2| Determines how many arguments the function should have.\\ +% |#3| The macro to be defined. +% +% If the `|##1|`, the value passed as the argument of the key |#1| +% to the macro |#3| is invoked starts with |\FunctionInstance|, then a +% special procedure is taken. Instead of defining a macro with the +% specified number of arguments, the paramater list of the nested +% function instance is parsed, and |#3| is defined to be a macro +% expanding to that instance. In this case the specified template +% is responsible for picking up the requested number of +% arguments. (This is \emph{not} checked.) +% \begin{macrocode} +\def\TP@define@key#1#2{% + \expandafter\def + \csname KV@\TP@name @#1\expandafter\endcsname + \expandafter##\expandafter1 + \expandafter{ + \expandafter\TP@remove + \csname KV@\TP@name @#1\expandafter\endcsname + \TP@global + #2}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@remove} +% \begin{macrocode} +\def\TP@remove#1{ + \def\@tempa##1#1##2##3#1##4\@@{ + \toks@{##1##3}} + \expandafter\@tempa\the\toks@#1\relax#1\@@} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TPkeycommand} +% \begin{macrocode} +\def\TPkeycommand#1#2#3{ + \TP@define@key{#1}{ +% \end{macrocode} +% +% |##1| can either be arbitrary inline code, in which case it will be +% defined with |\newcommand[val]| so it needs to use |#1| -- |#val|. +% +% define it locally here +% \begin{macrocode} + \functiondefine#2#3{##1} +% \end{macrocode} +% +% \begin{macrocode} + \expandafter\addto@hook\expandafter\TP@toks\expandafter{ + \the\TP@toksb{##1}} + } + } +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\TPnamecommand} +% Here is the extended version that tries to deal with +% |\MultiSelection|. +% +% In case of `n' keys there is no evaluation at declaration time so it +% is not sensible to look for |\DelayEvaluation|. For this reason as +% well as for the fact that |\TP@multi| above assumes that it deals +% with registers that can be accessed via |\the| we have to use a +% different command to handle the |\MultiSelection| args but +% it is essentially doing the same. +% +% \begin{macrocode} +\catcode`\:=11\relax +\def\TPnamecommand#1#2{ + \TP@define@key{#1}{ + \expandafter\ifx\@car##1..\@nil\MultiSelection + \begingroup + \TP@multi@name##1 + \endgroup + \addto@hook:No\TP@toks + {\expandafter\def\expandafter#2\expandafter + {\the\TP@multi@toks}} + \else + \def#2{##1} % setting it? + \addto@hook\TP@toks{\def#2{##1}} + \fi + } + } +\catcode`\:=12\relax +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@multi@name} +% \begin{macrocode} +%\catcode`\:=12\relax +\def\TP@multi@name #1#2#3#4{ + \global\TP@multi@toks{\ifcase #2} + \@for\next:=\@empty #3\do{ + \TP@do@multi\next +} + \global\addto@hook\TP@multi@toks{\else #4\fi} + } +%\catcode`\:=11\relax +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% +% +% +% \begin{macro}{\DeclareInstance} +% |{type}{instname}{templatename}{keyval}| +% \begin{macrocode} +\def\DeclareInstance{\DeclareCollectionInstance{}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\DeclareCollectionInstance} +% |{collection}{type}{instname}{templatename}{keyval}| +% \begin{macrocode} +\long\def\DeclareCollectionInstance#1#2#3#4{ + \expandafter\TP@DCI\csname<#1>#2/#3\endcsname{#2/#4}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\UseCollection} +% |{type}{collection}| +% \begin{macrocode} +\def\UseCollection#1#2{ + \expandafter\edef\csname TP@<#1>\endcsname{ + {#2} + \TP@args{#1}}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@letinstance} +% |\internalcommand{type}{instname}| +% \begin{macrocode} +\def\@letinstance#1#2#3{ + \expandafter\let\expandafter#1\csname + \@ifundefined{\TP@prefix{#2}#3} + {<>#2/} + {\TP@prefix{#2}} + #3 + \endcsname} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\UseInstance} +% |{type}{instname}| +% \begin{macrocode} +\def\UseInstance#1#2{ + \@letinstance\@tempa{#1}{#2} + \ifx\@tempa\relax + \INSTANCEundefined + \else + \expandafter\@tempa + \fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@fudge} +% \begin{macrocode} +\long\def\TP@fudge#1#2#3{% + \TP@DCI\TP@gtemp{#2/#3}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ShowTemplate} +% Some extension to |\ShowTemplate| so that we also get to see the +% restrictions if any +% \begin{macrocode} +\def\ShowTemplate#1#2{ + \typeout{*******~ Template:~ #1/#2~ *******} + \typeout{*} + \typeout{*~ Defaults:} + \typeout{*} + \typeout{\string\TPD>/#1/#2= + \expandafter\meaning\csname TPD>/#1/#2\endcsname} + \typeout{*} + \typeout{*~ Restrictions:} + \typeout{*} + \typeout{\string\TPR>/#1/#2= + \expandafter\meaning\csname TPR>/#1/#2\endcsname} + \typeout{*} + \typeout{*~ Body:} + \typeout{*} + \expandafter\show\csname TP>/#1/#2\endcsname} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\ShowCollectionInstance} +% \begin{macrocode} +\def\ShowCollectionInstance#1#2#3{ + \typeout{*******~ Instance:~ <#1>#2/#3~ *******} + \typeout{*} + \expandafter\show\csname <#1>#2/#3\endcsname} +\def\ShowInstance{\ShowCollectionInstance{}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@fakeregister} +% |{setcomand}{privateregister}{key}{internalcode}| +% \begin{macrocode} +\catcode`\:=11\relax +\def\TP@fakeregister#1#2#3#4{ + \TP@define@key{#3}{ + \expandafter\ifx\@car##1..\@nil\DelayEvaluation +% \end{macrocode} +% In the v0.08 version of \texttt{template.dtx} a +% |\DelayEvaluation| for a faked register would simply be equiv to +% a |\def| (code is below commented out). The negative side effect +% of this is that something like |=L| used with |\DelayEvaluation| +% would not allow for calc syntax since it would end up as +% |\def|\allowbreak|\foo|\allowbreak|{a+b}|. The code below changes +% this to first assign to a scratch register (at runtime) and then +% do an |\edef|. Could be coded differently to save space (at cost +% of time) +% \begin{macrocode} +% \addto@hook\TP@toks{\def#4{##1}} + \addto@hook\TP@toks{#1#2{##1}\edef#4{\the#2}} + \else +% \end{macrocode} +% +% +% Otherwise same game for fake registers except that instead of +% passing the register to |\TP@multi| we pass a temp fake one and +% doing a def instead of using |\setlength| or |\setcounter| +% +% and i haven't done the |\DelayEvaluation| bit for that case! as +% i'm not sure what the best approach is for those +% things\footnote{we might disallow it for that case in general --- +% not a nice rule but an explainable one} +% +% \begin{macrocode} + \expandafter\ifx\@car##1..\@nil\MultiSelection + \begingroup + \TP@multi#1#2##1 + \endgroup + \addto@hook:No\TP@toks + {\expandafter\def\expandafter#4\expandafter + {\the\TP@multi@toks}} + \else + #1#2{##1} + \addto@hook:No\TP@toks + {\expandafter + \def + \expandafter + #4 + \expandafter + {\the#2}} + \fi\fi}} +\catcode`\:=12\relax +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\TP@multi@toks} +% \begin{macrocode} +\newtoks\TP@multi@toks +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@multi} +% \marg{operation} \marg{register} |\MultiSelection| +% \marg{selector} \marg{case-list} \marg{else-case} +% +% This command builds up the |\ifcase| code from the three arguments +% of |\MultiSelection| and stores it in |\TP@multi@toks|. This code is +% supposed to be run in a group so a) we don't have to initialise +% |\TP@multi@toks| and b) all changes to the used registers not +% affecting the outside. +% +% Warning: this code uses |\@for| which will not work if put into files where +% ``:'' was made a letter! +% +% \begin{macrocode} +%\catcode`\:=12\relax +\def\TP@multi #1#2#3#4#5#6{ + \global\TP@multi@toks{\ifcase #4} + \@for\next:=\@empty #5\do{ + \expandafter \expandafter\expandafter\ifx\expandafter + \@car\next..\@nil\DelayEvaluation + \TP@do@multi\next + \else + #1#2{\next} + \TP@do@multi{\the#2} + \fi + } + \global\addto@hook\TP@multi@toks{\else #6\fi} + } +%\catcode`\:=11\relax +% \end{macrocode} +% +% Since we intend to add |\or| to |\TP@multi@toks| within the |\@for| +% loop we have to hide it carefully or else we will get some unmatched +% conditionals. +% \end{macro} +% +% \begin{macro}{\TP@do@multi} +% \begin{macrocode} +\def\TP@do@multi#1{ + \global\expandafter\addto@hook\expandafter\TP@multi@toks + \expandafter{\expandafter\or #1 } +} +% \end{macrocode} +% \end{macro} +% +% Since i like to set things like |item-label-text| using this +% mechanism i need to handle the `n' key specially. +% +% Actually i could have probably extended |\TPkeycommand| thus making +% this generally available to all f\meta{number} keys but was too lazy +% (or too stupid) to get it right first time so settled for the simple +% solution. +% +% So |\TP@do| now calls |\TPnamecommand| for the `n' key. looks like +% this thus be fixed some time soon +% +% +% +% +% +% +% \begin{macro}{\fake@length} +% \begin{macrocode} +\newlength\fake@length +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\IfExistsInstanceTF} +% tests that there is a \emph{default} definition +% taken from xinitials.dtx: +% \begin{macrocode} +\def\IfExistsInstanceTF#1#2{ + \expandafter\ifx\csname <>#1/#2\endcsname\relax + \expandafter\@secondoftwo + \else + \expandafter\@firstoftwo + \fi} +% \end{macrocode} +% +% FMi: what happens if we are in collection FOO and there exists an +% instance I for type T within this collection but there doesn't exist +% an instance in the empty collection? +% +% What would happen if \ldots\ --- not clear to me what the sematics +% really should be. The code below is not better only different( and +% slower).\footnote{fix semantics} +% \begin{macrocode} +\def\IfExistsInstanceTF#1#2{ + \@letinstance\@tempa{#1}{#2} + \ifx\@tempa\relax + \expandafter\@secondoftwo + \else + \expandafter\@firstoftwo + \fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\DeclareRestrictedTemplate} +% Setting it up: +% +%| \DeclareRestrictedTemplate|\\ +% |{T-type} {new-T-name} {source-T-name} {keyvals}| +% +% This uses the same code as {T-type} {source-T-name} but adds +% settings from {keyvals} +% \begin{macrocode} +\def\DeclareRestrictedTemplate#1#2#3#4{ + % CCC do we need a group here?? + \letcc { TPD>/#1/#2 } { TPD>/#1/#3 } + \letcc { TP>/#1/#2 } { TP>/#1/#3 } + \TP@get@restrictions {#1/#3} % puts stuff in \TP@toks + \setkeys{\the\TP@toksc} % temp OK? + {#4} % adds stuff to \TP@toks + \TP@store@restrictions {#1/#2}{#1/#3}} % stores the contents of + % \TP@toks +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\letcc} +% \begin{macrocode} +\def\letcc#1#2{ + \expandafter \let + \csname #1 \expandafter \endcsname + \csname #2 \endcsname} +% \end{macrocode} +% \end{macro} +% +% Internals: +% +% \begin{macro}{\TP@get@restrictions} +% These could probably be inlined, even when they do something! +% \begin{macrocode} +\def\TP@get@restrictions#1{ % Returns to \TP@toks the restrictions + % stored in the TP-structure (at present + % in YAM) of the template #1 + \@ifundefined {TPR>/#1} + {\TP@toks {}} + {\TP@toks \expandafter\expandafter\expandafter + {\csname TPR>/#1\endcsname}} + \@ifundefined {TPO>/#1} + {\@namedef {TPO>/#1} {#1} + \TP@toksc {#1} } % temp OK? + {\TP@toksc \expandafter\expandafter\expandafter + {\csname TPO>/#1\endcsname} }} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\TP@store@restrictions} +% \begin{macrocode} +\def\TP@store@restrictions#1#2{ % Stores the contents of \TP@toks + % in the TP-structure (at present + % in YAM) of the template #1 + \expandafter\edef\csname TPR>/#1\endcsname{\the\TP@toks} + \@ifundefined{TPO>/#2} + {\@namedef{TPO>/#1}{#2}} + {\letcc{TPO>/#1}{TPO>/#2}}} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</package> +% \end{macrocode} +% +% \Finale +% + + + |