diff options
Diffstat (limited to 'Master/texmf-dist/source')
| -rw-r--r-- | Master/texmf-dist/source/latex3/template/template.dtx | 2053 | ||||
| -rw-r--r-- | Master/texmf-dist/source/latex3/template/template.ins | 12 |
2 files changed, 0 insertions, 2065 deletions
diff --git a/Master/texmf-dist/source/latex3/template/template.dtx b/Master/texmf-dist/source/latex3/template/template.dtx deleted file mode 100644 index 286449af968..00000000000 --- a/Master/texmf-dist/source/latex3/template/template.dtx +++ /dev/null @@ -1,2053 +0,0 @@ -% \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 -% - - - diff --git a/Master/texmf-dist/source/latex3/template/template.ins b/Master/texmf-dist/source/latex3/template/template.ins deleted file mode 100644 index b8fe0900dc8..00000000000 --- a/Master/texmf-dist/source/latex3/template/template.ins +++ /dev/null @@ -1,12 +0,0 @@ -\input docstrip -\keepsilent -\askforoverwritefalse - -\preamble -\endpreamble - -\generate{% - \file{template.sty}{\from{template.dtx}{package}} - } - -\endbatchfile |