diff options
Diffstat (limited to 'Master/texmf-dist/source')
12 files changed, 0 insertions, 13647 deletions
diff --git a/Master/texmf-dist/source/latex/xpackages/xbase/ldcsetup.dtx b/Master/texmf-dist/source/latex/xpackages/xbase/ldcsetup.dtx deleted file mode 100644 index b47930bc217..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xbase/ldcsetup.dtx +++ /dev/null @@ -1,331 +0,0 @@ -% \iffalse -%% File: ldcsetup.dtx (C) Copyright 1999 Frank Mittelbach, Chris Rowley, David Carlisle -%% (C) Copyright 2004-2009 Frank Mittelbach, LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%% -%% This file is part of the ``xbase bundle'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -%<*driver|package> -\RequirePackage{expl3} -%</driver|package> -%\fi -\GetIdInfo$Id: ldcsetup.dtx 1628 2009-10-25 09:54:34Z mittelba $ - {coding conventions and stuff} -%\iffalse -%<*driver> -%\fi -\ProvidesFile{\filename.\filenameext} - [\filedate\space v\fileversion\space\filedescription] -%\iffalse -\documentclass{l3doc} -\begin{document} -\DocInput{ldcsetup.dtx} -\end{document} -%</driver> -% \fi -% -% \CheckSum{0} -% -% \title{The \textsf{ldcsetup} package\thanks{This file -% has version number \fileversion, last -% revised \filedate.}} -% \author{DPC, FMi} -% \date{\filedate} -% \maketitle -% -% \begin{abstract} -% Basic code shared by several other packages currently under development. -% \end{abstract} -% -% \StopEventually{} -% -% \begin{macrocode} -%<*package> -\ProvidesExplPackage - {\filename}{\filedate}{\fileversion}{\filedescription} -% \end{macrocode} -% \begin{macrocode} -\RequirePackage{keyval} -\RequirePackage{expl3} -\ExplSyntaxOff -% \end{macrocode} -% -% \section{Ignoring White Space} -% Within a package, or in a document preamble, you can use -% |\IgnoreWhiteSpace| this makes white space ignored, and |@| -% a letter, and |~| a space character. It lasts until the end of the -% current package or preamble. -% -%% Puts an ignored space at the end of the line, so `|\ |' does the right -% thing. (Perhaps should instead just change catcode of |^^M|) -% \begin{macrocode} -\def\IgnoreWhiteSpace{% - \edef\@tempa{% - \catcode`\noexpand\~=\the\catcode`\~\relax - \catcode`\noexpand\ =\the\catcode`\ \relax - \catcode`\noexpand\^^I=\the\catcode`\^^I\relax - \catcode`\noexpand\@=\the\catcode`\@\relax - \endlinechar=\the\endlinechar\relax - }% - \ifx\@currname\@empty - \expandafter\AtBeginDocument\expandafter{\@tempa}% - \else - \expandafter\AtEndOfPackage\expandafter{\@tempa}% - \fi - \catcode`\~=10\relax - \catcode`\ =9\relax - \catcode`\^^I=9\relax - \makeatletter - \endlinechar=` % - \relax -} -% \end{macrocode} -% The new syntax requires |:| and |_| to be letters; instead of -% putting that into |\IgnoreWhiteSpace| we make a new command which -% helps to gradually change packages from old to new syntax. -% \begin{macrocode} -\def\InternalSyntaxOn{% - \edef\@tempa{% - \catcode`\noexpand\~=\the\catcode`\~\relax - \catcode`\noexpand\ =\the\catcode`\ \relax - \catcode`\noexpand\^^I=\the\catcode`\^^I\relax - \catcode`\noexpand\@=\the\catcode`\@\relax - \catcode`\noexpand\:=\the\catcode`\:\relax - \catcode`\noexpand\_=\the\catcode`\_\relax - \endlinechar=\the\endlinechar\relax -%FMi fix is not properly reset - \endlinechar=13\relax - }% -%%% ???? -% this needs further work, don't think it is working - \ifx\InternalSyntaxOff\relax - \expandafter\def\expandafter\InternalSyntaxOff\expandafter - {\@tempa\let\InternalSyntaxOff\relax}% - \fi - \ifx\@currname\@empty - \expandafter\AtBeginDocument\expandafter{\@tempa}% - \else - \expandafter\AtEndOfPackage\expandafter{\@tempa}% - \fi - \catcode`\~=10\relax - \catcode`\ =9\relax - \catcode`\^^I=9\relax - \makeatletter - \catcode`\_=11\relax - \catcode`\:=11\relax - \endlinechar=` % - \relax -} -\let\InternalSyntaxOff\relax -% \end{macrocode} -% -% Do it for this package. -% \begin{macrocode} -%\InternalSyntaxOn -\ExplSyntaxOn -% \end{macrocode} -% -% \section{KV fixes} -% Allow\footnote{Not needed now?} key names to start with |\|. -% \begin{macrocode} -\cs_set_nopar:Npn \define@key#1#2{% - \@ifnextchar[ - {\KV@def{#1}{\string#2}} - {\@namedef{KV@#1@\string#2}####1}} -\cs_set_nopar:Npn \setkeys#1#2{% - \cs_set_nopar:Npn \KV@prefix{KV@#1@\expandafter\string}% - \KV@do#2,\relax,} -% \end{macrocode} -% -% Make KV |#| safe. -% \begin{macrocode} -% \end{macrocode} -% -% \begin{macrocode} -\newtoks\KV@toks -% \end{macrocode} -% -% \begin{macrocode} -\cs_set_nopar:Npn \KV@@sp@c#1\@nil#2\relax#3{\KV@toks{#1}\cs_set_nopar:Npx #3{\the\KV@toks}} -% \end{macrocode} -% -% Generate error messages on missing `,'. -% -% More exactly if two `=' appear after a key generate an error. -% The current KV just silently ignores everything after the second `='. -% \begin{macrocode} -\cs_set_nopar:Npn \KV@equal{=} -% \end{macrocode} -% -% \begin{macrocode} -\cs_set_nopar:Npn \KV@split#1=#2=#3\relax{% - \KV@@sp@def\@tempa{#1}% - \cs_set_nopar:Npn \@tempd{#3}% - \ifx\@tempa\@empty\else - \expandafter\cs_set_eq:NN \expandafter\@tempc - \csname\KV@prefix\@tempa\endcsname - \ifx\@tempc\relax - \KV@error{\@tempa\space \expandafter\@gobbletwo\string\@undefined}\@eha - \else - \ifx\@tempd\@empty - \KV@default - \else - \KV@@sp@def\@tempb{#2}% - \ifx\@tempd\KV@equal - \expandafter\@tempc\expandafter{\@tempb}\relax - \else - \KV@error{Extra~=~ sign~ after~ `#1'}\KV@erry - \fi - \fi - \fi - \fi} -% \end{macrocode} -% -% \begin{macrocode} -\cs_set_nopar:Npn \KV@erry{\expandafter\KV@errx\meaning\@tempd\relax ignored\MessageBreak - missing~comma~in~`\expandafter\strip@prefix\meaning\@tempb'~?} -% \end{macrocode} -% -% \begin{macrocode} -\cs_set_nopar:Npn \KV@errx#1>#2==\relax{% - `#2' } -% \end{macrocode} -% -% \begin{macrocode} -\cs_set_nopar:Npn \KV@default{% - \expandafter\cs_set_eq:NN \expandafter\@tempb - \csname\KV@prefix\@tempa @default\endcsname - \ifx\@tempb\relax - \KV@error{No value specified for \@tempa}\@eha - \else - \@tempb\relax - \fi} -% \end{macrocode} -% -% \LaTeX\ style error message. -% \begin{macrocode} -\cs_set_nopar:Npn \KV@error#1#2{\PackageError{keyval}{#1}{#2}} -% \end{macrocode} -% -% Instead of doing a full KV parse, and evaluating all the keys, -% you might want to parse a parameter list, even for undefined keys, -% removing spaces, splitting up the `,` and `=' and resolving cases -% where no value is supplied. This is used in |\DeclareGenericFunction| -% which \emph{defines} a set of keys via such a KV parse. -% -% A setting of |, key = value ,| will result in |\KV@elt{key}{value}| -% being added to the list, a seting of |, key ,| will result in -% |\KV@default@elt{key}| being added. At the end of the parse the list -% is executed. No keys are checked at this stage (so no csnames are used -% up) the two |\KV|\ldots|@elt| commands must be defined as appropriate. -% -% \begin{macrocode} -\cs_set_nopar:Npn \KV@parse#1{ - \begingroup -% \end{macrocode} -% -% Locally fudge |\KV@@def| to just add to a token register -% rather than make a definition. -% \begin{macrocode} -\cs_set_nopar:Npn \KV@@sp@c##1\@nil##2\relax##3{\addto@hook##3{{##1}}} -% \end{macrocode} -% -% Locally fudge |\KV@split| to just add to a token register -% rather than execute the code for the found keys. -% \begin{macrocode} -\cs_set_nopar:Npn \KV@split##1=##2=##3\relax{% - \cs_set_nopar:Npn \@tempd{##3}% - \expandafter\ifx\expandafter=\@firstofone##1=\else - \ifx\@tempd\@empty - \addto@hook\KV@toks\KV@default@elt - \KV@@sp@def\KV@toks{##1}% - \else - \ifx\@tempd\KV@equal - \addto@hook\KV@toks\KV@elt - \KV@@sp@def\KV@toks{##1}% - \KV@@sp@def\KV@toks{##2}% - \else - \KV@err{Extra `=' after `##1'}\@ehd - \fi - \fi - \fi} -% \end{macrocode} -% -% Initialise -% \begin{macrocode} - \KV@toks{} -% \end{macrocode} -% Do the parse -% \begin{macrocode} - \KV@do#1,\relax, -% \end{macrocode} -% Evaluate the token register outside the group. -% \begin{macrocode} - \expandafter - \endgroup - \the\KV@toks} -% \end{macrocode} -% -% \section{Calc fixes} -% -% Count Register assignments via calc. Here we also provide some -% global versions since a normal global prefix won't have any effect. -% \begin{macrocode} -\cs_set_eq:NN \SetInternalCounter \calc_int_set:Nn -\cs_set_eq:NN \GSetInternalCounter\calc_int_gset:Nn -% \end{macrocode} -% -% -% \section{Misc code that is best collected in one place} -% -% This section will receive odd code that would be of potential use to -% other packages and should eventually made it to the kernel -% (perhaps). -% -% \begin{macro}{\UndeclareRobustCommand} -% Remove a robust command from memory if it isn't used any -% longer. Of course this doesn't free the hash table but at least -% the space gets reclaimed. -% \begin{macrocode} -\cs_set_nopar:Npn \UndeclareRobustCommand#1{% - \cs_gundefine:N #1 - \exp_args:Nc \cs_gundefine:N {\cs_to_str:N #1~} -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macrocode} -%</package> -% \end{macrocode} -% -% \Finale -% diff --git a/Master/texmf-dist/source/latex/xpackages/xbase/template.dtx b/Master/texmf-dist/source/latex/xpackages/xbase/template.dtx deleted file mode 100644 index c5006a5e3fb..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xbase/template.dtx +++ /dev/null @@ -1,2452 +0,0 @@ -% \iffalse -%% File: template.dtx (C) Copyright 1999-2001 David Carlisle, Frank Mittelbach -%% (C) Copyright 2004-2009 Frank Mittelbach, LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%% -%% This file is part of the ``xbase bundle'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -%<*driver|package> -\RequirePackage{expl3} -%</driver|package> -%\fi -\GetIdInfo$Id: template.dtx 2063 2010-10-03 08:26:49Z mittelba $ - {template} -%\iffalse -%<*driver> -%\fi -\ProvidesFile{\filename.\filenameext} - [\filedate\space v\fileversion\space\filedescription] -%\iffalse -\documentclass{l3doc} -\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} - \catcode`\_=11 - \catcode`\:=11 - \DocInput{template.dtx} - \end{document} -%</driver> -% -% -% \fi -% -% -% \CheckSum{0} -% -% \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 -% |\toks_add_right:Nn\l_TP_KV_assignments_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 |\cs_set_nopar:Npn |. -%\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 -% { \cs_set_nopar:Npn \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 -% InternalSyntaxOn}, 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} -% { \cs_set_nopar:Npn \caption@start{#1:~} } -% { \cs_set_nopar:Npn \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} -% { \cs_set_nopar:Npn \caption@start{\caption@number@format{#1}{#2}} } -% { \cs_set_nopar:Npn \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|. -% -% \item |f0| keys should perhaps support |\UseTemplate| by replacing -% it with its internal form. or perhaps this is a rubbish idea? -% -% \item Marcin Wolinski suggested to use |\EvalOnUse| instead or in -% addition to |\DelayEvalutation|. -% -% \end{itemize} -% -% \StopEventually{} -% -% \section{Implementation} -% \begin{macrocode} -%<*package> -\ProvidesExplPackage - {\filename}{\filedate}{\fileversion}{\filedescription} -% \end{macrocode} -% -% \begin{macrocode} -\RequirePackage{expl3} -\RequirePackage{ldcsetup,xparse} -% \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} -\toks_new:N\l_TP_KV_assignments_toks -\toks_new:N\l_TP_default_assignments_toks -% \end{macrocode} -% -% -% -% \begin{macro}{\TP_declare_instance:Nnn} -% \begin{macro}{\TP_declare_instance:cnn} -% 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} -\cs_new_nopar:Npn \TP_declare_instance:Nnn #1#2#3 { - \group_begin: - \TP_instdecl_generate_assignments:nn {#2}{#3} - \cs_gset_nopar:Npx #1 { - \tl_if_eq:cNTF { TP>/#2 } \c_TP_doparameterassignments_tl -% \end{macrocode} -% If the body of the template consists only of the token -% |\DoParameterAssignments|, then we insert the list of parameter -% assignments directly. Otherwise we have push them onto the stack -% and prepare to execute the body code (which in turn will pop them -% again when it reaches |\DoParameterAssignments| inside). -% \begin{macrocode} - { \toks_use:N \l_TP_KV_assignments_toks } - { - \exp_not:N \TP_push_assignments:n - {\toks_use:N\l_TP_KV_assignments_toks} - \exp_not:c {TP>/#2} - } - } - \group_end:} -\cs_generate_variant:Nn \TP_declare_instance:Nnn {cnn} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\c_TP_doparameterassignments_tl} -% \begin{macrocode} -\tl_set:Nn \c_TP_doparameterassignments_tl {\DoParameterAssignments} -% \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} -\cs_new_nopar:Npn \UseTemplate #1#2#3{ - \TP_instdecl_generate_assignments:nn {#1/#2}{#3} - \TP_push_assignments: - \use:c { TP>/#1/#2 } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\DoParameterAssignments} -% Access the parameter assignment list that was once stored in -% |\l_TP_KV_assignments_toks| and then moved onto the -% |\g_TP_assignments_stack_toks|. -% \begin{macrocode} -\cs_new_nopar:Npn \DoParameterAssignments{ - \exp_after:wN - \TP_pop_and_execute_assignments:nw - \toks_use:N \g_TP_assignments_stack_toks \q_stop -} -% \end{macrocode} -% -% \end{macro} -% -% \begin{macro}{\TP_pop_and_execute_assignments:nw} -% \begin{macrocode} -\cs_new_nopar:Npn \TP_pop_and_execute_assignments:nw#1#2\q_stop{ - \toks_gset:Nn \g_TP_assignments_stack_toks {#2} - #1} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\g_TP_assignments_stack_toks} -% \begin{macrocode} -\toks_new:N \g_TP_assignments_stack_toks -\toks_gset:Nn \g_TP_assignments_stack_toks {\scan_stop:}% avoid brace loss -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_push_assignments:n} -% \begin{macro}{\TP_push_assignments:} -% Push a list of parameter assignments onto the -% |\g_TP_assignments_stack_toks|. As it all happens in token -% registers |#|s need no doubling. |\TP_push_assignments:| expects -% it to be |\l_TP_KV_assignments_toks| (needs fixing). -% \begin{macrocode} -\cs_new:Npn \TP_push_assignments:n#1{ - \toks_gput_left:Nn\g_TP_assignments_stack_toks{{#1}} -} -\cs_new_nopar:Npn \TP_push_assignments:{ - \toks_gset:No \g_TP_assignments_stack_toks - {\exp_after:wN - {\toks_use:N\exp_after:wN\l_TP_KV_assignments_toks\exp_after:wN} - \toks_use:N\g_TP_assignments_stack_toks} -} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% -% \begin{macro}{\DeclareTemplateType} -% |{type}{nofarg}| -% \begin{macrocode} -\cs_new_nopar:Npn \DeclareTemplateType #1#2{ - \tl_set:cn {TP@<#1>} {{}#2}} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TP_get_csname_prefix:n} -% |{type}| returns prefix for csnames for template type, -% based on current collection. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_get_csname_prefix:n #1 { - <\exp_after:wN\exp_after:wN\exp_after:wN - \use_i:nn - \cs:w TP@<#1>\cs_end:>#1/ -} -% \end{macrocode} -% -% \end{macro} -% -% \begin{macro}{\TP_get_arg_count:n} -% |{type}| returns arg count for the template type. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_get_arg_count:n #1 { - \exp_after:wN\exp_after:wN\exp_after:wN - \use_ii:nn - \cs:w TP@<#1>\cs_end: -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\DeclareTemplate} -% |{type}{templatename}{nofarg}{keywordspec}{code}| -% \begin{macrocode} -\cs_new:Npn\DeclareTemplate #1#2#3#4#5{ - \cs_if_free:cTF{TP@<#1>} - {\undefinedtype\DeclareTemplateType{#1}#3} - { - \int_compare:nNnF{#3}={\TP_get_arg_count:n{#1}} - { \BadArgCount } - } -% \end{macrocode} -% Parse the key declaration, and execute the list with a suitable -% definition of |\KV@elt|. -% \begin{macrocode} - \cs_set_eq:NN \KV_elt:nn \TP_templdecl_process_KV:nn - \cs_set_nopar:Npn \KV_default_elt:n##1{ - \PackageError{template}{Missing~ =~ after~ ##1}\@ehd} - \cs_set_eq:NN\KV@elt\KV_elt:nn - \cs_set_eq:NN\KV@default@elt\KV_default_elt:n - \tl_set:Nn \l_TP_curr_name_tl {#1/#2} - \toks_clear:N\l_TP_default_assignments_toks -% \end{macrocode} -% At this point there should be a test for which catcode regime we are -% in. We just test if spaces are ignored. -% \begin{macrocode} - %\int_compare:nNnTF{\char_value_catcode:n{`\ }}=\c_nine - %\KV_parse_picky_no_space_removal_no_sanitize:n - %\KV_parse_picky_space_removal_no_sanitize:n - \KV@parse{#4} -% \end{macrocode} -% -% Define the defaults: the setting for |TPD>/\l_TP_curr_name_tl| is a -% tricky since |\l_TP_default_assignments_toks| may contain |#|. We -% have to use an |x| expansion rather than -% |o| since that will hide those during the assignment. -% FIX THIS (see below)! -% \begin{macrocode} - \cs_set_nopar:cpx { TPD>/\l_TP_curr_name_tl } - {\toks_use:N\l_TP_default_assignments_toks} - - \tl_clear:c {TPR>/\l_TP_curr_name_tl} - - \tl_set_eq:cN {TPO>/\l_TP_curr_name_tl}\l_TP_curr_name_tl -% \end{macrocode} -% -% Define the template (using |\cs_new_nopar:Npn| means that one can't -% redefine a template easily). -% \begin{macrocode} - \cs_generate_from_arg_count:cNnn {TP>/\l_TP_curr_name_tl} - \cs_set:Npn {#3}{#5} -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\tl_set:cx} -% FIX this: The code above only works because in the past |\tl_set:cx| was -% defined as follows: -% \begin{macrocode} -\cs_set:Npn \tl_set:cx {\exp_args:Nc \tl_set:Nx} -% \end{macrocode} -% i.e., expanding the second arg at the very end. -% This is no longer the case but for the moment I revert to the old -% definition until the template code is fixed to not rely on |\tl_set:cx| -% expanding the second arg at the very last minute. -% \end{macro} -% -% \begin{macro}{\TP_templdecl_process_KV:nn} -% The list of undefined keys and values is put in the list of the form\\ -% |\KV_elt:nn|\marg{key1}\marg{val1}%^^A -% |\KV_elt:nn|\marg{key2}\marg{val2}\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} -\cs_new_nopar:Npn \TP_templdecl_process_KV:nn #1#2 {% - \cs_set_eq:NN \TP_templdecl_add_global_or_nothing: \prg_do_nothing: - \bool_set_false:N\l_TP_global_assignment_bool - \tl_set:Nn\l_TP_currkey_tl{#1} - \TP_templdecl_parse_KV:N#2\q_stop} -% \end{macrocode} -% \end{macro} -% -% -% -% \begin{macro}{\TP_templdecl_parse_KV:N} -% Case switch on the possible key types. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_parse_KV:N #1 { -% \end{macrocode} -% In |#1| we have key, in |#2| the first character after the equal -% sign and in |#3| the remainder of the line. We now have to parse -% that remainder to find out if it contains a default value (in -% brackets) and then set up the key declaration needed to parse -% instance declarations. The method is similar in most cases: we call -% |\TP_parse_optional_key_default:nw| which parses for the default -% and pass it already found key name as first argument, what to do in -% the end as second argument, and the remainder delimited by |\q_stop| -% so that it becomes parseable. -% -% Note that the code in the second argument to -% |\TP_parse_optional_key_default:nw| normally calls on a macro with -% one more argument than actually provided: the reason being that the -% missing argument will be the remainder of the line (added by -% |\TP_parse_optional_key_default:nw| after the default has be -% removed (if present)). -% \begin{macrocode} - \cs_if_free:cTF{TP_use_arg_type_#1:w} - {\PackageError{template}{Unknown~key~type~ (#1)~for~\l_TP_currkey_tl}\@eha} - {\use:c{TP_use_arg_type_#1:w}} -% \end{macrocode} -% The |f| and |i| keys are somewhat different since there we first -% have to parse for an additional argument (a digit in case of |f| -% or an template type name in case of |i|): -% \begin{macrocode} -% \end{macrocode} -% One more alternative: a |+| after the equal sign signals global -% so we change |\TP_templdecl_add_global_or_nothing:| to append a -% |\pref_global:D| to the assignment toks and then reparse the rest. -% \begin{macrocode} -% \cs_set_nopar:Npn \TP_templdecl_add_global_or_nothing: -% {\toks_put_right:Nn \l_TP_KV_assignments_toks {\pref_global:D} } -% \TP_templdecl_parse_KV:nw{#1}#3\TP_templdecl_parse_KV:nnw -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\l_TP_global_assignment_bool} -% For keeping track of the assignments. -% \begin{macrocode} -\bool_new:N \l_TP_global_assignment_bool -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_use_arg_type_+:w} -% The |+| does two things: Sets a boolean true to be used by the -% types that can't simply be prefixed with |\pref_global:D| and -% defines |\TP_templdecl_add_global_or_nothing:| to put the prefix -% onto the list. After that we simply call the big switch -% again.\footnote{It should probably all be changed to not rely on -% the prefix working}. -% \begin{macrocode} -\cs_new_nopar:cpn{TP_use_arg_type_+:w} { - \bool_set_true:N\l_TP_global_assignment_bool - \cs_set_nopar:Npn \TP_templdecl_add_global_or_nothing: - {\toks_put_right:Nn \l_TP_KV_assignments_toks {\pref_global:D} } - \TP_templdecl_parse_KV:N -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_use_arg_type_l:w} -% The |l| sets a length register. We disable the prefix and insert -% either |\gsetlength| or |\setlength| depending on whether a |+| -% was seen or not. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_l:w { - \TP_parse_optional_key_default:nw - { - \cs_set_eq:NN \TP_templdecl_add_global_or_nothing: \prg_do_nothing: - \bool_if:NTF \l_TP_global_assignment_bool - {\TP_templdecl_setup_register_key:Nn\gsetlength} - {\TP_templdecl_setup_register_key:Nn\setlength} - } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_use_arg_type_L:w} -% The |L| sets a fake length register. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_L:w { - \TP_parse_optional_key_default:nw - {\TP_templdecl_setup_fakeregister_key:NNn\setlength\l_tmpa_skip} -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_use_arg_type_c:w} -% The |c| sets a count register. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_c:w { - \TP_parse_optional_key_default:nw - { - \cs_set_eq:NN\TP_templdecl_add_global_or_nothing:\prg_do_nothing: - \bool_if:NTF \l_TP_global_assignment_bool - {\TP_templdecl_setup_register_key:Nn\GSetInternalCounter} - {\TP_templdecl_setup_register_key:Nn\SetInternalCounter} - } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_use_arg_type_C:w} -% The |C| sets a fake count register. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_C:w { - \TP_parse_optional_key_default:nw - {\TP_templdecl_setup_fakeregister_key:NNn - \SetInternalCounter\l_tmpa_int} -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_use_arg_type_n:w} -% The |n| sets a token list variable. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_n:w { - \TP_parse_optional_key_default:nw - {\TP_templdecl_setup_n_key:N} -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_use_arg_type_f:w} -% \begin{macro}{\TP_templdecl_parse_f_arg:nw} -% The |f| defines a command with between 0 and 9 arguments. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_f:w #1{ - %\TP_templdecl_parse_f_arg:nw {#1} - \TP_parse_optional_key_default:nw{\TP_templdecl_setup_f_key:Nn{#1}} -} -% \end{macrocode} -% Helper for |\TP_templdecl_parse_KV:nnw|. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_parse_f_arg:nw#1#2{ -% \end{macrocode} -% The third argument of |\TP_templdecl_setup_f_key:Nn|, i.e., the -% macro name, is the remaining data up to |\q_stop| which is picked up -% by |\TP_parse_optional_key_default:nw|. -% \begin{macrocode} - \TP_parse_optional_key_default:nw{\TP_templdecl_setup_f_key:Nn{#1}{#2}} -} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% -% \begin{macro}{\TP_use_arg_type_b:w} -% \begin{macro}{\TP_templdecl_setup_b_key:nn} -% The |b| uses access to the |\if_true:| and |\if_false:| -% primitives. Needed? -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_b:w { - \TP_parse_optional_key_default:nw - {\TP_templdecl_setup_b_key:n} -} -% \end{macrocode} -% -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_setup_b_key:n#1{ - \cs_set_eq:cN { if#1 } \if_true: - \TP_templdecl_define_key:n - { \TP_templdecl_eval_b_key_value:nn {#1}{##1} } -} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_eval_b_key_value:nn} -% Modify so the boolean does not need to have been -% declared with |\newif| -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_eval_b_key_value:nn#1#2{ - \cs_if_free:cTF {if#2} - { \PackageError{template}{Bad~boolean~setting~#1=#2}\@eha } - { \tl_set_eq:cc {if_#1:}{if_#2:} - \toks_put_right:Nf \l_TP_KV_assignments_toks - { \tl_set_eq:cc {if_#1:}{if_#2:} } - } -} -% \end{macrocode} -% -% \end{macro} -% -% \begin{macro}{\TP_use_arg_type_s:w} -% \begin{macro}{\TP_templdecl_setup_s_key:n} -% The |s| chooses between true and false. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_s:w { - \TP_parse_optional_key_default:nw - {\TP_templdecl_setup_s_key:n} -} -% \end{macrocode} -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_setup_s_key:n #1 { - \TP_templdecl_define_key:n - { \TP_templdecl_eval_s_key_value:nnn{##1}#1 } -} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% -% -% -% -% -% -% \begin{macro}{\TP_use_arg_type_i:w} -% The |i| expects an instance. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_i:w #1{ - \TP_parse_optional_key_default:nw{\TP_templdecl_setup_i_key:nnn{#1}} -} -% \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_templdecl_setup_i_key:nnn} -% MH change: do either local or global. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_setup_i_key:nnn#1#2{ - \TP_templdecl_define_key:n - { - \TP_templdecl_eval_i_key_value:Nnn #2 {#1}{##1} - } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_eval_i_key_value:Nnn} -% MH change: Add extra argument for local or global. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_eval_i_key_value:Nnn #1#2#3 { - \tl_if_head_eq_meaning:nNTF {#3.}\UseTemplate - { - \iow_term:x{\token_to_str:N\UseTemplate\space seen} -% \end{macrocode} -% -% Code below from |\TP_templdecl_setup_f_key:Nn| (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_templdecl_declare_tmp_instance:nnnn #3 } - \toks_put_right:No \l_TP_KV_assignments_toks - { \exp_after:wN \KV@toks \exp_after:wN {\g_tmpa_tl} } - %\TP_templdecl_add_global_or_nothing: - %\toks_put_right:Nn \l_TP_KV_assignments_toks - % { \cs_set_nopar:Npx #1{ \toks_use:N \KV@toks} } - \bool_if:NTF \l_TP_global_assignment_bool - {\toks_put_right:Nn \l_TP_KV_assignments_toks - {\cs_gset_nopar:Npx #1 { \toks_use:N \KV@toks}} - } - {\toks_put_right:Nn \l_TP_KV_assignments_toks - {\cs_set_nopar:Npx #1 { \toks_use:N \KV@toks}} - } - } - { - \TP_let_instance:Nnn#1{#2}{#3} -% \end{macrocode} -% We want the |\cs_set_eq:Nc| hiding in |\TP_let_instance:Nnn| to expand -% fully to two csnames so we put a |\tex_romannumeral:D 0| (which in -% itself expands to nothing) in front. This expands the |\cs_set_eq:Nc| fully -% before finding out that |\cs_set_eq:NwN| is not expandable. -% \begin{macrocode} - \toks_put_right:Nf \l_TP_KV_assignments_toks - { \TP_let_instance:Nnn#1{#2}{#3} } - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% -% -% -% -% \begin{macro}{\TP_use_arg_type_x:w} -% \begin{macro}{\TP_templdecl_setup_x_key:nn} -% The |x| runs internal code. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_x:w { - \TP_parse_optional_key_default:nw - {\TP_templdecl_setup_x_key:n} -} -% \end{macrocode} -% -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_setup_x_key:n#1{ - \TP_templdecl_define_key:n - { \toks_put_right:Nn\l_TP_KV_assignments_toks{#1} } -} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% -% -% -% -% \begin{macro}{\TP_use_arg_type_g:w} -% \begin{macro}{\TP_templdecl_setup_g_key:nn} -% The |g| runs any code. -% \begin{macrocode} -\cs_new_nopar:Npn\TP_use_arg_type_g:w { - \TP_parse_optional_key_default:nw - {\TP_templdecl_setup_g_key:n} -} -% \end{macrocode} -% -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_setup_g_key:n #1 { - \TP_templdecl_define_key:n{#1}} -% \end{macrocode} -% -% \end{macro} -% \end{macro} -% -% -% -% -% \begin{macro}{\TP_templdecl_define_key:n} -% Here we define the key in the current template. Original code from -% r522 is essentially unreadable but we keep it here until the -% internal structure is finally sorted out. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_define_key:n#1{ - \exp_after:wN \cs_set:Npn \cs:w - KV@\l_TP_curr_name_tl @\l_TP_currkey_tl - \exp_after:wN\cs_end: - \exp_after:wN##\exp_after:wN1\exp_after:wN{ - \exp_after:wN\TP_templdecl_remove_from_default_assignments:N - \cs:w KV@\l_TP_curr_name_tl @\l_TP_currkey_tl - \exp_after:wN \cs_end: - \TP_templdecl_add_global_or_nothing: - #1 - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% -% -% -% -% -% -% \begin{macro}{\TP_parse_optional_key_default:nw} -% Look for default value. -% \begin{macrocode} -\cs_set:Npn \TP_ignore_leading_space_in_arg_ii:nn#1#2{ - \exp_args:Nf\TP_ignore_leading_space_in_arg_ii_aux:nn - {\exp_not:N #2}{#1} -} -\cs_set:Npn \TP_ignore_leading_space_in_arg_ii_aux:nn#1#2{#2{#1}} - - -\DeclareDocumentCommand\TP_parse_optional_key_default:nw{mo}{ - \IfNoValueTF{#2} - {\TP_templdecl_finish_key_setup:nw{#1}} - {\TP_templdecl_finish_key_setup_with_default:nnw{#1}{#2}} -} -%\show\TP_parse_optional_key_default:nw -%\exp_args:Nc\show{\string\TP_parse_optional_key_default:nw} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_finish_key_setup:nw} -% After having parsed the line and not found any default value it -% remains to actually define the key for the instance parsing by -% executing the setup code (in |#1|) giving it |#2| (i.e., the -% remainder of the line) as an argument. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_finish_key_setup:nw#1#2\q_stop{ - \TP_ignore_leading_space_in_arg_ii:nn{#1}{#2} - %%%#1{#2} -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_finish_key_setup_with_default:nnw} -% If there is a default the situation is more complicated since we -% not only have to set up the key for the instance but also have to -% add the default value to |\l_TP_default_assignments_toks| in an -% appropriate way. -% -% First set up the the key itself: -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_finish_key_setup_with_default:nnw#1#2#3\q_stop{ - \TP_ignore_leading_space_in_arg_ii:nn{#1}{#3} - %%% #1 {#3} -% \end{macrocode} -% Now we run the new key code (which is stored in |\KV@...| hopefully) -% and give it the default found. By doing this in a group and by -% locally emptying |\l_TP_KV_assignments_toks| we will get the -% resulting assignment code into that register. -% -% (We set |\TP_templdecl_remove_from_default_assignments:N| to -% |\use_none:n| since this is a temporary operation and we don't want -% to change the default really.) -% \begin{macrocode} - \group_begin: - \toks_clear:N \l_TP_KV_assignments_toks - \cs_set_eq:NN \TP_templdecl_remove_from_default_assignments:N \use_none:n - \use:c{KV@\l_TP_curr_name_tl @\l_TP_currkey_tl}{#2} -% \end{macrocode} -% And now for a final trick: before closing the group again and losing -% our local changes we run |\exp_after:wN| several times to get the -% value of |\l_TP_KV_assignments_toks| into -% |\l_TP_default_assignments_toks| outside that group! -% \begin{macrocode} - \exp_after:wN - \group_end: - \exp_after:wN - \toks_set:Nn - \exp_after:wN - \l_TP_default_assignments_toks - \exp_after:wN - { \cs:w KV@\l_TP_curr_name_tl @\l_TP_currkey_tl \exp_after:wN \cs_end: - \exp_after:wN - { \toks_use:N \exp_after:wN \l_TP_KV_assignments_toks - \exp_after:wN - } - \toks_use:N\l_TP_default_assignments_toks - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% \begin{macro}{\c_TP_true_tl} -% \begin{macrocode} -\tl_new:Nn \c_TP_true_tl {true} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_eval_s_key_value:nnn} -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_eval_s_key_value:nnn#1#2#3 { -% no error check on this yet. - \tl_set:Nn \l_tmpa_tl {#1} - \tl_if_eq:NNTF \l_tmpa_tl \c_TP_true_tl - { \toks_put_right:Nn \l_TP_KV_assignments_toks {#2} } - { \toks_put_right:Nn \l_TP_KV_assignments_toks {#3} } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_setup_register_key:Nnn} -% 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 function to set the value eg \cs{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. Remember to remove -% the |\DelayEvaluation|. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_setup_register_key:Nn #1#2{ - \TP_templdecl_define_key:n{ - \tl_if_head_eq_meaning:nNTF{##1}\DelayEvaluation - { -% \end{macrocode} -% Old line commented out. Remove |\DelayEvaluation| and also remove -% the braces surrounding its argument. -% \begin{macrocode} - \toks_put_right:Nn \l_TP_KV_assignments_toks {#1#2{##1}} - %\toks_set:No\l_tmpa_toks{\use_ii:nn ##1} - %\toks_put_right:Nx \l_TP_KV_assignments_toks - % {\exp_not:n{#1#2}{\toks_use:N \l_tmpa_toks}} - } -% \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 |\l_TP_KV_assignments_toks|. -% -% \begin{macrocode} - { - \tl_if_head_eq_meaning:nNTF{##1..}\MultiSelection - { - \group_begin: - \TP_multiselection_add:nnnnnn #1#2##1 - \group_end: -% \end{macrocode} -% -% -% there are probably better ways to do this (:-) -% -% \begin{macrocode} - \tl_if_in:onTF{\toks_use:N\g_TP_multiselection_toks}\DelayEvaluation - { - \toks_put_right:No\l_TP_KV_assignments_toks - { - \exp_after:wN#1\exp_after:wN#2\exp_after:wN - {\toks_use:N\g_TP_multiselection_toks} - } - } - { - \toks_put_right:No\l_TP_KV_assignments_toks - { - \exp_after:wN #2 - \exp_after:wN= \toks_use:N\g_TP_multiselection_toks\scan_stop: - } - } -% \end{macrocode} -% -% -% otherwise do as before -% -% \begin{macrocode} - } - { - #1#2{##1} - \toks_put_right:No\l_TP_KV_assignments_toks { - \exp_after:wN #2 \exp_after:wN = \tex_the:D #2\scan_stop: - } - } - } - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% -% -% \begin{macro}{\DelayEvaluation} -% \begin{macro}{\MultiSelection} -% Since we are testing explicitly for |\DelayEvaluation| and -% |\MultiSelection| a few places we better give them unique -% meanings! -% \begin{macrocode} -\cs_new_nopar:Npn\DelayEvaluation #1{\use_none:n{\DelayEvaluation}#1} -\cs_new_nopar:Npn\MultiSelection #1{\use_none:n{\MultiSelection}#1} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_remove_from_default_assignments:N} -% Note: the toks register is more or less a plists and should -% perhaps be implemented as such as this would make far more -% readable code. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_remove_from_default_assignments:N#1{ - \cs_set_nopar:Npn \TP_tmp:w ##1#1##2##3#1##4\q_stop{ - \l_TP_default_assignments_toks{##1##3} - } - \exp_after:wN \TP_tmp:w - \toks_use:N\l_TP_default_assignments_toks #1\scan_stop:#1\q_stop} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_setup_f_key:Nn} -% Same for macro names. Again usually called automatically when -% declaring a new template.\\ -% |#1| Determines how many arguments the function should have.\\ -% |#2| The macro to be defined. -% -% If the `|##1|`, the value passed as the argument of the key -% to the macro |#2| 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 |#2| 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} -\cs_new_nopar:Npn \TP_templdecl_setup_f_key:Nn#1#2{ -% \end{macrocode} -% -% |##1| can either be arbitrary inline code, in which case it will be -% defined with something similar to |\newcommand[val]| so it needs to -% use |#1| -- |#val|. -% -% define it locally here (why this, David???) -% \begin{macrocode} - \TP_templdecl_define_key:n - { \TP_templdecl_define_function:NNn#1#2{##1} } -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TP_templdecl_define_function:NNn} -% Use number of arguments to define function. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_define_function:NNn#1#2#3{ - \cs_generate_from_arg_count:NNnn #2 \cs_set:Npn {#1}{#3} - \toks_put_right:Nf \l_TP_KV_assignments_toks { - \cs_generate_from_arg_count:NNnn #2 \cs_set:Npn {#1}{#3} - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% \begin{macro}{\TP_templdecl_setup_n_key:N} -% 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_multiselection_add:nnnnnn| above -% assumes that it deals -% with registers that can be accessed via |\toks_use:N| we have to use a -% different command to handle the |\MultiSelection| args but -% it is essentially doing the same. -% -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_setup_n_key:N#1{ - \TP_templdecl_define_key:n{ - \tl_if_head_eq_meaning:nNTF{##1..}\MultiSelection - { - \group_begin: - \TP_templdecl_multiselection:nnnn ##1 - \group_end: -% \end{macrocode} -% Extracting the correct item from the |\if_case:w| we are building -% requires a bit of care. Firstly we want to expand the appropirate -% number of times to get to the item but we also want to ensure we do -% not have any unwanted leftover |\fi:|s or other junk which is bound -% to cause errors later on. Therefore we start an |f| expansion (so we -% don't have to count |\exp_after:wN|s and then stop it again when we -% want to. -% \begin{macrocode} - \toks_put_right:Nx\l_TP_KV_assignments_toks { - \exp_not:n{\tl_set:Nf #1} { \toks_use:N \g_TP_multiselection_toks} - } - } - { - \cs_set_nopar:Npn #1{##1} % setting it? - \toks_put_right:Nn \l_TP_KV_assignments_toks - { \tl_set:Nn #1{##1} } - } - } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_multiselection:nnnn} -% Start the |\if_case:w|. When the item is retrieved using an |f| -% type expansion we better stop it at the right place once we have -% emerged on the other side of the conditional. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_multiselection:nnnn #1#2#3#4{ - \toks_gset:Nn \g_TP_multiselection_toks {\if_case:w #2} - \clist_map_inline:nn {#3}{ - \TP_multiselection_add_or_case:n {\exp_stop_f:##1} - } - \toks_gput_right:Nn\g_TP_multiselection_toks { - \else: \use_i_after_fi:nw { \exp_stop_f: #4} \fi: - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% -% -% -% -% \begin{macro}{\DeclareInstance} -% |{type}{instname}{templatename}{keyval}| -% \begin{macrocode} -\cs_new_nopar:Npn \DeclareInstance { \DeclareCollectionInstance{} } -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\DeclareCollectionInstance} -% |{collection}{type}{instname}{templatename}{keyval}| -% The fifth argument is picked up implicitly. -% \begin{macrocode} -\cs_new:Npn \DeclareCollectionInstance#1#2#3#4{ - \TP_declare_instance:cnn { <#1>#2/#3 }{ #2/#4 } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\UseCollection} -% |{type}{collection}| -% \begin{macrocode} -\cs_new_nopar:Npn \UseCollection#1#2{ - \tl_set:cx { TP@<#1> } - { {#2} \TP_get_arg_count:n{#1} } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_let_instance:Nnn} -% |\internalcommand{type}{instname}| -% -% The way this macro is used, it must result in |\cs_set_eq:NwN| |<csname1>| -% |<csname2>| after exactly two expansions as it is used this way -% in |\TP_templdecl_eval_i_key_value:nnn|! -% \begin{macrocode} -\cs_new_nopar:Npn \TP_let_instance:Nnn#1#2#3{ - \cs_set_eq:Nc #1 - { - \cs_if_free:cTF { \TP_get_csname_prefix:n{#2} #3 } - { <>#2/ } - { \TP_get_csname_prefix:n{#2} } - #3 - } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\UseInstance} -% |{type}{instname}| -% \begin{macrocode} -\cs_new_nopar:Npn \UseInstance#1#2{ - \TP_let_instance:Nnn \l_tmpa_tl {#1}{#2} - \tl_if_eq:NNTF \l_tmpa_tl \scan_stop: - \INSTANCEundefined - \l_tmpa_tl -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_declare_tmp_instance:nnnn} -% This macro is called when we have seen a |\UseTemplate| -% declaration as part of an |i| key value. Therefore the -% first argument will be dropped (it contains the token -% |\UseTemplate|) the second and third will be combined to refer to -% the template and the fourth argument will be implictly picked up -% by |\TP_declare_instance:Nnn|. -% \begin{macrocode} -\cs_new:Npn \TP_templdecl_declare_tmp_instance:nnnn#1#2#3{% - \TP_declare_instance:Nnn \g_tmpa_tl {#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} -\cs_new_nopar:Npn \ShowTemplate#1#2{ - \iow_term:x{*******~ Template:~ #1/#2~ *******} - \iow_term:x{*} - \iow_term:x{*~ Defaults:} - \iow_term:x{*} - \iow_term:x{\token_to_str:N\TPD>/#1/#2= - \cs_meaning:c{TPD>/#1/#2}} - \iow_term:x{*} - \iow_term:x{*~ Restrictions:} - \iow_term:x{*} - \iow_term:x{\token_to_str:N\TPR>/#1/#2= - \cs_meaning:c{TPR>/#1/#2}} - \iow_term:x{*} - \iow_term:x{*~ Body:} - \iow_term:x{*} - \cs_show:c {TP>/#1/#2}} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\ShowCollectionInstance} -% \begin{macrocode} -\cs_new_nopar:Npn \ShowCollectionInstance#1#2#3{ - \iow_term:x{*******~ Instance:~ <#1>#2/#3~ *******} - \iow_term:x{*} - \cs_show:c {<#1>#2/#3}} -\cs_new_nopar:Npn \ShowInstance{\ShowCollectionInstance{}} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_templdecl_setup_fakeregister_key:NNn} -% |{setcomand}{privateregister}{key}{internalcode}| -% \begin{macrocode} -\cs_new_nopar:Npn \TP_templdecl_setup_fakeregister_key:NNn#1#2#3{ - \TP_templdecl_define_key:n{ - \tl_if_head_eq_meaning:nNTF{##1..}\DelayEvaluation - { -% \end{macrocode} -% In the v0.08 version of \texttt{template.dtx} a -% |\DelayEvaluation| for a faked register would simply be equiv to -% a |\cs_set_nopar:Npn | (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 -% |\cs_set_nopar:Npn |\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} -% \toks_put_right:Nn \l_TP_KV_assignments_toks {\cs_set_nopar:Npn #3{##1}} -% \toks_put_right:Nn \l_TP_KV_assignments_toks -% {#1#2{##1}\cs_set_nopar:Npx #3{\toks_use:N#2}} - \toks_set:No \l_tmpa_toks {\use_ii:nn ##1} - \toks_put_right:Nx \l_TP_KV_assignments_toks { - \exp_not:n{#1#2}{\toks_use:N \l_tmpa_toks} - \exp_not:n{ \cs_set_nopar:Npx #3{\toks_use:N#2} } - - } - } -% \end{macrocode} -% -% -% Otherwise same game for fake registers except that instead of -% passing the register to |\TP_multiselection_add:nnnnnn| 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} - { - \tl_if_head_eq_meaning:nNTF{##1..}\MultiSelection - { - \group_begin: - \TP_multiselection_add:nnnnnn#1#2##1 - \group_end: - \toks_put_right:Nx\l_TP_KV_assignments_toks - {\exp_not:n{\cs_set_nopar:Npn #3} {\toks_use:N\g_TP_multiselection_toks}} - } - { - #1#2{##1} - \toks_put_right:Nx\l_TP_KV_assignments_toks - {\exp_not:n{\cs_set_nopar:Npn#3} {\toks_use:N#2}} - } - } - } -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\g_TP_multiselection_toks} -% \begin{macrocode} -\toks_new:N \g_TP_multiselection_toks -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TP_multiselection_add:nnnnnn} -% \marg{operation} \marg{register} |\MultiSelection| -% \marg{selector} \marg{case-list} \marg{else-case} -% -% This command builds up the |\if_case:w| code from the three -% arguments of |\MultiSelection| and stores it in -% |\g_TP_multiselection_toks|. This code is supposed to be run in a -% group so a) we don't have to initialise |\g_TP_multiselection_toks| -% and b) all changes to the used registers not affecting the -% outside. -% -% \begin{macrocode} -\cs_new_nopar:Npn \TP_multiselection_add:nnnnnn #1#2#3#4#5#6{ - \toks_gset:Nn \g_TP_multiselection_toks {\if_case:w #4} - \clist_map_inline:nn {#5}{ - \tl_if_head_eq_meaning:nNTF{##1..}\DelayEvaluation - { - \TP_multiselection_add_or_case:n {##1} - } - { - #1#2{##1} - \TP_multiselection_add_or_case:o { \toks_use:N #2 } - } - } - \toks_gput_right:Nn \g_TP_multiselection_toks { - \else: \use_i_after_fi:nw{#6}\fi: - } -} -% \end{macrocode} -% -% \end{macro} -% -% \begin{macro}{\TP_multiselection_add_or_case:o} -% No need to worry about where |\or:| is allowed to be added since -% all loops in \LaTeX3 process the item outside conditionals. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_multiselection_add_or_case:n #1 { - \toks_gput_right:Nn \g_TP_multiselection_toks { - \or: \use_i_after_orelse:nw{#1} - } -} -\cs_generate_variant:Nn \TP_multiselection_add_or_case:n {o} -% \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 -% |\TP_templdecl_setup_f_key:nnN| 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_templdecl_parse_KV:nnw| now calls -% |\TP_templdecl_setup_n_key:nN| for the `n' key. looks like -% this thus be fixed some time soon -% -% -% -% -% -% -% -% \begin{macro}{\IfExistsInstanceTF} -% tests that there is a \emph{default} definition -% taken from xinitials.dtx: -% \begin{macrocode} -\cs_new_nopar:Npn \IfExistsInstanceTF#1#2{ - \cs_if_exist:cTF{<>#1/#2} -} -% \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} -\cs_set_nopar:Npn \IfExistsInstanceTF#1#2{ - \TP_let_instance:Nnn \l_tmpa_tl {#1}{#2} -% next is not \tl_if_eq:NNTF but ...FT so done manually - \if_meaning:w\l_tmpa_tl\scan_stop: - \exp_after:wN\use_ii:nn - \else: - \exp_after:wN\use_i:nn - \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} -\cs_new_nopar:Npn \DeclareRestrictedTemplate#1#2#3#4{ - % CCC do we need a group here?? - \tl_set_eq:cc { TPD>/#1/#2 } { TPD>/#1/#3 } - \tl_set_eq:cc { TP>/#1/#2 } { TP>/#1/#3 } - \toks_set:Nv \l_TP_KV_assignments_toks { TPR>/ #1 / #3 } -% adds stuff to \l_TP_KV_assignments_toks - \setkeys {\cs:w TPO>/#1/#3\cs_end:}{#4} - - \tl_set:cx { TPR>/#1/#2 } - { \toks_use:N \l_TP_KV_assignments_toks } - \cs_if_free:cTF { TPO>/#1/#3 } - { \tl_set:cn {TPO>/#1/#2}{#1/#3} } - { \tl_set_eq:cc {TPO>/#1/#2}{TPO>/#1/#3} } -} -% \end{macrocode} -% \end{macro} -% -% -% Internals: -% -% \begin{macro}{\TP_instdecl_generate_assignments:nn} -% These could probably be inlined, even when they do something! -% -% Assumption: setkeys fully expands its first argument. -% -% \begin{macrocode} -\cs_new_nopar:Npn \TP_instdecl_generate_assignments:nn#1#2 { - % Returns to \l_TP_KV_assignments_toks - % the restrictions - % stored in the TP-structure (at present - % in YAM) of the template #1 - \exp_args:NNo \toks_set:No \l_TP_default_assignments_toks - {\cs:w TPD>/#1\cs_end:\scan_stop:\scan_stop:} - \toks_set:Nv \l_TP_KV_assignments_toks { TPR>/ #1 } - \setkeys { \cs:w TPO>/#1 \cs_end: } - { #2 } % adds stuff to \l_TP_KV_assignments_toks - -% prepends stuff to \l_TP_KV_assignments_toks : - \exp_after:wN\TP_instdecl_add_default_recurse:nn - \toks_use:N\l_TP_default_assignments_toks - -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TP_instdecl_add_default_recurse:nn} -% [ 2001/06/10 Think about doing this properly with explicit plists! --- but -% this means that one has to think about whether or not plists should be -% implemented as token registers and not as tl vars as they are now. ] -% \begin{macrocode} -\cs_new_nopar:Npn \TP_instdecl_add_default_recurse:nn#1#2{ - \token_if_eq_meaning:NNF #1\scan_stop: - { - \l_tmpa_toks{#2} - \tl_set:Nx \l_tmpa_tl { - {\toks_use:N \l_tmpa_toks \toks_use:N \l_TP_KV_assignments_toks} - } - \l_TP_KV_assignments_toks \l_tmpa_tl - \TP_instdecl_add_default_recurse:nn - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% |TPD>/type/name| stores the default parameter assignments. -% -% |TPR>/type/name| stores the parameter assignments that have been -% made for a restricted template otherwise it is undefined (or |\scan_stop:|). -% -% -% |TPO>/type/name| stores the full name (i.e. as |type/name|) -% of the template a restricted -% template is coming from originally. -% -% -% -% -% \begin{macro}{\TP_split_finite_skip_value:nnNN} -% This macro is for use in error checking template values like -% "text-float-sep" that can't contain infinite glue and needs the -% shrink and/or stretch components. First argument is the skip -% register (which is likely to be user input), second is a template -% key name, and the last two are the \meta{dimen} registers that -% stores the stretch and shrink components. Assignments are global. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_split_finite_skip_value:nnNN #1#2{ - \skip_split_finite_else_action:nnNN {#1} { - \PackageError{template}{Value~ for~ key~ #2~ contains~ `fil(ll)'} - {Only~ finite~ minus~ or~ plus~ parts~ are~ allowed~ for~ this~ key.} - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% \begin{macrocode} -%</package> -% \end{macrocode} -% -% \Finale -% diff --git a/Master/texmf-dist/source/latex/xpackages/xbase/xbase.ins b/Master/texmf-dist/source/latex/xpackages/xbase/xbase.ins deleted file mode 100644 index aef2755ba99..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xbase/xbase.ins +++ /dev/null @@ -1,74 +0,0 @@ -% \iffalse -%% -%% This file will generate fast loadable files and documentation -%% driver files from the dtx files in this package when run through -%% LaTeX or TeX. -%% -%% (C) Copyright 2000-2009 LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%% -%% This file is part of the ``xbase bundle'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -%% $Id: xbase.ins 1650 2009-10-30 22:34:24Z joseph $ -%% -% \fi -% - -\input docstrip -\keepsilent -\askforoverwritefalse - -\preamble - -(C) Copyright The LaTeX3 Project and any individual authors -listed elsewhere in this file. - -This is a generated file. - -This file was generated from file(s) of the xbase bundle. ---------------------------------------------------------- - -This file may only be distributed together with a copy of this bundle. -You may however distribute the bundle without such generated files. - -====================================================================== - -\endpreamble - - -\generate{% - \file{ldcsetup.sty}{\from{ldcsetup.dtx}{package}} - \file{template.sty}{\from{template.dtx}{package,trace}} - \file{xtemplate.sty}{\from{xtemplate.dtx}{package}} - \file{xparse.sty}{\from{xparse.dtx}{package}} -} - -\endbatchfile diff --git a/Master/texmf-dist/source/latex/xpackages/xbase/xparse.dtx b/Master/texmf-dist/source/latex/xpackages/xbase/xparse.dtx deleted file mode 100644 index 1a90d4891f4..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xbase/xparse.dtx +++ /dev/null @@ -1,2985 +0,0 @@ -% \iffalse -%% File: xparse.dtx (C) Copyright 1999 Frank Mittelbach, Chris Rowley, -%% David Carlisle -%% (C) Copyright 2004-2008 Frank Mittelbach, -%% LaTeX3 Project -%% (C) Copyright 2009-2010 LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%% -%% This file is part of the ``xbase bundle'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -% -%<*driver|package> -\RequirePackage{l3names} -%</driver|package> -%\fi -\GetIdInfo$Id: xparse.dtx 2219 2011-04-08 21:07:45Z joseph $ - {Generic document command parser} -%\iffalse -%<*driver> -%\fi -\ProvidesFile{\filename.\filenameext} - [\filedate\space v\fileversion\space\filedescription] -%\iffalse -\documentclass{l3doc} -\usepackage{amstext} -\begin{document} - \DocInput{xparse.dtx} -\end{document} -%</driver> -% \fi -% -% \title{The \textsf{xparse} package\thanks{This file -% has version number \fileversion, last -% revised \filedate.}\\ -% Generic document command parser} -% \author{\Team} -% \date{\filedate} -% \maketitle -% -%\begin{documentation} -% -%\section{Creating document commands} -% -% The \pkg{xparse} package provides a high-level interface for -% producing document-level commands. In that way, it is intended as -% a replacement for the \LaTeXe\ \cs{newcommand} macro. However, -% \pkg{xparse} works so that the interface to a function (optional -% arguments, stars and mandatory arguments, for example) is separate -% from the internal implementation. \pkg{xparse} provides a normalised -% input for the internal form of a function, independent of the -% document-level argument arrangement. -% -% At present, the functions in \pkg{xparse} which are regarded as -% `stable' are: -%\begin{itemize} -% \item \cs{DeclareDocumentCommand} -% \item \cs{NewDocumentCommand} -% \item \cs{RenewDocumentCommand} -% \item \cs{ProvideDocumentCommand} -% \item \cs{DeclareDocumentEnvironment} -% \item \cs{NewDocumentEnvironment} -% \item \cs{RenewDocumentEnvironment} -% \item \cs{ProvideDocumentEnvironment} -% \item \cs{IfNoValue(TF)} (the need for \cs{IfValue(TF)} is currently -% an item of active discussion) -% \item \cs{IfBoolean(TF)} -%\end{itemize} -% with the other functions currently regarded as `experimental'. Please -% try all of the commands provided here, but be aware that the -% experimental ones may change or disappear. -% -%\subsection{Specifying arguments} -% -% Before introducing the functions used to create document commands, -% the method for specifying arguments with \pkg{xparse} will be -% illustrated. In order to allow each argument to be defined -% independently, \pkg{xparse} does not simply need to know the -% number of arguments for a function, but also the nature of each -% one. This is done by constructing an \emph{argument specification}, -% which defines the number of arguments, the type of each argument -% and any additional information needed for \pkg{xparse} to read the -% user input and properly pass it through to internal functions. -% -% The basic form of the argument specifier is a list of letters, where -% each letter defines a type of argument. As will be described below, -% some of the types need additional information, such as default values. -% The argument types can be divided into two, those which define -% arguments that are mandatory (potentially raising an error if not -% found) and those which define optional arguments. The mandatory types -% are: -%\begin{itemize}[font=\ttfamily] -% \item[m] A standard mandatory argument, which can either be a single -% token alone or multiple tokens surrounded by curly braces. -% Regardless of the input, the argument will be passed to the -% internal code surrounded by a brace pair. This is the \pkg{xparse} -% type specifier for a normal \TeX\ argument. -% \item[l] An argument which reads everything up to the first -% open group token: in standard \LaTeX\ this is a left brace. -% \item[u] Reads an argument `until' \meta{tokens} are encountered, -% where the desired \meta{tokens} are given as an argument to the -% specifier: \texttt{u}\marg{tokens}. -%\end{itemize} -% The types which define optional arguments are: -%\begin{itemize}[font=\ttfamily] -% \item[o] A standard \LaTeX\ optional argument, surrounded with square -% brackets, which will supply -% the special \cs{NoValue} token if not given (as described later). -% \item[d] An optional argument which is delimited by \meta{token1} -% and \meta{token2}, which are given as arguments: -% \texttt{d}\meta{token1}\meta{token2}. As with \texttt{o}, if no -% value is given the special token \cs{NoValue} is returned. -% \item[O] As for \texttt{o}, but returns \meta{default} if no -% value is given. Should be given as \texttt{O}\marg{default}. -% \item[D] As for \texttt{d}, but returns \meta{default} if no -% value is given: \texttt{D}\meta{token1}\meta{token2}\marg{default}. -% Internally, the \texttt{o}, \texttt{d} and \texttt{O} types are -% short-cuts to an appropriated-constructed \texttt{D} type argument. -% \item[s] An optional star, which will result in a value -% \cs{BooleanTrue} if a star is present and \cs{BooleanFalse} -% otherwise (as described later). -% \item[t] An optional \meta{token}, which will result in a value -% \cs{BooleanTrue} if \meta{token} is present and \cs{BooleanFalse} -% otherwise. Given as \texttt{t}\meta{token}. -% \item[g] An optional argument given inside a pair of \TeX\ group -% tokens (in standard \LaTeX, |{| \ldots |}|), which returns -% \cs{NoValue} if not present. -% \item[G] As for \texttt{g} but returns \meta{default} if no value -% is given: \texttt{G}\marg{default}. -%\end{itemize} -% -% Using these specifiers, it is possible to create complex input syntax -% very easily. For example, given the argument definition -% `|s o o m O{default}|', the input `|*[Foo]{Bar}|' would be parsed as: -%\begin{itemize}[nolistsep] -% \item |#1| = |\BooleanTrue| -% \item |#2| = |{Foo}| -% \item |#3| = |\NoValue| -% \item |#4| = |{Bar}| -% \item |#5| = |{default}| -%\end{itemize} -% whereas `|[One][Two]{}[Three]|' would be parsed as: -%\begin{itemize}[nolistsep] -% \item |#1| = |\BooleanFalse| -% \item |#2| = |{One}| -% \item |#3| = |{Two}| -% \item |#4| = |{}| -% \item |#5| = |{Three}| -%\end{itemize} -% Note that after parsing the input there will be always exactly the -% same number of \meta{balanced text} arguments as the number of letters -% in the argument specifier. The \cs{BooleanTrue} and \cs{BooleanFalse} -% tokens are passed without braces; all other arguments are passed as -% brace groups. -% -% Two more tokens have a special meaning when creating an argument -% specifier. First, \texttt{+} is used to make an argument long (to -% accept paragraph tokens). In contrast to \LaTeXe's \cs{newcommand}, -% this applies on an argument-by-argument basis. So modifying the -% example to `|s o o +m O{default}|' means that the mandatory argument -% is now \cs{long}, whereas the optional arguments are not. -% -% Secondly, the token \texttt{>} is used to declare so-called -% `argument processors', which can be used to modify the contents of an -% argument before it is passed to the macro definition. The use of -% argument processors is a somewhat advanced topic, (or at least a less -% commonly used feature) and is covered in Section~\ref{sec:processors}. -% -%\subsection{Spacing and optional arguments} -% -% TeX will find the first argument after a function name irrespective -% of any intervening spaces. This is true for both mandatory and -% optional arguments. So "\foo[arg]" and \verb*"\foo [arg]" are -% equivalent. Spaces are also ignored when collecting arguments up -% to the last mandatory argument to be collected (as it must exist). -% So after -%\begin{verbatim} -% \DeclareDocumentCommand \foo { m o m } { ... } -%\end{verbatim} -% the user input "\foo{arg1}[arg2]{arg3}" and -% \verb*"\foo{arg1} [arg2] {arg3}" will both be parsed in the same -% way. However, spaces are \emph{not} ignored when parsing optional -% arguments after the last mandatory argument. Thus with -%\begin{verbatim} -% \DeclareDocumentCommand \foo { m o } { ... } -%\end{verbatim} -% "\foo{arg1}[arg2]" will find an optional argument but -% \verb*"\foo{arg1} [arg2]" will not. This is so that trailing optional -% arguments are not picked up `by accident' in input. -% -%\subsection{Declaring commands and environments} -% -% With the concept of an argument specifier defined, it is now -% possible to describe the methods available for creating both -% functions and environments using \pkg{xparse}. -% -% The interface-building commands are the preferred method for -% creating document-level functions in \LaTeX3. All of the functions -% generated in this way are naturally robust (using the \eTeX\ -% \cs{protected} mechanism). -% -%\begin{function}{ -% \DeclareDocumentCommand| -% \NewDocumentCommand| -% \RenewDocumentCommand| -% \ProvideDocumentCommand -%} -% \begin{syntax} -% "\DeclareDocumentCommand" <function> \Arg{arg spec} \Arg{code} -% \end{syntax} -% This family of commands are used to create a document-level -% <function>. The argument specification for the function is -% given by <arg spec>, and the function will execute <code>. -% -% As an example: -% \begin{verbatim} -% \DeclareDocumentCommand \chapter { s o m } { -% \IfBooleanTF {#1} { -% \typesetnormalchapter {#2} {#3} -% }{ -% \typesetstarchapter {#3} -% } -% } -% \end{verbatim} -% would be a way to define a \cs{chapter} command which would -% essentially behave like the current \LaTeXe\ command (except that it -% would accept an optional argument even when a \texttt{*} was parsed). -% The \cs{typesetnormalchapter} could test its first argument for being -% \cs{NoValue} to see if an optional argument was present. -% -% The difference between the \cs{Declare\ldots}, \cs{New\ldots} -% \cs{Renew\ldots} and \cs{Provide\ldots} versions is the behaviour -% if <function> is already defined. -% \begin{itemize} -% \item \cs{DeclareDocumentCommand} will always create the new -% definition, irrespective of any existing <function> with the -% same name. -% \item \cs{NewDocumentCommand} will issue an error if <function> -% has already been defined. -% \item \cs{RenewDocumentCommand} will issue an error if <function> -% has not previously been defined. -% \item \cs{ProvideDocumentCommand} creates a new definition for -% <function> only if one has not already been given. -% \end{itemize} -% -% \begin{texnote} -% Unlike \LaTeXe's \cs{newcommand} and relatives, the -% \cs{DeclareDocumentCommand} function do not prevent creation of -% functions with names starting \cs{end\ldots}. -% \end{texnote} -%\end{function} -% -%\begin{function}{% -% \DeclareDocumentEnvironment| -% \NewDocumentEnvironment| -% \RenewDocumentEnvironment| -% \ProvideDocumentEnvironment -%} -% \begin{syntax} -% "\DeclareDocumentEnvironment" \Arg{environment} \Arg{arg spec} -% ~~~~\Arg{start code} \Arg{end code} -% \end{syntax} -% These commands work in the same way as \cs{DeclareDocumentCommand}, -% etc., but create environments (\cs{begin}|{|<function>|}| \ldots -% \cs{end}|{|<function>|}|). Both the <start code> and <end code> -% may access the arguments as defined by <arg spec>. -% -% \begin{texnote} -% When loaded as part of a \LaTeX3 format, these, these commands do -% not create a pair of macros \cs{<environment>} and -% \cs{end<environment>}. Thus \LaTeX3 environments have to be -% accessed using the \cs{begin} \ldots \cs{end} mechanism. When -% \pkg{xparse} is loaded as a \LaTeXe\ package, \cs{<environment>} -% and \cs{end<environment>} are defined, as this is necessary to -% allow the new environment to work! -% \end{texnote} -%\end{function} -% -%\subsection{Testing special values} -% -% Optional arguments created using \pkg{xparse} make use of dedicated -% variables to return information about the nature of the argument -% received. -% -%\begin{variable}{\NoValue} -% \cs{NoValue} is a special marker returned by \pkg{xparse} if no -% value is given for an optional argument. If typeset (which should -% not happen), it will print the value \texttt{-NoValue-}. -%\end{variable} -% -%\begin{function}{\IfNoValue / (TF) (EXP)} -% \begin{syntax} -% "\IfNoValueTF" \Arg{argument} \Arg{true code} \Arg{false code} -% \end{syntax} -% The \cs{IfNoValue} tests are used to check if <argument> (|#1|, -% |#2|, etc.) is the special \cs{NoValue} token. For example -% \begin{verbatim} -% \DeclareDocumentCommand \foo { o m } { -% \IfNoValueTF {#1} { -% \DoSomethingJustWithMandatoryArgument {#2} -% }{ -% \DoSomethingWithBothArguments {#1} {#2} -% } -% } -% \end{verbatim} -% will use a different internal function if the optional argument -% is given than if it is not present. -% -% As the \cs{IfNoValue(TF)} tests are expandable, it is possible to -% test these values later, for example at the point of typesetting or -% in an expansion context. -%\end{function} -% -%\begin{function}{\IfValue / (TF) (EXP)} -% \begin{syntax} -% "\IfValueTF" \Arg{argument} \Arg{true code} \Arg{false code} -% \end{syntax} -% The reverse form of the \cs{IfNoValue(TF)} tests are also available -% as \cs{IfValue(TF)}. The context will determine which logical -% form makes the most sense for a given code scenario. -%\end{function} -% -%\begin{variable}{ -% \BooleanFalse| -% \BooleanTrue -%} -% The \texttt{true} and \texttt{false} flags set when searching for -% an optional token (using \texttt{s} or \texttt{t}<token>) have -% names which are accessible outside of code blocks. -%\end{variable} -% -%\begin{function}{\IfBoolean / (TF) (EXP)} -% \begin{syntax} -% "\IfBooleanTF" <argument> \Arg{true code} \Arg{false code} -% \end{syntax} -% Used to test if <argument> (|#1|, |#2|, etc.) is \cs{BooleanTrue} -% or \cs{BooleanFalse}. For example -% \begin{verbatim} -% \DeclareDocumentCommand \foo { s m } { -% \IfBooleanTF #1 { -% \DoSomethingWithStar {#2} -% }{ -% \DoSomethingWithoutStar {#2} -% } -% } -% \end{verbatim} -% checks for a star as the first argument, then chooses the action to -% take based on this information. -%\end{function} -% -%\subsection{Argument processors} -%\label{sec:processors} -% -% \pkg{xparse} introduces the idea of an argument processor, which is -% applied to an argument \emph{after} it has been grabbed by the -% underlying system but before it is passed to \meta{code}. An argument -% processor can therefore be used to regularise input at an early stage, -% allowing the internal functions to be completely independent of input -% form. Processors are applied to user input and to default values for -% optional arguments, but \emph{not} to the special \cs{NoValue} marker. -% -% Each argument processor is specified by the syntax -% \texttt{>}\marg{processor} in the argument specification. Processors -% are applied from right to left, so that -%\begin{verbatim} -% >{\ProcessorB} >{\ProcessorA} m -%\end{verbatim} -% would apply \cs{ProcessorA} -% followed by \cs{ProcessorB} to the tokens grabbed by the \texttt{m} -% argument. -% -%\begin{variable}{\ProcessedArgument} -% \pkg{xparse} defines a very small set of processor functions. In the -% main, it is anticipated that code writers will want to create their -% own processors. These need to accept one argument, which is the -% tokens as grabbed (or as returned by a previous processor function). -% Processor functions should return the processed argument as the -% variable \cs{ProcessedArgument}. -%\end{variable} -% -%\begin{function}{\xparse_process_to_str:n} -% \begin{syntax} -% "\xparse_process_to_str:n" \Arg{grabbed argument} -% \end{syntax} -% The \cs{xparse_process_to_str:n} processor applies the \LaTeX3 -% \cs{tl_to_str:n} function to the <grabbed argument>. For example -% \begin{verbatim} -% \DeclareDocumentCommand \foo { >{\xparse_arg_to_str:n} m } { -% #1 % Which is now detokenized -% } -% \end{verbatim} -%\end{function} -% -%\begin{function}{ \ReverseBoolean } -% \begin{syntax} -% \cs{ReverseBoolean} -% \end{syntax} -% This processor reverses the logic of \cs{BooleanTrue} and -% \cs{BooleanFalse}, so that the the example from earlier would become -% \begin{verbatim} -% \DeclareDocumentCommand \foo { > { \ReverseBoolean } s m } { -% \IfBooleanTF #1 -% { \DoSomethingWithoutStar {#2} } -% { \DoSomethingWithStar {#2} } -% } -% \end{verbatim} -%\end{function} -% -%\begin{function}{ \SplitArgument } -% \begin{syntax} -% \cs{SplitArgument} \Arg{number} \Arg{token} -% \end{syntax} -% This processor splits the argument given at each occurrence of the -% \meta{token} up to a maximum of \meta{number} tokens (thus -% dividing the input into \( \text{\meta{number}} + 1 \) parts). -% An error is given if too many \meta{tokens} are present in the -% input. The processed input is places inside -% \( \text{\meta{number}} + 1 \) sets of braces for further use. -% If there are less than \Arg{number} of \Arg{tokens} in the argument -% then empty brace groups are added at the end of the processed -% argument. -% \begin{verbatim} -% \DeclareDocumentCommand \foo -% { > { \SplitArgument { 2 } { ; } } m } -% { \InternalFunctionOfThreeArguments #1 } -% \end{verbatim} -% Any category code \( 13 \) (active) \meta{tokens} will be replaced -% before the split takes place. -%\end{function} -% -%\begin{function}{ \SplitList } -% \begin{syntax} -% \cs{SplitList} \Arg{token} -% \end{syntax} -% This processor splits the argument given at each occurrence of the -% \meta{token} where the number of items is not fixed. Each item is -% then wrapped in braces within "#1". The result is that the -% processed argument can be further processed using a mapping function. -% \begin{verbatim} -% \DeclareDocumentCommand \foo -% { > { \SplitList { ; } } m } -% { \MappingFunction #1 } -% \end{verbatim} -% Any category code \( 13 \) (active) \meta{tokens} will be replaced -% before the split takes place. -%\end{function} -% -%\subsection{Separating interface and implementation} -% -% One \emph{experimental} idea implemented in \pkg{xparse} is to -% separate out document command interfaces (the argument specification) -% from the implementation (code). This is carried out using a -% pair of functions, \cs{DeclareDocumentCommandInterface} and -% \cs{DeclareDocumentCommandImplementation} -% -%\begin{function}{\DeclareDocumentCommandInterface} -% \begin{syntax} -% "\DeclareDocumentCommandInterface" <function> -% ~~~~\Arg{implementation} \Arg{arg spec} -% \end{syntax} -% This declares a <function>, which will take arguments as detailed -% in the <arg spec>. When executed, the <function> will look for -% code stored as an <implementation>. -%\end{function} -% -%\begin{function}{\DeclareDocumentCommandImplementation} -% \begin{syntax} -% "\DeclareDocumentCommandImplementation" -% ~~~~\Arg{implementation} <args> \Arg{code} -% \end{syntax} -% Declares the <implementation> for a function to accept <args> -% arguments and expand to <code>. An implementation must take the -% same number of arguments as a linked interface, although this is not -% enforced by the code. -%\end{function} -% -%\subsection{Fully-expandable document commands} -% -% There are \emph{very rare} occasion when it may be useful to create -% functions using a fully-expandable argument grabber. To support this, -% \pkg{xparse} can create expandable functions as well as the usual -% robust ones. This imposes a number of restrictions on the nature of -% the arguments accepted by a function, and the code it implements. -% This facility should only be used when \emph{absolutely necessary}; -% if you do not understand when this might be, \emph{do not use these -% functions}! -% -%\begin{function}{\DeclareExpandableDocumentCommand} -% \begin{syntax} -% "\DeclareExpandableDocumentCommand" -% ~~~~<function> \Arg{arg spec} \Arg{code} -% \end{syntax} -% This command is used to create a document-level <function>, -% which will grab its arguments in a fully-expandable manner. The -% argument specification for the function is given by <arg spec>, -% and the function will execute <code>. In general, <code> will -% also be fully expandable, although it is possible that this will -% not be the case (for example, a function for use in a table might -% expand so that \cs{omit} is the first non-expandable token). -% -% Parsing arguments expandably imposes a number of restrictions on -% both the type of arguments that can be read and the error checking -% available: -% \begin{itemize} -% \item The function must have at least one mandatory argument, and -% in particular the last argument must be one of the mandatory -% types (\texttt{l}, \texttt{m} or \texttt{u}). -% \item All arguments are either short or long: it is not possible -% to mix short and long argument types. -% \item The `optional group' argument types \texttt{g} and -% \texttt{G} are not available. -% \item It is not possible to differentiate between, for example -% |\foo[| and |\foo{[}|: in both cases the \texttt{[} will be -% interpreted as the start of an optional argument. As a result -% result, checking for optional arguments is less robust than -% in the standard version. -% \end{itemize} -% \pkg{xparse} will issue an error if an argument specifier is given -% which does not conform to the first three requirements. The last -% item is an issue when the function is used, and so is beyond the -% scope of \pkg{xparse} itself. -%\end{function} -% -%\subsection{Access to the argument specification} -% -% The argument specifications for document commands and environments are -% available for examination and use. -% -%\begin{function}{ -% \GetDocumentCommandArgSpec | -% \GetDocumentEnvironmentArgSpec | -%} -% \begin{syntax} -% \cs{GetDocumentCommandArgSpec} \meta{function} -% \cs{GetDocumentEnvironmentArgSpec} \meta{environment} -% \end{syntax} -% These functions transfer the current argument specification for the -% requested \meta{function} or \meta{environment} into the token list -% variable \cs{ArgumentSpecification}. If the \meta{function} or -% \meta{environment} has no known argument specification then an error -% is issued. The assignment to \cs{ArgumentSpecification} is local to -% the current \TeX\ group. -%\end{function} -% -%\begin{function}{ -% \ShowDocumentCommandArgSpec | -% \ShowDocumentEnvironmentArgSpec | -%} -% \begin{syntax} -% \cs{ShowDocumentCommandArgSpec} \meta{function} -% \cs{ShowDocumentEnvironmentArgSpec} \meta{environment} -% \end{syntax} -% These functions show the current argument specification for the -% requested \meta{function} or \meta{environment} at the terminal. If -% the \meta{function} or \meta{environment} has no known argument -% specification then an error is issued. -%\end{function} -% -%\end{documentation} -% -%\begin{implementation} -% -%\subsection{Variables and constants} -% -%\begin{variable}{\c_xparse_shorthands_prop} -% Shorthands and replacement text: set up at the start of the package, -% and not be be altered later! -%\end{variable} -% -%\begin{variable}{\l_xparse_arg_tl} -% Variable used as internal representation of -% \cs{ProcessedArgument}. Unlike the later, this register should not -% be used directly when creating new processors. -%\end{variable} -% -%\begin{variable}{\l_xparse_args_tl} -% Token list variable for arguments as they are picked up for passing -% on to user functions. -%\end{variable} -% -%\begin{variable}{\l_xparse_environment_args_tl} -% Token list register to pass arguments to the end of an environment -% from the beginning. -%\end{variable} -% -%\begin{variable}{\l_xparse_environment_bool} -% When creating functions, a short cut can be taken if all of the -% arguments are of \texttt{m} type. The code for environments cannot -% do that, and so a flag is needed. -%\end{variable} -% -%\begin{variable}{\l_xparse_error_bool} -% For flagging up errors when making expandable commands. -%\end{variable} -% -%\begin{variable}{\l_xparse_function_tl} -% Needed to pass along the function name when creating in an expandable -% manner. This is needed as a series of functions have to be created -% when making expandable functions. (In contrast, standard robust -% functions need at most two functions.) -%\end{variable} -% -%\begin{variable}{\l_xparse_last_arg_tl} -% The last argument type added. As this must be mandatory when creating -% expandable commands, this variable is needed to enforce this -% behaviour. -%\end{variable} -% -%\begin{variable}{\l_xparse_long_bool} -% Flag used to indicate creation of \cs{long} arguments. -%\end{variable} -% -%\begin{variable}{\l_xparse_m_args_int} -% Used to enumerate the \texttt{m} arguments with no modifications -% (i.e., neither long nor processed after grabbing). -%\end{variable} -% -%\begin{variable}{\l_xparse_m_only_bool} -% Flag used to indicate that all arguments are of type \texttt{m}, -% with no no modifications. -%\end{variable} -% -%\begin{variable}{\l_xparse_mandatory_args_int} -% For counting up all mandatory arguments so that the code can tell -% when optional arguments come after the last mandatory one. Counts -% down again as mandatory arguments are added to the signature, so will -% be zero for any trailing optional arguments. -%\end{variable} -% -%\begin{variable}{\l_xparse_processor_bool} -% When converting an argument specification into a signature there is -% a need to know if there are any argument processors set up. This is -% used to tell if \texttt{m} arguments can simply be counted up or need -% handling on a one-off basis. -%\end{variable} -% -%\begin{variable}{\l_xparse_processor_int} -% Each time a processor is set up in the grabber routine, it is stored -% and the total number of processors is recorded here. Later, the -% variable is counted back down to use the processors in reverse order -% to the collection order. -%\end{variable} -% -%\begin{variable}{\l_xparse_signature_tl} -% For constructing the signature of the function defined. As -% \pkg{xparse} works through an argument specification, grabber -% functions are added to this variable for each argument. -%\end{variable} -% -%\begin{variable}{\l_xparse_tmp_tl} -% Scratch space, used for example to convert shorthand argument types -% into the full versions. -%\end{variable} -% -%\begin{variable}{\l_xparse_total_args_int} -% Used to enumerate the total number of arguments (i.e., the number of -% letters in the argument specification). -%\end{variable} -% -%\subsection{Internal functions} -% -%\begin{function}{ -% \xparse_add_arg:n | -% \xparse_add_arg:V -%} -% \begin{syntax} -% "\xparse_add_arg:n" <grabbed arg> -% \end{syntax} -% Adds <grabbed arg> to the output \pkg{xparse} supplies to the -% defined <code>, applying any post-processing that is needed. -%\end{function} -% -%\begin{function}{ -% \xparse_add_grabber_mandatory:N| -% \xparse_add_grabber_optional:N -%} -% \begin{syntax} -% "\xparse_add_grabber_mandatory:N" <grabber type> -% \end{syntax} -% Adds appropriate grabber for <grabber type> to the signature -% being constructed, making it long if necessary. The -% \texttt{optional} version includes a second check to see if space -% skipping should be on or off. -%\end{function} -% -%\begin{function}{ -% \xparse_add_type_+:w| -% \xparse_add_type_>:w| -% \xparse_add_type_d:w| -% \xparse_add_type_D:w| -% \xparse_add_type_g:w| -% \xparse_add_type_G:w| -% \xparse_add_type_l:w| -% \xparse_add_type_m:w| -% \xparse_add_type_t:w| -% \xparse_add_type_u:w -%} -% \begin{syntax} -% "\xparse_add_type_u:w" -% \end{syntax} -% Carry out necessary processes to add given <type> of argument to -% the signature being constructed. Depending on the argument type -% being added, one or more arguments will be absorbed. -%\end{function} -% -%\begin{function}{\xparse_check_and_add:N} -% \begin{syntax} -% "\xparse_check_and_add:N" <arg spec> -% \end{syntax} -% Ensures that <arg spec> is valid, and if so adds it to the signature -% being constructed. -%\end{function} -% -%\begin{function}{ -% \xparse_count_mandatory:n| -% \xparse_count_mandatory:N -%} -% \begin{syntax} -% "\xparse_count_mandatory:N" <arg spec> -% \end{syntax} -% Used to count how many mandatory arguments an argument specification -% contains. The \texttt{n} function carries out the set up, before -% handing of to the \texttt{N} function. This reads one token, and -% calls the appropriate counter function. -%\end{function} -% -%\begin{function}{ -% \xparse_count_type_>:w| -% \xparse_count_type_+:w| -% \xparse_count_type_d:w| -% \xparse_count_type_D:w| -% \xparse_count_type_g:w| -% \xparse_count_type_G:w| -% \xparse_count_type_l:w| -% \xparse_count_type_m:w| -% \xparse_count_type_t:w| -% \xparse_count_type_u:w| -%} -% \begin{syntax} -% "\xparse_count_type_D:w" -% \end{syntax} -% Used to count up mandatory arguments: one function for each argument -% type so that a simple loop can be used. Only the functions for -% mandatory arguments do any more than call the loop again. -%\end{function} -% -%\begin{function}{\xparse_declare_cmd:Nnn} -% \begin{syntax} -% "\xparse_declare_cmd:Nnn" <function> \Arg{signature} -% ~~~~\Arg{code} -% \end{syntax} -% Declares <function> using <signature> for argument definition and -% <code> as expansion. -% \begin{texnote} -% This is the internal name for \cs{DeclareDocumentCommand}. -% \end{texnote} -%\end{function} -% -%\begin{function}{\xparse_declare_cmd_interface:Nnn} -% \begin{syntax} -% "\xparse_declare_cmd_interface:Nnn" <function> -% ~~~~\Arg{implementation} \Arg{signature} -% \end{syntax} -% Declares <function> using <signature>, which should have code stored -% as <implementation>. -% \begin{texnote} -% This is the internal name for \cs{DeclareDocumentCommandInterface}. -% \end{texnote} -%\end{function} -% -%\begin{function}{\xparse_declare_cmd_implementation:nNn} -% \begin{syntax} -% "\xparse_declare_cmd_implementation:nNn" -% ~~~~\Arg{implementation} <number> \Arg{code} -% \end{syntax} -% Declares <code> taking <number> arguments as an <implementation>, -% to be accessed using an interface defined elsewhere. -% \begin{texnote} -% This is the internal name for -% \cs{DeclareDocumentCommandImplementation}. -% \end{texnote} -%\end{function} -% -%\begin{function}{\xparse_declare_env:nnnn} -% \begin{syntax} -% "\xparse_declare_env:nnnn" \Arg{env} \Arg{arg spec} -% ~~~~\Arg{start code} \Arg{end code} -% \end{syntax} -% Declares <env> as an environment taking <arg spec> arguments -% at \cs{begin}\{<env>\}. The <start code> is executed at the beginning -% of the environment, and the <end code> at the end. Both parts may -% use the arguments defined by <arg spec>. -% \begin{texnote} -% This is the internal name for \cs{DeclareDocumentEnvironment}. -% \end{texnote} -%\end{function} -% -%\begin{function}{\xparse_flush_m_args:} -% \begin{syntax} -% "\xparse_flush_m_args:" -% \end{syntax} -% Adds an outstanding \texttt{m} arguments to the signature. -%\end{function} -% -%\begin{function}{\xparse_grab_arg:w} -% \begin{syntax} -% "\xparse_grab_arg:w" <args> -% \end{syntax} -% Function re-defined each time an argument is grabbed to actually -% do the grabbing. It is this function which will raise an error if -% an argument runs away. -%\end{function} -% -%\begin{function}{ -% \xparse_grab_D:w | -% \xparse_grab_D_long:w | -% \xparse_grab_D_trailing:w | -% \xparse_grab_D_long_trailing:w| -% \xparse_grab_G:w | -% \xparse_grab_G_long:w | -% \xparse_grab_G_trailing:w | -% \xparse_grab_G_long_trailing:w| -% \xparse_grab_l:w | -% \xparse_grab_l_long:w | -% \xparse_grab_m:w | -% \xparse_grab_m_long:w | -% \xparse_grab_m_1:w | -% \xparse_grab_m_2:w | -% \xparse_grab_m_3:w | -% \xparse_grab_m_4:w | -% \xparse_grab_m_5:w | -% \xparse_grab_m_6:w | -% \xparse_grab_m_7:w | -% \xparse_grab_m_8:w | -% \xparse_grab_t:w | -% \xparse_grab_t_long:w | -% \xparse_grab_t_trailing:w | -% \xparse_grab_t_long_trailing:w| -% \xparse_grab_u:w | -% \xparse_grab_u_long:w | -%} -% \begin{syntax} -% "\xparse_grab_D:w" <arg data> "\l_xparse_args_tl" -% \end{syntax} -% Argument grabbing functions, which re-arrange other <arg data> -% so that the argument is read correctly. The \texttt{trailing} -% versions do not skip spaces when searching for optional arguments. -% For each argument type, the various versions feed the appropriate -% information to a common auxiliary function which then sets up -% \cs{xparse_grab_arg:w} to actually carry out the argument absorption. -%\end{function} -% -%\begin{function}{\xparse_if_no_value:n / (TF) (EXP)} -% \begin{syntax} -% "\xparse_if_no_value:nTF" \Arg{arg} -% ~~~~\Arg{true code} \Arg{false code} -% \end{syntax} -% Executes <true code> if <arg> is equal to the special -% \cs{NoValue} marker and <false code> otherwise. Provided that -% the primitive \cs{(pdf)strcmp} is available, this function is -% expandable. -%\end{function} -% -%\begin{function}{ -% \xparse_prepare_signature:n| -% \xparse_prepare_signature:N -%} -% \begin{syntax} -% "\xparse_prepare_signature:n" \Arg{arg specs} -% \end{syntax} -% Parse one or more <arg specs> and convert to an output <signature>. -%\end{function} -% -%\begin{function}{\xparse_process_arg:n} -% \begin{syntax} -% "\xparse_process_arg:n" \Arg{processor} -% \end{syntax} -% Sets up code to apply <processor> to next grabbed argument. -%\end{function} -% -%\subsection{Creating expandable commands} -% -%\begin{function}{ -% \xparse_exp_add_type_d:w| -% \xparse_exp_add_type_D:w| -% \xparse_exp_add_type_l:w| -% \xparse_exp_add_type_m:w| -% \xparse_exp_add_type_t:w| -% \xparse_exp_add_type_u:w -%} -% \begin{syntax} -% "\xparse_exp_add_type_u:w" \Arg{delimiter} -% \end{syntax} -% Carry out necessary processes to add given <type> of argument for -% an expandable command. Depending on the argument type being added, -% one or more arguments will be absorbed. -%\end{function} -% -%\begin{function}{\xparse_exp_check_and_add:N} -% \begin{syntax} -% "\xparse_exp_check_and_add:N" <arg spec> -% \end{syntax} -% Ensures that <arg spec> is valid, and if so adds it to expandable -% function being constructed. -%\end{function} -% -%\begin{function}{\xparse_exp_declare_cmd:Nnn} -% \begin{syntax} -% "\xparse_exp_declare_cmd:Nnn" <function> \Arg{signature} -% ~~~~\Arg{code} -% \end{syntax} -% Declares <function> using <signature> for argument definition and -% <code> as expansion, and creating an expandable command. -% \begin{texnote} -% This is the internal name for -% \cs{DeclareExpandableDocumentCommand}. -% \end{texnote} -%\end{function} -% -%\begin{function}{ -% \xparse_exp_prepare_function:n| -% \xparse_exp_prepare_function:N -%} -% \begin{syntax} -% "\xparse_exp_prepare_function:n" \Arg{arg specs} -% \end{syntax} -% Parse one or more <arg specs> and convert to an expandable -% function. -%\end{function} -% -%\begin{function}{\xparse_exp_set:cpx} -% \begin{syntax} -% "\xparse_exp_set:cpx" <csname> <parameters> \Arg{code} -% \end{syntax} -% An alias for either \cs{cs_set:cpx} or \cs{cs_set_nopar:cpx}, -% depending on the \cs{long} status of the expandable function. -%\end{function} -% -%\section{\pkg{xparse} implementation} -% -% The usual lead-off: only needed for the package, of course (one day we -% may have a \LaTeX3 kernel). -% \begin{macrocode} -%<*package> -\ProvidesExplPackage - {\filename}{\filedate}{\fileversion}{\filedescription} -\RequirePackage{expl3} -%</package> -%<*initex|package> -% \end{macrocode} -% -%\subsection{Variables and constants} -% -%\begin{macro}{\c_xparse_shorthands_prop} -% Shorthands are stored as a property list: this is set up here as it -% is a constant. -% \begin{macrocode} -\prop_new:N \c_xparse_shorthands_prop -\prop_put:Nnn \c_xparse_shorthands_prop { o } { d[] } -\prop_put:Nnn \c_xparse_shorthands_prop { O } { D[] } -\prop_put:Nnn \c_xparse_shorthands_prop { s } { t* } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_arg_tl} -% Token registers for single grabbed argument when post-processing. -% \begin{macrocode} -\tl_new:N \l_xparse_arg_tl -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_args_tl} -% Token registers for grabbed arguments. -% \begin{macrocode} -\tl_new:N \l_xparse_args_tl -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_environment_bool} -% Generating environments uses the same mechanism as generating -% functions. However, full processing of arguments is always needed -% for environments, and so the function-generating code needs to -% know this. -% \begin{macrocode} -\bool_new:N \l_xparse_environment_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_error_bool} -% Used to signal an error when creating expandable functions. -% \begin{macrocode} -\bool_new:N \l_xparse_error_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_function_tl} -% When creating expandable functions, the current function name needs -% to be passed along. -% \begin{macrocode} -\tl_new:N \l_xparse_function_tl -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_last_arg_tl} -% Used when creating expandable arguments. -% \begin{macrocode} -\tl_new:N \l_xparse_last_arg_tl -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_long_bool} -% A flag for \cs{long} arguments. -% \begin{macrocode} -\bool_new:N \l_xparse_long_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_m_args_int} -% The number of simple \texttt{m} arguments is tracked so they can be -% dumped \emph{en masse}. -% \begin{macrocode} -\int_new:N \l_xparse_m_args_int -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_m_only_bool} -% A flag to indicate that only \texttt{m} arguments have been found. -% \begin{macrocode} -\bool_new:N \l_xparse_m_only_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_mandatory_args_int} -% So that trailing optional arguments can be picked up, a count has to -% be taken of all mandatory arguments. This is then decreased as -% mandatory arguments are added to the signature, so will be zero -% only if there are no more mandatory arguments to add. -% \begin{macrocode} -\int_new:N \l_xparse_mandatory_args_int -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_processor_bool} -% When reading through the argument specifier, a flag is needed to -% show that a processor has been found for the current argument. This -% is used when checking how to handle \texttt{m} arguments. -% \begin{macrocode} -\bool_new:N \l_xparse_processor_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_processor_int} -% In the grabber routine, each processor is saved with a number -% recording the order it was found in. The total is then used to work -% back through the grabbers so they apply to the argument right to left. -% \begin{macrocode} -\int_new:N \l_xparse_processor_int -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_signature_tl} -% Token registers for constructing signatures. -% \begin{macrocode} -\tl_new:N \l_xparse_signature_tl -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_tmp_tl} -% A general purpose token list variable. -% \begin{macrocode} -\tl_new:N \l_xparse_tmp_tl -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xparse_total_args_int} -% Thje total number of arguments is used to create the internal function -% which has a fixed number of arguments. -% \begin{macrocode} -\int_new:N \l_xparse_total_args_int -% \end{macrocode} -%\end{macro} -% -%\subsection{Turning the argument specifier into grabbers} -% -%\begin{macro}{\xparse_add_grabber_mandatory:N} -%\begin{macro}{\xparse_add_grabber_optional:N} -% To keep the various checks needed in one place, adding the grabber to -% the signature is done here. For mandatory arguments, the only question -% is whether to add a long grabber. For optional arguments, there is -% also a check to see if any mandatory arguments are still to be added. -% This is used to determine whether to skip spaces or not where -% searching for the argument. -% \begin{macrocode} -\cs_new_nopar:Npn \xparse_add_grabber_mandatory:N #1 { - \tl_put_right:Nx \l_xparse_signature_tl { - \exp_not:c { - xparse_grab_ #1 \bool_if:NT \l_xparse_long_bool { _long } :w - } - } - \bool_set_false:N \l_xparse_long_bool - \int_decr:N \l_xparse_mandatory_args_int -} -\cs_new_nopar:Npn \xparse_add_grabber_optional:N #1 { - \tl_put_right:Nx \l_xparse_signature_tl { - \exp_not:c { - xparse_grab_ #1 - \bool_if:NT \l_xparse_long_bool { _long } - \int_compare:nF { - \l_xparse_mandatory_args_int > \c_zero - } { _trailing } - :w - } - } - \bool_set_false:N \l_xparse_long_bool -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -% All of the argument-adding functions work in essentially the same -% way, except the one for \texttt{m} arguments. Any collected \texttt{m} -% arguments are added to the signature, then the appropriate grabber -% is added to the signature. Some of the adding functions also pick up -% one or more arguments, and are also added to the signature. All of the -% functions then call the loop function \cs{xparse_prepare_signature:N}. -% -%\begin{macro}{\xparse_add_type_+:w} -% Making the next argument \cs{long} means setting the flag and -% knocking one back off the total argument count. The \texttt{m} -% arguments are recorded here as this has to be done for every case -% where there is then a \cs{long} argument. -% \begin{macrocode} -\cs_new_nopar:cpn { xparse_add_type_+:w } { - \xparse_flush_m_args: - \bool_set_true:N \l_xparse_long_bool - \bool_set_false:N \l_xparse_m_only_bool - \int_decr:N \l_xparse_total_args_int - \xparse_prepare_signature:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_add_type_>:w} -% When a processor is found, the function \cs{xparse_process_arg:n} -% is added to the signature along with the processor code itself. When -% the signature is used, the code will be added to an execution list by -% \cs{xparse_process_arg:n}. Here, the loop calls -% \cs{xparse_prepare_signature_aux:N} rather than -% \cs{xparse_prepare_signature:N} so that the flag is not reset. -% \begin{macrocode} -\cs_new:cpn { xparse_add_type_>:w } #1 { - \bool_set_true:N \l_xparse_processor_bool - \xparse_flush_m_args: - \int_decr:N \l_xparse_total_args_int - \tl_put_right:Nn \l_xparse_signature_tl { - \xparse_process_arg:n {#1} - } - \xparse_prepare_signature_aux:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_add_type_d:w} -% To save on repeated code, \texttt{d} is actually turned into -% the same grabber as is used by \texttt{D}, by putting the -% \cs{NoValue} default in the correct place. So there is some -% simple argument re-arrangement to do. Remember that |#1| and |#2| -% should be single tokens. -% \begin{macrocode} -\cs_new:Npn \xparse_add_type_d:w #1#2 { - \xparse_add_type_D:w #1 #2 { \NoValue } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_add_type_D:w} -% All of the optional delimited arguments are handled internally by -% the \texttt{D} type. At this stage, the two delimiters are stored -% along with the default value. -% \begin{macrocode} -\cs_new:Npn \xparse_add_type_D:w #1#2#3 { - \xparse_flush_m_args: - \xparse_add_grabber_optional:N D - \tl_put_right:Nn \l_xparse_signature_tl { #1 #2 {#3} } - \xparse_prepare_signature:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_add_type_g:w} -% The \texttt{g} type is simply an alias for \texttt{G} with the -% correct default built-in. -% \begin{macrocode} -\cs_new_nopar:Npn \xparse_add_type_g:w { - \xparse_add_type_G:w { \NoValue } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_add_type_G:w} -% For the \texttt{G} type, the grabber and the default are added to -% the signature. -% \begin{macrocode} -\cs_new:Npn \xparse_add_type_G:w #1 { - \xparse_flush_m_args: - \xparse_add_grabber_optional:N G - \tl_put_right:Nn \l_xparse_signature_tl { {#1} } - \xparse_prepare_signature:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_add_type_l:w} -% Finding \texttt{l} arguments is very simple: there is nothing to do -% other than add the grabber. -% \begin{macrocode} -\cs_new_nopar:Npn \xparse_add_type_l:w { - \xparse_flush_m_args: - \xparse_add_grabber_mandatory:N l - \xparse_prepare_signature:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_add_type_m:w} -% The \texttt{m} type is special as short arguments which are not -% post-processed are simply counted at this stage. Thus there is a check -% to see if either of these cases apply. If so, a one-argument grabber -% is added to the signature. On the other hand, if a standard short -% argument is required it is simply counted at this stage, to be -% added later using \cs{xparse_flush_m_args:}. -% \begin{macrocode} -\cs_new_nopar:Npn \xparse_add_type_m:w { - \bool_if:nTF { - \l_xparse_long_bool || \l_xparse_processor_bool - } { - \xparse_flush_m_args: - \xparse_add_grabber_mandatory:N m - }{ - \int_incr:N \l_xparse_m_args_int - } - \xparse_prepare_signature:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_add_type_t:w} -% Setting up a \texttt{t} argument means collecting one token for the -% test, and adding it along with the grabber to the signature. -% \begin{macrocode} -\cs_new:Npn \xparse_add_type_t:w #1 { - \xparse_flush_m_args: - \xparse_add_grabber_optional:N t - \tl_put_right:Nn \l_xparse_signature_tl { #1 } - \xparse_prepare_signature:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_add_type_u:w} -% At the set up stage, the \texttt{u} type argument is identical to the -% \texttt{G} type except for the name of the grabber function. -% \begin{macrocode} -\cs_new:Npn \xparse_add_type_u:w #1 { - \xparse_flush_m_args: - \xparse_add_grabber_mandatory:N u - \tl_put_right:Nn \l_xparse_signature_tl { {#1} } - \xparse_prepare_signature:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_check_and_add:N} -% This function checks if the argument type actually exists and gives -% an error if it doesn't. -% \begin{macrocode} -\cs_new_nopar:Npn \xparse_check_and_add:N #1 { - \cs_if_free:cTF { xparse_add_type_ #1 :w } { - \msg_kernel_error:nnx { xparse } { unknown-argument-type } {#1} - \xparse_add_type_m:w - }{ - \use:c { xparse_add_type_ #1 :w } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_count_mandatory:n} -%\begin{macro}{\xparse_count_mandatory:N} -%\begin{macro}[aux]{\xparse_count_mandatory_aux:N} -% To count up mandatory arguments before the main parsing run, the -% same approach is used. First, check if the current token is a -% short-cut for another argument type. If it is, expand it and loop -% again. If not, then look for a `counting' function to check the -% argument type. No error is raised here if one is not found as one -% will be raised by later code. -% \begin{macrocode} -\cs_new:Npn \xparse_count_mandatory:n #1 { - \int_zero:N \l_xparse_mandatory_args_int - \xparse_count_mandatory:N #1 \q_nil -} -\cs_new:Npn \xparse_count_mandatory:N #1 { - \quark_if_nil:NF #1 { - \prop_if_in:NnTF \c_xparse_shorthands_prop {#1} { - \prop_get:NnN \c_xparse_shorthands_prop {#1} \l_xparse_tmp_tl - \exp_last_unbraced:NV \xparse_count_mandatory:N \l_xparse_tmp_tl - }{ - \xparse_count_mandatory_aux:N #1 - } - } -} -\cs_new:Npn \xparse_count_mandatory_aux:N #1 { - \cs_if_free:cTF { xparse_count_type_ #1 :w } { - \xparse_count_type_m:w - }{ - \use:c { xparse_count_type_ #1 :w } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_count_type_>:w} -%\begin{macro}{\xparse_count_type_+:w} -%\begin{macro}{\xparse_count_type_d:w} -%\begin{macro}{\xparse_count_type_D:w} -%\begin{macro}{\xparse_count_type_g:w} -%\begin{macro}{\xparse_count_type_G:w} -%\begin{macro}{\xparse_count_type_l:w} -%\begin{macro}{\xparse_count_type_m:w} -%\begin{macro}{\xparse_count_type_t:w} -%\begin{macro}{\xparse_count_type_u:w} -% For counting the mandatory arguments, a function is provided for -% each argument type that will mop any extra arguments and call the -% loop function. Only the counting functions for mandatory arguments -% actually do anything: the rest are simply there to ensure the loop -% continues correctly. -% \begin{macrocode} -\cs_new:cpn { xparse_count_type_>:w } #1 { - \xparse_count_mandatory:N -} -\cs_new_nopar:cpn { xparse_count_type_+:w } { - \xparse_count_mandatory:N -} -\cs_new:Npn \xparse_count_type_d:w #1#2 { - \xparse_count_mandatory:N -} -\cs_new:Npn \xparse_count_type_D:w #1#2#3 { - \xparse_count_mandatory:N -} -\cs_new_nopar:Npn \xparse_count_type_g:w { - \xparse_count_mandatory:N -} -\cs_new:Npn \xparse_count_type_G:w #1 { - \xparse_count_mandatory:N -} -\cs_new_nopar:Npn \xparse_count_type_l:w { - \int_incr:N \l_xparse_mandatory_args_int - \xparse_count_mandatory:N -} -\cs_new_nopar:Npn \xparse_count_type_m:w { - \int_incr:N \l_xparse_mandatory_args_int - \xparse_count_mandatory:N -} -\cs_new:Npn \xparse_count_type_t:w #1 { - \xparse_count_mandatory:N -} -\cs_new:Npn \xparse_count_type_u:w #1 { - \int_incr:N \l_xparse_mandatory_args_int - \xparse_count_mandatory:N -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_declare_cmd:Nnn} -%\begin{macro}[aux]{\xparse_declare_cmd_aux:Nnn} -%\begin{macro}[aux]{\xparse_declare_cmd_aux:cnn} -%\begin{macro}[aux]{\xparse_declare_cmd_all_m:Nn} -%\begin{macro}[aux]{\xparse_declare_cmd_mixed:Nn} -% First, the signature is set up from the argument specification. There -% is then a check: if only \texttt{m} arguments are needed (which -% includes functions with no arguments at all) then the definition is -% simple. On the other hand, if the signature is more complex then an -% internal function actually contains the code with the user function -% as a simple wrapper. -% \begin{macrocode} -\cs_new:Npn \xparse_declare_cmd:Nnn #1#2 { - \cs_if_exist:NTF #1 - { - \msg_kernel_warning:nnxx { xparse } { redefine-command } - { \token_to_str:N #1 } { \exp_not:n {#2} } - } - { - \msg_kernel_info:nnxx { xparse } { define-command } - { \token_to_str:N #1 } { \exp_not:n {#2} } - } - \xparse_declare_cmd_aux:Nnn #1 {#2} -} -\cs_new:Npn \xparse_declare_cmd_aux:Nnn #1#2#3 { - \cs_if_exist:cF { l_xparse_ \token_to_str:N #1 _arg_spec_tl } - { \tl_new:c { l_xparse_ \token_to_str:N #1 _arg_spec_tl } } - \tl_set:cn { l_xparse_ \token_to_str:N #1 _arg_spec_tl } {#2} - \xparse_count_mandatory:n {#2} - \xparse_prepare_signature:n {#2} - \bool_if:NTF \l_xparse_m_only_bool { - \xparse_declare_cmd_all_m:Nn #1 {#3} - }{ - \xparse_declare_cmd_mixed:Nn #1 {#3} - } -} -\cs_generate_variant:Nn \xparse_declare_cmd_aux:Nnn { cnn } -\cs_new:Npn \xparse_declare_cmd_all_m:Nn #1#2 { - \cs_generate_from_arg_count:NNnn - #1 \cs_set_protected_nopar:Npn \l_xparse_total_args_int {#2} -} -\cs_new:Npn \xparse_declare_cmd_mixed:Nn #1#2 { - \group_begin: - \tex_escapechar:D 92 \scan_stop: - \tl_set:Nx \l_xparse_function_tl { \token_to_str:N #1 } - \exp_args:NNNo \group_end: - \tl_set:Nn \l_xparse_function_tl { \l_xparse_function_tl } - \cs_set_protected_nopar:Npx #1 { - \exp_not:n { - \int_zero:N \l_xparse_processor_int - \tl_set:Nn \l_xparse_args_tl - } { \exp_not:c { \l_xparse_function_tl } } - \exp_not:V \l_xparse_signature_tl - \exp_not:N \l_xparse_args_tl - } - \cs_generate_from_arg_count:cNnn - { \token_to_str:N #1 } \cs_set:Npn \l_xparse_total_args_int {#2} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_declare_cmd_implementation:nNn} -% Creating a stand-alone implementation using the `two-part' mechanism -% is quite easy as this is just a wrapper for -% \cs{cs_generate_from_arg_count:cNnn}. -% \begin{macrocode} -\cs_new:Npn \xparse_declare_cmd_implementation:nNn #1#2#3 { - \cs_generate_from_arg_count:cNnn { implementation_ #1 :w } - \cs_set:Npn {#2} {#3} -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_declare_cmd_interface:Nnn} -%\begin{macro}[aux]{\xparse_declare_cmd_interface_all_m:Nn} -%\begin{macro}[aux]{\xparse_declare_cmd_interface_mixed:Nn} -% As with the basic function \cs{xparse_declare_cmd:Nnn}, there are -% three things to do here. First, generate a signature from the -% argument specification. Then use that to create a function which -% will call the implementation part. Finally, a holder implementation -% is created. As before, there is a short-cut for functions which only -% have \texttt{m} type arguments. -% \begin{macrocode} -\cs_new:Npn \xparse_declare_cmd_interface:Nnn #1#2#3 { - \xparse_prepare_signature:n {#3} - \bool_if:NTF \l_xparse_m_only_bool { - \xparse_declare_cmd_interface_all_m:Nn #1 {#2} - }{ - \xparse_declare_cmd_interface_mixed:Nn #1 {#2} - } - \cs_generate_from_arg_count:cNnn { implementation_ #2 :w } - \cs_set:Npn \l_xparse_total_args_int { ``#2'' } -} -\cs_new:Npn \xparse_declare_cmd_interface_all_m:Nn #1#2 { - \cs_generate_from_arg_count:NNnn - #1 \cs_set_protected_nopar:Npn \l_xparse_total_args_int - { \use:c { implementation_ #2 :w } } -} -\cs_new:Npn \xparse_declare_cmd_interface_mixed:Nn #1#2 { - \cs_set_protected_nopar:Npx #1 { - \exp_not:n { - \int_zero:N \l_xparse_processor_int - \tl_set:Nn \l_xparse_args_tl - } { \exp_not:c { \token_to_str:N #1 } } - \exp_not:V \l_xparse_signature_tl - \exp_not:N \l_xparse_args_tl - } - \cs_generate_from_arg_count:cNnn - { \token_to_str:N #1 } \cs_set:Npn \l_xparse_total_args_int - { \use:c { implementation_ #2 :w } } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_declare_env:nnnn} -% The idea here is to make sure that the end of the environment has the -% same arguments available as the beginning. -% \begin{macrocode} -\cs_new:Npn \xparse_declare_env:nnnn #1#2#3#4 { - \bool_set_true:N \l_xparse_environment_bool -%</initex|package> -%<*initex> - \cs_if_exist:cTF { environment_begin_ #1 :w } -%</initex> -%<*package> - \cs_if_exist:cTF {#1} -%</package> -%<*initex|package> - { - \msg_kernel_warning:nnxx { xparse } { redefine-environment } - {#1} { \exp_not:n {#2} } - } - { - \msg_kernel_info:nnxx { xparse } { define-environment } - {#1} { \exp_not:n {#2} } - } - \xparse_declare_cmd_aux:cnn { environment_begin_ #1 :w } {#2} { - \group_begin: - \cs_set_protected_nopar:cpx { environment_end_ #1 :w } - { - \exp_not:c { environment_end_ #1 _aux:N } - \exp_not:V \l_xparse_args_tl - \group_end: - } - #3 - } - \cs_set_protected_nopar:cpx { environment_end_ #1 : } - { \exp_not:c { environment_end_ #1 :w } } - \bool_set_false:N \l_xparse_environment_bool - \cs_set_nopar:cpx { environment_end_ #1 _aux:N } ##1 { - \exp_not:c { environment_end_ #1 _aux :w } - } - \cs_generate_from_arg_count:cNnn - { environment_end_ #1 _aux :w } \cs_set:Npn - \l_xparse_total_args_int {#4} -%</initex|package> -%<*package> - \cs_set_eq:cc {#1} { environment_begin_ #1 :w } - \cs_set_eq:cc { end #1 } { environment_end_ #1 : } -%</package> -%<*initex|package> -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_flush_m_args:} -% As \texttt{m} arguments are simply counted, there is a need to add -% them to the token register in a block. As this function can only -% be called if something other than \texttt{m} turns up, the flag can -% be switched here. The total number of mandatory arguments added to -% the signature is also decreased by the appropriate amount. -% \begin{macrocode} -\cs_new_nopar:Npn \xparse_flush_m_args: { - \cs_if_exist:cT { - xparse_grab_m_ \int_use:N \l_xparse_m_args_int :w - } { - \tl_put_right:Nx \l_xparse_signature_tl { - \exp_not:c { xparse_grab_m_ \int_use:N \l_xparse_m_args_int :w } - } - \int_set:Nn \l_xparse_mandatory_args_int { - \l_xparse_mandatory_args_int - \l_xparse_m_args_int - } - } - \int_zero:N \l_xparse_m_args_int - \bool_set_false:N \l_xparse_m_only_bool -} -% \end{macrocode} -%\end{macro} -% -% -%\begin{macro}[TF]{\xparse_if_no_value:n} -% Tests for \cs{NoValue}. -% \begin{macrocode} -\prg_new_conditional:Nnn \xparse_if_no_value:n { TF,T,F } { - \str_if_eq:nnTF {#1} { \NoValue } { - \prg_return_true: - }{ - \prg_return_false: - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_prepare_signature:n} -% Creating the signature is a case of working through the input and -% turning into the output in \cs{l_xparse_signature_tl}. A track is -% also kept of the total number of arguments. This function sets -% everything up then hands off to the parser. -% \begin{macrocode} -\cs_new:Npn \xparse_prepare_signature:n #1 { - \bool_set_false:N \l_xparse_long_bool - \int_zero:N \l_xparse_m_args_int - \bool_if:NTF \l_xparse_environment_bool { - \bool_set_false:N \l_xparse_m_only_bool - }{ - \bool_set_true:N \l_xparse_m_only_bool - } - \bool_set_false:N \l_xparse_processor_bool - \tl_clear:N \l_xparse_signature_tl - \int_zero:N \l_xparse_total_args_int - \xparse_prepare_signature:N #1 \q_nil -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_prepare_signature:N} -%\begin{macro}[aux]{\xparse_prepare_signature_aux:N} -% The main signature-preparation loop is in two parts, to keep the code -% a little clearer. Most of the checks here is pretty clear, with a key -% point to watch what is next on the stack so that the loop continues -% correctly. -% \begin{macrocode} -\cs_new:Npn \xparse_prepare_signature:N #1 { - \bool_set_false:N \l_xparse_processor_bool - \xparse_prepare_signature_aux:N #1 -} -\cs_new:Npn \xparse_prepare_signature_aux:N #1 { - \quark_if_nil:NTF #1 { - \bool_if:NF \l_xparse_m_only_bool { - \xparse_flush_m_args: - } - }{ - \prop_if_in:NnTF \c_xparse_shorthands_prop {#1} { - \prop_get:NnN \c_xparse_shorthands_prop {#1} \l_xparse_tmp_tl - \exp_last_unbraced:NV \xparse_prepare_signature:N \l_xparse_tmp_tl - }{ - \int_incr:N \l_xparse_total_args_int - \xparse_check_and_add:N #1 - } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_process_arg:n} -% Processors are saved for use later during the grabbing process. -% \begin{macrocode} -\cs_new:Npn \xparse_process_arg:n #1 { - \int_incr:N \l_xparse_processor_int - \cs_set:cpn { - xparse_processor_ \int_use:N \l_xparse_processor_int :n - } ##1 - { #1 {##1} } -} -% \end{macrocode} -%\end{macro} -% -%\subsection{Grabbing arguments} -% -%\begin{macro}{\xparse_add_arg:n} -%\begin{macro}{\xparse_add_arg:V} -%\begin{macro}[aux]{\xparse_add_arg_aux:n} -%\begin{macro}[aux]{\xparse_add_arg_aux:V} -% The argument-storing system provides a single point for interfacing -% with processors. They are done in a loop, counting downward. In this -% way, the processor which was found last is executed first. The result -% is that processors apply from right to left, as intended. Notice that -% a set of braces are added back around the result of processing so that -% the internal function will correctly pick up one argument for each -% input argument. -% \begin{macrocode} -\cs_new:Npn \xparse_add_arg:n #1 { - \int_compare:nTF { \l_xparse_processor_int = \c_zero } { - \tl_put_right:Nn \l_xparse_args_tl { {#1} } - }{ - \xparse_if_no_value:nTF {#1} { - \int_zero:N \l_xparse_processor_int - \tl_put_right:Nn \l_xparse_args_tl { {#1} } - }{ - \xparse_add_arg_aux:n {#1} - } - } -} -\cs_generate_variant:Nn \xparse_add_arg:n { V } -\cs_new:Npn \xparse_add_arg_aux:n #1 { - \tl_set_eq:NN \ProcessedArgument \l_xparse_arg_tl - \use:c { xparse_processor_ \int_use:N \l_xparse_processor_int :n } - {#1} - \int_decr:N \l_xparse_processor_int - \int_compare:nTF { \l_xparse_processor_int = \c_zero } { - \tl_put_right:Nx \l_xparse_args_tl { - { \exp_not:V \ProcessedArgument } - } - }{ - \xparse_add_arg_aux:V \ProcessedArgument - } -} -\cs_generate_variant:Nn \xparse_add_arg_aux:n { V } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -% All of the grabbers follow the same basic pattern. The initial -% function sets up the appropriate information to define -% \cs{parse_grab_arg:w} to grab the argument. This means determining -% whether to use \cs{cs_set:Npn} or \cs{cs_set_nopar:Npn}, and for -% optional arguments whether to skip spaces. In all cases, -% \cs{xparse_grab_arg:w} is then called to actually do the grabbing. -% -%\begin{macro}{\xparse_grab_arg:w} -%\begin{macro}[aux]{\xparse_grab_arg_aux_i:w} -%\begin{macro}[aux]{\xparse_grab_arg_aux_ii:w} -% Each time an argument is actually grabbed, \pkg{xparse} defines a -% function to do it. In that way, long arguments from previous functions -% can be included in the definition of the grabber function, so that -% it does not raise an error if not long. The generic function used -% for this is reserved here. A couple of auxiliary functions are also -% needed in various places. -% \begin{macrocode} -\cs_new:Npn \xparse_grab_arg:w { } -\cs_new:Npn \xparse_grab_arg_aux_i:w { } -\cs_new:Npn \xparse_grab_arg_aux_ii:w { } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_grab_D:w} -%\begin{macro}{\xparse_grab_D_long:w} -%\begin{macro}{\xparse_grab_D_trailing:w} -%\begin{macro}{\xparse_grab_D_long_trailing:w} -% The generic delimited argument grabber. The auxiliary function does -% a peek test before calling \cs{xparse_grab_arg:w}, so that the -% optional nature of the argument works as expected. -% \begin{macrocode} -\cs_new:Npn \xparse_grab_D:w #1#2#3#4 \l_xparse_args_tl { - \xparse_grab_D_aux:NNnnNn #1 #2 {#3} {#4} \cs_set_nopar:Npn - { _ignore_spaces } -} -\cs_new:Npn \xparse_grab_D_long:w #1#2#3#4 \l_xparse_args_tl { - \xparse_grab_D_aux:NNnnNn #1 #2 {#3} {#4} \cs_set:Npn - { _ignore_spaces } -} -\cs_new:Npn \xparse_grab_D_trailing:w #1#2#3#4 \l_xparse_args_tl { - \xparse_grab_D_aux:NNnnNn #1 #2 {#3} {#4} \cs_set_nopar:Npn { } -} -\cs_new:Npn \xparse_grab_D_long_trailing:w #1#2#3#4 - \l_xparse_args_tl { - \xparse_grab_D_aux:NNnnNn #1 #2 {#3} {#4} \cs_set:Npn { } -} -% \end{macrocode} -%\begin{macro}[aux]{\xparse_grab_D_aux:NNnnNn} -% This is a bit complicated. The idea is that, in order to check for -% nested optional argument tokens (\texttt{[[...]]} and so on) the -% argument needs to be grabbed without removing any braces at all. If -% this is not done, then cases like |[{[}]| fail. So after testing for -% an optional argument, it is collected piece-wise. First, the opening -% token is removed, then a check is made for a group. If it looks like -% the entire argument is a group, then an extra set of braces are -% added back in. The closing token is then used to collect everything -% else. There is then a test to see if there is nesting, by looking -% for a `spare' open-argument token. If that is found, things hand off -% to a loop to deal with that. -% \begin{macrocode} -\cs_new:Npn \xparse_grab_D_aux:NNnnNn #1#2#3#4#5#6 { - #5 \xparse_grab_arg:w #1 { - \peek_meaning:NTF \c_group_begin_token { - \xparse_grab_arg_aux_i:w - }{ - \xparse_grab_arg_aux_ii:w - } - } - #5 \xparse_grab_arg_aux_i:w ##1 { - \peek_charcode:NTF #2 { - \xparse_grab_arg_aux_ii:w { {##1} } - }{ - \xparse_grab_arg_aux_ii:w {##1} - } - } - #5 \xparse_grab_arg_aux_ii:w ##1 #2 { - \tl_if_in:nnTF {##1} {#1} { - \xparse_grab_D_nested:NNnnN #1 #2 {##1} {#4} #5 - }{ - \xparse_add_arg:n {##1} - #4 \l_xparse_args_tl - } - } - \use:c { peek_charcode #6 :NTF } #1 { - \xparse_grab_arg:w - }{ - \xparse_add_arg:n {#3} - #4 \l_xparse_args_tl - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\begin{macro}[aux]{\xparse_grab_D_nested:NNnnN} -%\begin{macro}{\_l_xparse_nesting_a_tl} -%\begin{macro}{\_l_xparse_nesting_b_tl} -%\begin{macro}{\q_xparse} -% Catching nested optional arguments means more work. The aim here is -% to collect up each pair of optional tokens without \TeX\ helping out, -% and without counting anything. The code above will already have -% removed the leading opening token and a closing token, but the -% wrong one. The aim is then to work through the the material grabbed -% so far and divide it up on each opening token, grabbing a closing -% token to match (thus working in pairs). Once there are no opening -% tokens, then there is a second check to see if there are any -% opening tokens in the second part of the argument (for things -% like "[][]"). Once everything has been found, the entire collected -% material is added to the output as a single argument. -% \begin{macrocode} -\tl_new:N \_l_xparse_nesting_a_tl -\tl_new:N \_l_xparse_nesting_b_tl -\quark_new:N \q_xparse -\cs_new_protected:Npn \xparse_grab_D_nested:NNnnN #1#2#3#4#5 { - \tl_clear:N \_l_xparse_nesting_a_tl - \tl_clear:N \_l_xparse_nesting_b_tl - #5 \xparse_grab_arg:w ##1 #1 ##2 \q_xparse ##3 #2 - { - \tl_put_right:Nn \_l_xparse_nesting_a_tl { ##1 #1 } - \tl_put_right:Nn \_l_xparse_nesting_b_tl { #2 ##3 } - \tl_if_in:nnTF {##2} {#1} - { \xparse_grab_arg:w ##2 \q_xparse } - { - \tl_put_right:Nn \_l_xparse_nesting_a_tl {##2} - \tl_if_in:NnTF \_l_xparse_nesting_b_tl {#1} - { - \tl_set_eq:NN \l_xparse_tmp_tl \_l_xparse_nesting_b_tl - \tl_clear:N \_l_xparse_nesting_b_tl - \exp_last_unbraced:NV \xparse_grab_arg:w - \l_xparse_tmp_tl \q_xparse - } - { - \tl_put_right:NV \_l_xparse_nesting_a_tl - \_l_xparse_nesting_b_tl - \xparse_add_arg:V \_l_xparse_nesting_a_tl - #4 \l_xparse_args_tl - } - } - } - \xparse_grab_arg:w #3 \q_xparse -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_grab_G:w} -%\begin{macro}{\xparse_grab_G_long:w} -%\begin{macro}{\xparse_grab_G_trailing:w} -%\begin{macro}{\xparse_grab_G_long_trailing:w} -%\begin{macro}[aux]{\xparse_grab_G_aux:nnNn} -% Optional groups are checked by meaning, so that the same code will -% work with, for example, Con\TeX{}t-like input. -% \begin{macrocode} -\cs_new:Npn \xparse_grab_G:w #1#2 \l_xparse_args_tl { - \xparse_grab_G_aux:nnNn {#1} {#2} \cs_set_nopar:Npn { _ignore_spaces } -} -\cs_new:Npn \xparse_grab_G_long:w #1#2 \l_xparse_args_tl { - \xparse_grab_G_aux:nnNn {#1} {#2} \cs_set:Npn { _ignore_spaces } -} -\cs_new:Npn \xparse_grab_G_trailing:w #1#2 \l_xparse_args_tl { - \xparse_grab_G_aux:nnNn {#1} {#2} \cs_set_nopar:Npn { } -} -\cs_new:Npn \xparse_grab_G_long_trailing:w #1#2 \l_xparse_args_tl { - \xparse_grab_G_aux:nnNn {#1} {#2} \cs_set:Npn { } -} -\cs_set:Npn \xparse_grab_G_aux:nnNn #1#2#3#4 { - #3 \xparse_grab_arg:w ##1 { - \xparse_add_arg:n {##1} - #2 \l_xparse_args_tl - } - \use:c { peek_meaning #4 :NTF } \c_group_begin_token { - \xparse_grab_arg:w - }{ - \xparse_add_arg:n {#1} - #2 \l_xparse_args_tl - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_grab_l:w} -%\begin{macro}{\xparse_grab_l_long:w} -%\begin{macro}[aux]{\xparse_grab_l_aux:nN} -% Argument grabbers for mandatory \TeX\ arguments are pretty simple. -% \begin{macrocode} -\cs_new:Npn \xparse_grab_l:w #1 \l_xparse_args_tl { - \xparse_grab_l_aux:nN {#1} \cs_set_nopar:Npn -} -\cs_new:Npn \xparse_grab_l_long:w #1 \l_xparse_args_tl { - \xparse_grab_l_aux:nN {#1} \cs_set:Npn -} -\cs_new:Npn \xparse_grab_l_aux:nN #1#2 { - #2 \xparse_grab_arg:w ##1## { - \xparse_add_arg:n {##1} - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_grab_m:w} -%\begin{macro}{\xparse_grab_m_long:w} -% Collecting a single mandatory argument is quite easy. -% \begin{macrocode} -\cs_new:Npn \xparse_grab_m:w #1 \l_xparse_args_tl { - \cs_set_nopar:Npn \xparse_grab_arg:w ##1 { - \xparse_add_arg:n {##1} - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -\cs_new:Npn \xparse_grab_m_long:w #1 \l_xparse_args_tl { - \cs_set:Npn \xparse_grab_arg:w ##1 { - \xparse_add_arg:n {##1} - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_grab_m_1:w} -%\begin{macro}{\xparse_grab_m_2:w} -%\begin{macro}{\xparse_grab_m_3:w} -%\begin{macro}{\xparse_grab_m_4:w} -%\begin{macro}{\xparse_grab_m_5:w} -%\begin{macro}{\xparse_grab_m_6:w} -%\begin{macro}{\xparse_grab_m_7:w} -%\begin{macro}{\xparse_grab_m_8:w} -% Grabbing 1--8 mandatory arguments. We don't need to worry about -% nine arguments as this is only possible if everything is -% mandatory. Each function has an auxiliary so that \cs{par} tokens -% from other arguments still work. -% \begin{macrocode} -\cs_new:cpn { xparse_grab_m_1:w } #1 \l_xparse_args_tl { - \cs_set_nopar:Npn \xparse_grab_arg:w ##1 { - \tl_put_right:Nn \l_xparse_args_tl { {##1} } - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -\cs_new:cpn { xparse_grab_m_2:w } #1 \l_xparse_args_tl { - \cs_set_nopar:Npn \xparse_grab_arg:w ##1##2 { - \tl_put_right:Nn \l_xparse_args_tl { {##1} {##2} } - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -\cs_new:cpn { xparse_grab_m_3:w } #1 \l_xparse_args_tl { - \cs_set_nopar:Npn \xparse_grab_arg:w ##1##2##3 { - \tl_put_right:Nn \l_xparse_args_tl { {##1} {##2} {##3} } - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -\cs_new:cpn { xparse_grab_m_4:w } #1 \l_xparse_args_tl { - \cs_set_nopar:Npn \xparse_grab_arg:w ##1##2##3##4 { - \tl_put_right:Nn \l_xparse_args_tl { {##1} {##2} {##3} {##4} } - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -\cs_new:cpn { xparse_grab_m_5:w } #1 \l_xparse_args_tl { - \cs_set_nopar:Npn \xparse_grab_arg:w ##1##2##3##4##5 { - \tl_put_right:Nn \l_xparse_args_tl { - {##1} {##2} {##3} {##4} {##5} - } - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -\cs_new:cpn { xparse_grab_m_6:w } #1 \l_xparse_args_tl { - \cs_set_nopar:Npn \xparse_grab_arg:w ##1##2##3##4##5##6 { - \tl_put_right:Nn \l_xparse_args_tl { - {##1} {##2} {##3} {##4} {##5} {##6} - } - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -\cs_new:cpn { xparse_grab_m_7:w } #1 \l_xparse_args_tl { - \cs_set_nopar:Npn \xparse_grab_arg:w ##1##2##3##4##5##6##7 { - \tl_put_right:Nn \l_xparse_args_tl { - {##1} {##2} {##3} {##4} {##5} {##6} {##7} - } - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -\cs_new:cpn { xparse_grab_m_8:w } #1 \l_xparse_args_tl { - \cs_set_nopar:Npn \xparse_grab_arg:w ##1##2##3##4##5##6##7##8 { - \tl_put_right:Nn \l_xparse_args_tl { - {##1} {##2} {##3} {##4} {##5} {##6} {##7} {##8} - } - #1 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_grab_t:w} -%\begin{macro}{\xparse_grab_t_long:w} -%\begin{macro}{\xparse_grab_t_trailing:w} -%\begin{macro}{\xparse_grab_t_long_trailing:w} -%\begin{macro}[aux]{\xparse_grab_t_aux:NnNn} -% Dealing with a token is quite easy. Check the match, remove the -% token if needed and add a flag to the output. -% \begin{macrocode} -\cs_new:Npn \xparse_grab_t:w #1#2 \l_xparse_args_tl { - \xparse_grab_t_aux:NnNn #1 {#2} \cs_set_nopar:Npn { _ignore_spaces } -} -\cs_new:Npn \xparse_grab_t_long:w #1#2 \l_xparse_args_tl { - \xparse_grab_t_aux:NnNn #1 {#2} \cs_set:Npn { _ignore_spaces } -} -\cs_new:Npn \xparse_grab_t_trailing:w #1#2 \l_xparse_args_tl { - \xparse_grab_t_aux:NnNn #1 {#2} \cs_set_nopar:Npn { } -} -\cs_new:Npn \xparse_grab_t_long_trailing:w #1#2 \l_xparse_args_tl { - \xparse_grab_t_aux:NnNn #1 {#2} \cs_set:Npn { } -} -\cs_new:Npn \xparse_grab_t_aux:NnNn #1#2#3#4 { - #3 \xparse_grab_arg:w { - \use:c { peek_charcode_remove #4 :NTF } #1 { - \xparse_add_arg:n { \BooleanTrue } - #2 \l_xparse_args_tl - }{ - \xparse_add_arg:n { \BooleanFalse } - #2 \l_xparse_args_tl - } - } - \xparse_grab_arg:w -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_grab_u:w} -%\begin{macro}{\xparse_grab_u_long:w} -%\begin{macro}[aux]{\xparse_grab_u_aux:NnN} -% Grabbing up to a list of tokens is quite easy: define the grabber, -% and then collect. -% \begin{macrocode} -\cs_new:Npn \xparse_grab_u:w #1#2 \l_xparse_args_tl { - \xparse_grab_u_aux:NnN {#1} {#2} \cs_set_nopar:Npn -} -\cs_new:Npn \xparse_grab_u_long:w #1#2 \l_xparse_args_tl { - \xparse_grab_u_aux:NnN {#1} {#2} \cs_set:Npn -} -\cs_new:Npn \xparse_grab_u_aux:NnN #1#2#3 { - #3 \xparse_grab_arg:w ##1 #1 { - \xparse_add_arg:n {##1} - #2 \l_xparse_args_tl - } - \xparse_grab_arg:w -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\subsection{Argument processors} -% -%\begin{macro}{\xparse_process_to_str:n} -% A basic argument processor: as much an example as anything else. -% \begin{macrocode} -\cs_new:Npn \xparse_process_to_str:n #1 { - \tl_set:Nx \ProcessedArgument { - \tl_to_str:n {#1} - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\_parse_bool_reverse:N} -% A simple reversal. -% \begin{macrocode} -\cs_new_protected:Npn \_xparse_bool_reverse:N #1 { - \bool_if:NTF #1 - { \tl_set:Nn \ProcessedArgument { \c_false_bool } } - { \tl_set:Nn \ProcessedArgument { \c_true_bool } } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\_l_xparse_split_argument_tl} -%\begin{macro}{\_xparse_split_argument:nnn} -%\begin{macro}[aux]{\_xparse_split_argument_aux_i:w} -%\begin{macro}[aux]{\_xparse_split_argument_aux_ii:w} -%\begin{macro}[aux]{\_xparse_split_argument_aux_iii:w} -% The idea of this function is to split the input \( n + 1 \) times using -% a given token. -% \begin{macrocode} -\tl_new:N \_l_xparse_split_argument_tl -\group_begin: - \char_make_active:N \@ - \cs_gset_protected:Npn \_xparse_split_argument:nnn #1#2#3 - { - \tl_set:Nn \_l_xparse_split_argument_tl {#3} - \group_begin: - \char_set_lccode:nn { `\@ } { `#2} - \tl_to_lowercase:n - { - \group_end: - \tl_replace_all_in:Nnn \_l_xparse_split_argument_tl { @ } {#2} - } - \cs_set_protected:Npn \_xparse_split_argument_aux_i:w - ##1 \q_mark ##2 #2 ##3 \q_stop - { - \tl_put_right:Nn \ProcessedArgument { {##2} } - ##1 \q_mark ##3 \q_stop - } - \cs_set_protected:Npn \_xparse_split_argument_aux_iii:w - ##1 #2 ##2 \q_stop - { - \IfNoValueF {##1} - { - \msg_kernel_error:nnxxx { xparse } { split-excess-tokens } - { \exp_not:n {#2} } {#1} { \exp_not:n {#3} } - } - } - \tl_set:Nx \l_xparse_tmp_tl - { - \prg_replicate:nn { #1 + 1 } - { \_xparse_split_argument_aux_i:w } - \_xparse_split_argument_aux_ii:w - \exp_not:N \q_mark - \exp_not:V \_l_xparse_split_argument_tl - \prg_replicate:nn {#1} { \exp_not:n {#2} \NoValue } - \exp_not:n { #2 \q_stop } - } - \l_xparse_tmp_tl - } -\group_end: -\cs_set_protected:Npn \_xparse_split_argument_aux_i:w { } -\cs_set_protected:Npn \_xparse_split_argument_aux_ii:w - #1 \q_mark #2 \q_stop - { - \tl_if_empty:nF {#2} - { \_xparse_split_argument_aux_iii:w #2 \q_stop } - } -\cs_set_protected:Npn \_xparse_split_argument_aux_iii:w { } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\_l_xparse_split_list_tl} -%\begin{macro}{\_xparse_split_list:nn} -%\begin{macro}{\_xparse_split_list_aux:w} -% Splitting a list is done again by first dealing with active -% characters, then looping over the list using the same method as the -% \cs{clist_map_\ldots} functions. -% \begin{macrocode} -\tl_new:N \_l_xparse_split_list_tl -\group_begin: - \char_make_active:N \@ - \cs_gset_protected:Npn \_xparse_split_list:nn #1#2 - { - \tl_set:Nn \_l_xparse_split_list_tl {#2} - \group_begin: - \char_set_lccode:nn { `\@ } { `#1 } - \tl_to_lowercase:n - { - \group_end: - \tl_replace_all_in:Nnn \_l_xparse_split_list_tl { @ } {#1} - } - \cs_set:Npn \_xparse_split_list_aux:w ##1 #1 - { - \quark_if_recursion_tail_stop:n {##1} - \tl_put_right:Nn \ProcessedArgument { {##1} } - \_xparse_split_list_aux:w - } - \tl_if_empty:NTF \_l_xparse_split_list_tl - { \tl_set:Nn \ProcessedArgument { { } } } - { - \tl_clear:N \ProcessedArgument - \exp_last_unbraced:NV \_xparse_split_list_aux:w - \_l_xparse_split_list_tl #1 - \q_recursion_tail #1 \q_recursion_stop - } - } -\group_end: -\cs_set:Npn \_xparse_split_list_aux:w { } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\subsection{Creating expandable functions} -% -% The trick here is to pass each grabbed argument along a chain of -% auxiliary functions. Each one ultimately calls the next in the chain, -% so that all of the arguments are passed along delimited using -% \cs{q_xparse}. At the end of the chain, the marker is removed -% so that the user-supplied code can be passed the correct number -% of arguments. All of this is done by expansion! -% -%\begin{macro}{\xparse_exp_add_type_d:w} -% As in the standard case, the trick here is to slot in the default -% and treat as type \texttt{D}. -% \begin{macrocode} -\cs_new:Npn \xparse_exp_add_type_d:w #1#2 { - \xparse_exp_add_type_D:w #1 #2 { \NoValue } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_exp_add_type_D:w} -% The most complex argument to grab in an expandable manner is the -% general delimited one. First, a short-cut is set up in -% \cs{l_xparse_tmp_tl} for the name of the current grabber function. -% This is then created to grab one argument and test if it is equal -% to the opening delimiter. If the test fails, the code adds the default -% value and closing delimiter before `recycling' the argument. In either -% case, the second auxiliary function is called. It finds the closing -% delimiter and so the optional argument (if any). The function then -% calls the next one in the chain, passing along the argument(s) -% grabbed thus-far using \cs{q_xparse} as a marker. -% \begin{macrocode} -\cs_new:Npn \xparse_exp_add_type_D:w #1#2#3 { - \tl_set:Nx \l_xparse_tmp_tl { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_use:N \l_xparse_total_args_int - } - \xparse_exp_set:cpx { \l_xparse_tmp_tl } ##1 \q_xparse ##2 { - \exp_not:N \tl_if_head_eq_charcode:nNTF {##2} #1 { - \exp_not:c { \l_xparse_tmp_tl aux } - ##1 \exp_not:N \q_xparse - }{ - \exp_not:c { \l_xparse_tmp_tl aux } - ##1 \exp_not:N \q_xparse #3 #2 {##2} - } - } - \xparse_exp_set:cpx { \l_xparse_tmp_tl aux} ##1 \q_xparse ##2 #2 { - \exp_not:c { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_eval:n { \l_xparse_total_args_int + 1 } - } ##1 {##2} \exp_not:N \q_xparse - } - \xparse_exp_prepare_function:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_exp_add_type_l:w} -%\begin{macro}{\xparse_exp_add_type_m:w} -% Gathering \texttt{l} and \texttt{m} arguments is almost the same. -% The grabber for the current argument is created to simply get the -% necessary argument and pass it along with any others through to the -% next function in the chain. -% \begin{macrocode} -\cs_new_nopar:Npn \xparse_exp_add_type_l:w { - \xparse_exp_set:cpx { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_use:N \l_xparse_total_args_int - } ##1 \q_xparse ##2## { - \exp_not:c { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_eval:n { \l_xparse_total_args_int + 1 } - } - ##1 {##2} \exp_not:N \q_xparse - } - \xparse_exp_prepare_function:N -} -\cs_new_nopar:Npn \xparse_exp_add_type_m:w { - \int_incr:N \l_xparse_m_args_int - \xparse_exp_set:cpx { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_use:N \l_xparse_total_args_int - } ##1 \q_xparse ##2 { - \exp_not:c { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_eval:n { \l_xparse_total_args_int + 1 } - } - ##1 {##2} \exp_not:N \q_xparse - } - \xparse_exp_prepare_function:N -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_exp_add_type_t:w} -% Looking for a single token is a simpler version of the \texttt{D} -% code. The same idea of picking up one argument is used, but there is -% no need for a second function as there is no closing token to find. So -% either \cs{BooleanTrue} or \cs{BooleanFalse} are added to the list of -% arguments. In the later case, the grabber argument must be `recycled'. -% \begin{macrocode} -\cs_new:Npn \xparse_exp_add_type_t:w #1 { - \tl_set:Nx \l_xparse_tmp_tl { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_eval:n { \l_xparse_total_args_int + 1 } - } - \xparse_exp_set:cpx { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_use:N \l_xparse_total_args_int - } ##1 \q_xparse ##2 { - \exp_not:N \tl_if_head_eq_charcode:nNTF {##2} #1 { - \exp_not:c { \l_xparse_tmp_tl } - ##1 \exp_not:n { { \BooleanTrue } \q_xparse } - }{ - \exp_not:c { \l_xparse_tmp_tl } - ##1 \exp_not:n { { \BooleanFalse } \q_xparse {##2} } - } - } - \xparse_exp_prepare_function:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_exp_add_type_u:w} -% Setting up for a \texttt{u} argument is a case of defining the -% grabber for the current argument in a delimited fashion. The rest of -% the process is as the other grabbers: add to the chain and call the -% next function. -% \begin{macrocode} -\cs_new:Npn \xparse_exp_add_type_u:w #1 { - \xparse_exp_set:cpx { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_use:N \l_xparse_total_args_int - } ##1 \q_xparse ##2 #1 { - \exp_not:c { - \exp_after:wN \token_to_str:N \l_xparse_function_tl - \int_eval:n { \l_xparse_total_args_int + 1 } - } - ##1 {##2} \exp_not:N \q_xparse - } - \xparse_exp_prepare_function:N -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_exp_check_and_add:N} -% Virtually identical to the normal version, except calling the -% expandable \texttt{add} functions rather than the standard versions. -% \begin{macrocode} -\cs_new_nopar:Npn \xparse_exp_check_and_add:N #1 { - \cs_if_free:cTF { xparse_exp_add_type_ #1 :w } { - \msg_kernel_error:nnx { xparse } { unknown-argument-type } {#1} - \tl_set:Nn \l_xparse_last_arg_tl { m } - \xparse_exp_add_type_m:w - }{ - \tl_set:Nn \l_xparse_last_arg_tl {#1} - \use:c { xparse_exp_add_type_ #1 :w } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xparse_exp_declare_cmd:Nnn} -%\begin{macro}[aux]{\xparse_exp_declare_cmd_all_m:Nn} -%\begin{macro}[aux]{\xparse_exp_declare_cmd_mixed:Nn} -%\begin{macro}[aux]{\xparse_exp_declare_cmd_mixed_aux:Nn} -% The overall scheme here is very different from the standard method. -% For each argument, an internal function is created to grab an argument -% and pass along previous ones. Each `daisy chains' to call the next -% one in the sequence. Thus at the end of the chain, an extra `argument' -% function is included to unwind the chain and pass data to the the -% internal function containing the actual code. If all of the arguments -% are type \texttt{m}, then the same tick is used as in the standard -% version. The \texttt{x} in the lead-off and mop-up functions makes -% sure that the braces around the first argument are not lost. -% \begin{macrocode} -\cs_new:Npn \xparse_exp_declare_cmd:Nnn #1#2#3 { - \cs_if_exist:NTF #1 - { - \msg_kernel_warning:nnxx { xparse } { redefine-command } - { \token_to_str:N #1 } { \exp_not:n {#2} } - } - { - \msg_kernel_info:nnxx { xparse } { define-command } - { \token_to_str:N #1 } { \exp_not:n {#2} } - } - \group_begin: - \tex_escapechar:D 92 \scan_stop: - \tl_set:Nx \l_xparse_function_tl { \token_to_str:N #1} - \exp_args:NNNo \group_end: - \tl_set:Nn \l_xparse_function_tl { \l_xparse_function_tl } - \xparse_exp_prepare_function:n {#2} - \int_compare:nTF { - \l_xparse_total_args_int = \l_xparse_m_args_int - } { - \xparse_exp_declare_cmd_all_m:Nn #1 {#3} - }{ - \xparse_exp_declare_cmd_mixed:Nn #1 {#3} - } -} -\cs_new:Npn \xparse_exp_declare_cmd_all_m:Nn #1#2 { - \bool_if:NTF \l_xparse_long_bool { - \cs_generate_from_arg_count:NNnn - #1 \cs_set:Npn \l_xparse_total_args_int {#2} - }{ - \cs_generate_from_arg_count:NNnn - #1 \cs_set_nopar:Npn \l_xparse_total_args_int {#2} - } -} -\cs_new:Npn \xparse_exp_declare_cmd_mixed:Nn #1#2 { - \exp_args:NnV \tl_if_in:nnTF { l m u } \l_xparse_last_arg_tl { - \xparse_exp_declare_cmd_mixed_aux:Nn #1 {#2} - }{ - \msg_kernel_error:nn { xparse } { expandable-ending-optional } - } -} -\cs_new:Npn \xparse_exp_declare_cmd_mixed_aux:Nn #1#2 { - \cs_set_nopar:Npx #1 { - \exp_not:c { \token_to_str:N #1 1 } x \exp_not:N \q_xparse - } - \cs_set_nopar:cpx { - \token_to_str:N #1 \int_eval:n { \l_xparse_total_args_int + 1 } - } x ##1 \q_xparse { - \exp_not:c { \token_to_str:N #1 } ##1 - } - \cs_generate_from_arg_count:cNnn - { \token_to_str:N #1 } \cs_set:Npn \l_xparse_total_args_int {#2} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_exp_prepare_function:n} -%\begin{macro}[aux]{\xparse_exp_prepare_function_aux:n} -% A couple of early validation tests. Processors are forbidden, as are -% \texttt{g}, \texttt{l} and \texttt{u} arguments (the later more for -% ease than any technical reason). -% \begin{macrocode} -\cs_new:Npn \xparse_exp_prepare_function:n #1 { - \bool_set_false:N \l_xparse_error_bool - \tl_if_in:nnT {#1} { > } { - \msg_kernel_error:nnx { xparse } { processor-in-expandable } {#1} - \bool_set_true:N \l_xparse_error_bool - } - \tl_if_in:nnT {#1} { g } { - \msg_kernel_error:nnx { xparse } { grouped-in-expandable } - { g } {#1} - \bool_set_true:N \l_xparse_error_bool - } - \tl_if_in:nnT {#1} { G } { - \msg_kernel_error:nnx { xparse } { grouped-in-expandable } - { G } {#1} - \bool_set_true:N \l_xparse_error_bool - } - \bool_if:NF \l_xparse_error_bool { - \xparse_exp_prepare_function_aux:n {#1} - } -} -\cs_new:Npn \xparse_exp_prepare_function_aux:n #1 { - \cs_set_eq:NN \xparse_prepare_next:w \xparse_exp_prepare_function:N - \cs_set_eq:NN \xparse_exp_set:cpx \cs_set_nopar:cpx - \bool_set_false:N \l_xparse_long_bool - \int_zero:N \l_xparse_m_args_int - \int_zero:N \l_xparse_total_args_int - \tl_if_in:nnT {#1} { + } { - \bool_set_true:N \l_xparse_long_bool - \cs_set_eq:NN \xparse_exp_set:cpx \cs_set:cpx - } - \xparse_exp_prepare_function:N #1 \q_nil -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_exp_prepare_function:N} -%\begin{macro}[aux]{\xparse_exp_prepare_function_long:N} -%\begin{macro}[aux]{\xparse_exp_prepare_function_short:N} -% Preparing functions is a case of reading the signature, as in the -% normal case. However, everything has to be either short or long, and -% so there is an extra step to make sure that once one \texttt{+} has -% been seen everything has one. That detour then takes us back to -% a standard looping concept. -% \begin{macrocode} -\cs_new:Npn \xparse_exp_prepare_function:N #1 { - \bool_if:NTF \l_xparse_long_bool { - \xparse_exp_prepare_function_long:N #1 - }{ - \xparse_exp_prepare_function_short:N #1 - } -} -\cs_new:Npn \xparse_exp_prepare_function_long:N #1 { - \quark_if_nil:NF #1 { - \str_if_eq:nnTF {#1} { + } { - \xparse_exp_prepare_function_short:N - }{ - \msg_kernel_error:nn { xparse } { expandable-inconsistent-long } - \xparse_exp_prepare_function_short:N #1 - } - } -} -\cs_new:Npn \xparse_exp_prepare_function_short:N #1 { - \quark_if_nil:NF #1 { - \prop_if_in:NnTF \c_xparse_shorthands_prop {#1} { - \prop_get:NnN \c_xparse_shorthands_prop {#1} \l_xparse_tmp_tl - \bool_if:NT \l_xparse_long_bool { - \tl_put_left:Nn \l_xparse_tmp_tl { + } - } - \exp_last_unbraced:NV \xparse_exp_prepare_function:N - \l_xparse_tmp_tl - }{ - \int_incr:N \l_xparse_total_args_int - \xparse_exp_check_and_add:N #1 - } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_exp_set:cpx} -% A short-cut to save constantly re-testing \cs{l_xparse_long_bool}. -% \begin{macrocode} -\cs_new_eq:NN \xparse_exp_set:cpx \cs_set_nopar:cpx -% \end{macrocode} -%\end{macro} -% -%\subsection{Access to the argument specification} -% -%\begin{macro}{\xparse_get_arg_spec:N} -%\begin{macro}{\xparse_get_arg_spec:n} -%\begin{macro}{\ArgumentSpecification} -% Recovering the argument specification is also trivial, using the -% \cs{tl_set_eq:cN} function. -% \begin{macrocode} -\cs_new_protected:Npn \xparse_get_arg_spec:N #1 { - \cs_if_exist:cTF { l_xparse_ \token_to_str:N #1 _arg_spec_tl } - { - \tl_set_eq:Nc \ArgumentSpecification - { l_xparse_ \token_to_str:N #1 _arg_spec_tl } - } - { - \msg_kernel_error:nnx { xparse } { unknown-document-command } - { \token_to_str:N #1 } - } -} -\cs_new_protected:Npn \xparse_get_arg_spec:n #1 { - \cs_if_exist:cTF { l_xparse_ #1 _arg_spec_tl } - { - \tl_set_eq:Nc \ArgumentSpecification { l_xparse_ #1 _arg_spec_tl } - } - { - \msg_kernel_error:nnx { xparse } - { unknown-document-environment } {#1} - } -} -\tl_new:N \ArgumentSpecification -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xparse_show_arg_spec:N} -%\begin{macro}{\xparse_show_arg_spec:n} -% Showing the argument specification simply means finding it and then -% calling the \cs{tl_show:c} function. -% \begin{macrocode} -\cs_new_protected:Npn \xparse_show_arg_spec:N #1 { - \cs_if_exist:cTF { l_xparse_ \token_to_str:N #1 _arg_spec_tl } - { - \tl_set_eq:Nc \ArgumentSpecification - { l_xparse_ \token_to_str:N #1 _arg_spec_tl } - \tl_show:N \ArgumentSpecification - } - { - \msg_kernel_error:nnx { xparse } { unknown-document-command } - { \token_to_str:N #1 } - } -} -\cs_new_protected:Npn \xparse_show_arg_spec:n #1 { - \cs_if_exist:cTF { l_xparse_ #1 _arg_spec_tl } - { - \tl_set_eq:Nc \ArgumentSpecification { l_xparse_ #1 _arg_spec_tl } - \tl_show:N \ArgumentSpecification - } - { - \msg_kernel_error:nnx { xparse } - { unknown-document-environment } {#1} - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\subsection{Messages} -% -% Some messages intended as errors. -% \begin{macrocode} -\msg_kernel_new:nnnn { xparse } { command-already-defined } - { Command~'#1'~already~defined! } - { - You~have~used~\token_to_str:N \NewDocumentCommand \\ - with~a~command~that~already~has~a~definition.\\ - Perhaps~you~meant~\token_to_str:N \RenewDocumentCommand. - } -\msg_kernel_new:nnnn { xparse } { command-not-yet-defined } - { Command ~'#1'~not~yet~defined! } - { - You~have~used~\token_to_str:N \RenewDocumentCommand \\ - with~a~command~that~was~never~defined.\\ - Perhaps~you~meant~\token_to_str:N \NewDocumentCommand. - } -\msg_kernel_new:nnnn { xparse } { environment-already-defined } - { Environment~'#1'~already~defined! } - { - You~have~used~\token_to_str:N \NewDocumentEnvironment \\ - with~a~command~that~already~has~a~definition.\\ - Perhaps~you~meant~\token_to_str:N \RenewDocumentEnvironment. - } -\msg_kernel_new:nnnn { xparse } { environment-not-yet-defined } - {Environment~'#1'~not~yet~defined! } - { - You~have~used~\token_to_str:N \RenewDocumentEnvironment \\ - with~a command~that~was~never~defined.\\ - Perhaps~you~meant~\token_to_str:N \NewDocumentEnvironment. - } -\msg_kernel_new:nnnn { xparse } { expandable-ending-optional } - { - Signature~for~expandable~command~ends~with \\ - optional~argument~\msg_line_context:. - } - { - Expandable~commands~must~have~a~final~mandatory~argument \\ - (or~no arguments~at all).~You~cannot~have~a~terminal~optional \\ - argument~with~expandable~commands. - } -\msg_kernel_new:nnnn { xparse } { expandable-inconsistent-long } - { - Inconsistent~handling~of~long~arguments~for \\ - expandable~command~\msg_line_context:. - } - { - The~arguments~for~an~expandable~command~must~either~all~be \\ - short~or~all~be~long.~You~have~tried~to~mix~the~two~types. - } -\msg_kernel_new:nnnn { xparse } { grouped-in-expandable } - {% - Argument~specifier~'#1'~forbidden~in~expandable~commands~ - \msg_line_context:. - } - { - Argument~specification~'#2'~contains~the~optional~grouped~ - argument~#1':\\ - this~is only~supported~for~standard~robust~functions. - } -\msg_kernel_new:nnnn { xparse } { processor-in-expandable } - { - Argument~processors~cannot~be~used \\ - with~expandable~functions~\msg_line_context:. - } - { - Argument~specification~'#1'~contains~a~processor~function:\\ - this~is~only~supported~for~standard~robust~functions. - } -\msg_kernel_new:nnnn { xparse } { split-excess-tokens } - { Too~many~'#1'~tokens~when~trying~to~split~argument. } - { - LaTeX~was~asked~to~split~the~input~'#3'\\ - at~each~occurrence~of~the~token~'#1',~up~to~a~maximum~of~#2~tokens.\\ - There~were~too~many~'#1'~tokens. - } -\msg_kernel_new:nnnn { xparse } { unknown-argument-type } - { Unknown~argument~type~'#1'~replaced~by~'m'.~Fingers~crossed~... } - { - The~letter~#1'~does~not~specify~a~known~argument~type.\\ - I'm~assuming~you~want~a~standard~mandatory~argument~(type~'m'). - } -\msg_kernel_new:nnnn { xparse } { unknown-document-command } - { Unknown~document~command~'#1'. } - { - You~have~asked~for~the~argument~specification~for~a~command~'#1',~ - but~this~is~not~a~document~command. - } -\msg_kernel_new:nnnn { xparse } { unknown-document-environment } - { Unknown~document~environment~'#1'. } - { - You~have~asked~for~the~argument~specification~for~a~command~'#1',~ - but~this~is~not~a~document~environment. - } -% \end{macrocode} -% -% Intended more for information. -% \begin{macrocode} -\msg_kernel_new:nnn { xparse } { define-command } - { - Defining~document~command~#1\\ - with~arg.~spec.~'#2'~\msg_line_context:. - } -\msg_kernel_new:nnn { xparse } { define-environment } - { - Defining~document~environment~'#1'\\ - with~arg.~spec.~'#2'~\msg_line_context:. - } -\msg_kernel_new:nnn { xparse } { redefine-command } - { - Redefining~document~command~#1\\ - with~arg.~spec.~'#2'~\msg_line_context:. - } -\msg_kernel_new:nnn { xparse } { redefine-environment } - { - Redefining~document~environment~'#1'\\ - with~arg.~spec.~'#2'~\msg_line_context:. - } -% \end{macrocode} -% -%\subsection{User functions} -% -% The user functions are more or less just the internal functions -% renamed. -% -%\begin{macro}{\BooleanFalse} -%\begin{macro}{\BooleanTrue} -% Design-space names for the Boolean values. -% \begin{macrocode} -\cs_new_eq:NN \BooleanFalse \c_false_bool -\cs_new_eq:NN \BooleanTrue \c_true_bool -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\DeclareDocumentCommand} -%\begin{macro}{\NewDocumentCommand} -%\begin{macro}{\RenewDocumentCommand} -%\begin{macro}{\ProvideDocumentCommand} -% The user macros are pretty simple wrappers around the internal ones. -% \begin{macrocode} -\cs_new_protected:Npn \DeclareDocumentCommand #1#2#3 { - \xparse_declare_cmd:Nnn #1 {#2} {#3} -} -\cs_new_protected:Npn \NewDocumentCommand #1#2#3 { - \cs_if_exist:NTF #1 { - \msg_kernel_error:nnx { xparse } { command-already-defined } - { \token_to_str:N #1 } - }{ - \xparse_declare_cmd:Nnn #1 {#2} {#3} - } -} -\cs_new_protected:Npn \RenewDocumentCommand #1#2#3 { - \cs_if_exist:NTF #1 { - \xparse_declare_cmd_aux:Nnn #1 {#2} {#3} - \msg_kernel_info:nnxx { xparse } { redefine-command } - { \token_to_str:N #1 } { \exp_not:n {#2} } - }{ - \msg_kernel_error:nnx { xparse } { command-not-yet-defined } - { \token_to_str:N #1 } - } -} -\cs_new_protected:Npn \ProvideDocumentCommand #1#2#3 { - \cs_if_exist:NF #1 { - \xparse_declare_cmd:Nnn #1 {#2} {#3} - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\DeclareDocumentCommandImplementation} -%\begin{macro}{\DeclareDocumentCommandInterface} -% The separate implementation/interface system is again pretty simple -% to create at the outer layer. -% \begin{macrocode} -\cs_new_protected:Npn \DeclareDocumentCommandImplementation #1#2#3 { - \xparse_declare_cmd_implementation:nNn {#1} #2 {#3} -} -\cs_new_protected:Npn \DeclareDocumentCommandInterface #1#2#3 { - \xparse_declare_cmd_interface:Nnn #1 {#2} {#3} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\DeclareDocumentEnvironment} -%\begin{macro}{\NewDocumentEnvironment} -%\begin{macro}{\RenewDocumentEnvironment} -%\begin{macro}{\ProvideDocumentEnvironment} -% Very similar for environments. -% \begin{macrocode} -\cs_new_protected:Npn \DeclareDocumentEnvironment #1#2#3#4 { - \xparse_declare_env:nnnn {#1} {#2} {#3} {#4} -} -\cs_new_protected:Npn \NewDocumentEnvironment #1#2#3#4 { -%</initex|package> -%<*initex> - \cs_if_exist:cTF { environment_begin_ #1 :w } { -%</initex> -%<*package> - \cs_if_exist:cTF {#1} { -%</package> -%<*initex|package> - \msg_kernel_error:nnx { xparse } - { environment-already-defined } {#1} - }{ - \xparse_declare_env:nnnn {#1} {#2} {#3} {#4} - } -} -\cs_new_protected:Npn \RenewDocumentEnvironment #1#2#3#4 { -%</initex|package> -%<*initex> - \cs_if_exist:cTF { environment_begin_ #1 :w } { -%</initex> -%<*package> - \cs_if_exist:cTF {#1} { -%</package> -%<*initex|package> - \xparse_declare_env:nnnn {#1} {#2} {#3} {#4} - }{ - \msg_kernel_error:nnx { xparse } - { environment-not-yet-defined } {#1} - } -} -\cs_new_protected:Npn \ProvideDocumentEnvironment #1#2#3#4 { -%</initex|package> -%<*initex> - \cs_if_exist:cF { environment_begin_ #1 :w } { -%</initex> -%<*package> - \cs_if_exist:cF { #1 } { -%</package> -%<*initex|package> - \xparse_declare_env:nnnn {#1} {#2} {#3} {#4} - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\DeclareExpandableDocumentCommand} -% The expandable version of the basic function is essentially the same. -% \begin{macrocode} -\cs_new_protected:Npn \DeclareExpandableDocumentCommand #1#2#3 { - \xparse_exp_declare_cmd:Nnn #1 {#2} {#3} -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}[TF]{\IfBoolean} -% The logical \meta{true} and \meta{false} statements are just the -% normal \cs{c_true_bool} and \cs{c_false_bool}, so testing for them is -% done with the \cs{bool_if:NTF} functions from \textsf{l3prg}. -% \begin{macrocode} -\cs_new_eq:NN \IfBooleanTF \bool_if:NTF -\cs_new_eq:NN \IfBooleanT \bool_if:NT -\cs_new_eq:NN \IfBooleanF \bool_if:NF -% \end{macrocode} -%\end{macro} -% -%\begin{macro}[TF]{\IfNoValue} -% Simple re-naming. -% \begin{macrocode} -\cs_new_eq:NN \IfNoValueF \xparse_if_no_value:nF -\cs_new_eq:NN \IfNoValueT \xparse_if_no_value:nT -\cs_new_eq:NN \IfNoValueTF \xparse_if_no_value:nTF -% \end{macrocode} -%\end{macro} -%\begin{macro}[TF]{\IfValue} -% Inverted logic. -% \begin{macrocode} -\cs_set:Npn \IfValueF { \xparse_if_no_value:nT } -\cs_set:Npn \IfValueT { \xparse_if_no_value:nF } -\cs_set:Npn \IfValueTF #1#2#3 { - \xparse_if_no_value:nTF {#1} {#3} {#2} -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\NoValue} -% The marker for no value being give: this can be typeset safely. -% This is coded by hand as making it \cs{protected} ensures that it -% will not turn into anything else by accident. -% \begin{macrocode} -\cs_new_protected:Npn \NoValue { -NoValue- } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\ProcessedArgument} -% Processed arguments are returned using this name, which is reserved -% here although the definition will change. -% \begin{macrocode} -\cs_new:Npn \ProcessedArgument { } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\ReverseBoolean} -% A processor to reverse the logic for token detection. -% \begin{macrocode} -\cs_new_eq:NN \ReverseBoolean \_xparse_bool_reverse:N -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\SplitArgument} -%\begin{macro}{\SplitList} -% Another simple copy. -% \begin{macrocode} -\cs_new_eq:NN \SplitArgument \_xparse_split_argument:nnn -\cs_new_eq:NN \SplitList \_xparse_split_list:nn -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\GetDocumentCommandArgSpec} -%\begin{macro}{\GetDocumentEnvironmentArgSpec} -%\begin{macro}{\ShowDocumentCommandArgSpec} -%\begin{macro}{\ShowDocumentEnvironmentArgSpec} -% More simple mappings. -% \begin{macrocode} -\cs_new_eq:NN \GetDocumentCommandArgSpec \xparse_get_arg_spec:N -\cs_new_eq:NN \GetDocumentEnvironmmentArgSpec \xparse_get_arg_spec:n -\cs_new_eq:NN \ShowDocumentCommandArgSpec \xparse_show_arg_spec:N -\cs_new_eq:NN \ShowDocumentEnvironmentArgSpec \xparse_show_arg_spec:n -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -% \begin{macrocode} -%</initex|package> -% \end{macrocode} -% -% \end{implementation} -% -% \PrintIndex diff --git a/Master/texmf-dist/source/latex/xpackages/xbase/xtemplate.dtx b/Master/texmf-dist/source/latex/xpackages/xbase/xtemplate.dtx deleted file mode 100644 index 0ad4f0699ab..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xbase/xtemplate.dtx +++ /dev/null @@ -1,3383 +0,0 @@ -% \iffalse -%% File: xtemplate.dtx (C) Copyright 1999-2001 David Carlisle, Frank Mittelbach -%% (C) Copyright 2004-2010 Frank Mittelbach, LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%%1 -%% This file is part of the ``xbase bundle'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -% -%<*driver|package> -\RequirePackage{l3names} -%</driver|package> -%\fi -\GetIdInfo$Id: xtemplate.dtx 2115 2011-01-03 21:46:30Z joseph $ - {Prototype document functions} -%\iffalse -%<*driver> -%\fi -\ProvidesFile{\filename.\filenameext} - [\filedate\space v\fileversion\space\filedescription] -%\iffalse -\documentclass[full]{l3doc} -\ExplSyntaxOn -% SYNTAX environments getting ugly. This helps: -\cs_if_exist:NT \g_doc_syntax_dim { - \dim_set:Nn \g_doc_syntax_dim {\textwidth} -} -\ExplSyntaxOff -\usepackage{booktabs} -\begin{document} - \DocInput{xtemplate.dtx} -\end{document} -%</driver> -% \fi -% -% \title{The \textsf{xtemplate} package\thanks{This file -% has version number \fileversion, last -% revised \filedate.}} -% \author{\Team} -% \date{\filedate} -% \maketitle -% -% \begin{documentation} -% -% \section{Introduction} -% -% There are three broad `layers' between putting down ideas into a source file -% and ending up with a typeset document. These layers of document writing are: -% \begin{enumerate} -% \item Authoring of the text, with mark-up -% \item Document layout design -% \item Implementation (with \TeX\ programming) of the design -% \end{enumerate} -% We write the text as an author, and we see the visual output of the design -% after the document is generated; the \TeX\ implementation in the middle is -% the glue between the two. -% -% \LaTeX's greatest success has been to standardise a system of mark-up that -% balances the trade-off between ease of reading and ease of writing to suit -% almost all forms of technical writing. It's -% other original strength was a good background in typographical design; while -% the standard \LaTeXe\ classes look somewhat dated now in terms of their -% visual design, their typography is generally sound. (Barring the occasional -% minor faults.) -% -% However, \LaTeXe\ has always lacked a standard approach to customising -% the visual design of a document. Changing the looks of the standard classes -% involved either: -% \begin{itemize} -% \item Creating a new version of the implementation code of the class and -% editing it. -% \item Loading one of the many packages to customise certain elements of -% the standard classes. -% \item Loading a completely different document class, such as -% \textsf{KOMA-Script} or \textsf{memoir}, that allows easy -% customisation. -% \end{itemize} -% All three of these approaches have their drawbacks and learning curves. -% -% The idea behind \pkg{xtemplate} is to cleanly separate the three layers -% introduced at the beginning of this section, so that document authors who -% are not programmers can easily change the design of their documents. -% \pkg{xtemplate} also makes it easier for \LaTeX\ programmers to provide -% their own customisations on top of a pre-existing class. -% -% \section{What is a document?} -% -% Besides the textual content of the words themselves, the source file of a -% document contains mark-up elements that add structure to the document. -% These elements include sectional divisions, figure/table captions, -% lists of various sorts, theorems/proofs, and so on. -% The list will be different for every document that can be written. -% -% Each element can be represented logically without worrying about the -% formatting, with mark-up such as \cmd\section, \cmd\caption, -% "\begin{enumerate}" and so on. -% The output of each one of these document -% elements will be a typeset representation of the information marked up, and -% the visual arrangement and design of these elements can vary widely in -% producing a variety of desired outcomes. -% -% For each type of document element, there may be design variations that -% contain the same sort of information but present it in slightly different -% ways. -% For example, the difference between a numbered and an unnumbered -% section, \cmd\section\ and \cmd\section"*", or the difference between an -% itemised list or an enumerated list. -% -% There are three distinct layers in the definition of `a document' at this -% level: -% \begin{enumerate} -% \item Semantic elements such as the ideas of sections and lists. -% \item A set of design solutions for representing these elements visually. -% \item Specific variations for these designs that represent the elements in the document. -% \end{enumerate} -% In the parlance of the \pkg{xtemplate} package, we call these object types, -% templates, and instances, and they are discussed below in -% sections \ref{sec:objects}, \ref{sec:templates}, and~\ref{sec:instances}, -% respectively. -% -% \section {Objects, templates, and instances} -% -% By formally declaring our document to be composed of mark-up elements -% grouped into objects, which are interpreted and typeset with a set of -% templates, each of which has one or more instances with which to compose each -% and every semantic unit of the text, we can cleanly separate -% the components of document construction. -% The \pkg{xtemplate} package provides the tools to do this. -% -% \subsection{Object types}\label{sec:objects} -% -% An `object type' (or sometimes just `object') is an abstract idea of a -% document element that takes a -% fixed number of arguments corresponding to the information from the -% document author that it is representing. -% A sectioning object, for example, might take three inputs: `title', -% `short title', and `label'. -% -% Any given document class will define which object types are to be used in -% the -% document, and any template of a given object type can be used to generate an -% instance for the object. -% (Of course, different templates will produce different typeset -% representations, but the underlying content will be the same.) -% -% \begin{function}{\DeclareObjectType} -% \begin{syntax} -% "\DeclareObjectType" \Arg{name} \Arg{Nargs} -% \end{syntax} -% This function defines an \emph{object type}, -% where \meta{name} is the name of the object type and \meta{Nargs} is the number of -% arguments an instance of this type should take. For example, -% \begin{quote} -% \begin{verbatim} -% \DeclareObjectType{sectioning}{3} -% \end{verbatim} -% \end{quote} -% Note that object types are global entities: \cs{DeclareObjectType} -% will apply outside of any \TeX\ grouping in force when it is -% called. -% \end{function} -% -% \subsection{Templates}\label{sec:templates} -% -% A \emph{template} is a generalised design solution for representing the -% information of a specified \emph{object type}. -% Templates that do the same thing~--- e.g., two completely different ways of -% printing a chapter heading~--- are grouped together by their object type and -% given -% separate names. -% There are two important parts to a template: -% \begin{itemize} -% \item The parameters it takes to vary the design it is producing. -% \item The implementation of the design. -% \end{itemize} -% As a document author or designer does not care about the implementation -% but rather only the interface to the template, these two aspects of the template -% definition are split into two independent declarations, \cmd\DeclareTemplateInterface\ -% and \cmd\DeclareTemplateCode. -% -% \begin{function}{\DeclareTemplateInterface} -% \par -% \begin{syntax} -% "\DeclareTemplateInterface" \Arg{object type} \Arg{template} \Arg{Nargs} -% "{" -% " "<name of key 1> ":" <key type 1> "," -% " "<name of key 2> ":" <key type 2> "=" <optional default> "," -% " ..." -% "}" -% \end{syntax} -% The \meta{name of keys} can be any string of \textsc{ascii} characters (with -% the exception of ":", "=" and "," as they are part of the syntax); -% we recommend only using lower case letters and dashes, however. -% Note that spaces in key names are ignored, so that key names can be -% spaced out for ease of reading without affecting the recognition of -% keys inside and outside of code blocks. -% -% The <key types> define what sort of input the key accepts, such as `boolean', -% `integer', and so on. The complete list of possible <key types> is shown in -% \autoref{tab:keytypes}. -% -% Like objects, templates are global entities: both -% \cs{DeclareTemplateInterface} \cs{DeclareTemplateCode} will apply -% outside of any \TeX\ grouping in force when it is called. -% \end{function} -% -% \begin{table}[p] -% \begin{tabular}{@{}ll@{}} -% \toprule -% Key Type & Description of input \\ -% \midrule -% "boolean" & "true" or "false" \\ -% "choice "\Arg{choices} & A list of pre-defined choices \\ -% "code" & Generalised key type; use "#1" as the input to the key \\ -% "commalist" & A comma-separated list of arbitrary items \\ -% "function "$N$ & A function definition with $N$ arguments -% ($N$ from $0$ to $9$) \\ -% "instance "\Arg{name} & An instance of type \meta{name} \\ -% "integer" & An integer expression (e.g., {\small "(1 + 5)/2"}) \\ -% "length" & A dimension expression (e.g., {\small "3pt + 2cm"}) \\ -% "skip" & A dimension expression with glue -% (e.g., {\small "3pt plus 2pt minus 1pt"}) \\ -% "tokenlist" & A `token list' input; any text or commands \\ -% \bottomrule -% \end{tabular} -% \caption{`Key types' for defining template interfaces with \cs{DeclareTemplateInterface}.} -% \label{tab:keytypes} -% \end{table} -% -% \begin{table}[p] -% \begin{tabular}{@{}lcl@{}} -% \toprule -% Key Type && Description of binding \\ -% \midrule -% "boolean" &$\star$& Boolean variable; e.g., "\l_tmpa_bool" \\ -% "choice" && "{" \meta{choice\,$_1$} "=" \meta{code\,$_1$} "," \meta{choice\,$_2$} "=" \meta{code\,$_2$} "," \dots "}" \\ -% "code" && \meta{code} ; use "#1" as the input to the key \\ -% "commalist" &$\star$& Comma-list variable; e.g., "\l_tmpa_clist" \\ -% "function" &$\star$& Function w/ $N$ arguments; e.g., "\use_i:nn" \\ -% "instance" &$\star$& An instance variable; e.g., "\g_foo_instance" \\ -% "integer" &$\star$& Integer variable; e.g., "\l_tmpa_int" \\ -% "length" &$\star$& Dimension variable; e.g., "\l_tmpa_dim" \\ -% "skip" &$\star$& Skip variable; e.g., "\l_tmpa_skip" \\ -% "tokenlist" &$\star$& Token list variable; e.g., "\l_tmpa_tl" \\ -% \bottomrule -% \end{tabular} -% \caption{Bindings required for different key types when defining template implementations with \cs{DeclareTemplateCode}. Starred entries may be prefixed with the keyword \texttt{global} to make a global assignment.} -% \label{tab:keyvariables} -% \end{table} -% -% \begin{function}{\DeclareTemplateCode} -% \par -% \begin{syntax} -% "\DeclareTemplateCode" \Arg{object type} \Arg{template} \Arg{Nargs} -% "{" -% " "<name of key 1> "=" <internal variable or code 1> "," -% " "<name of key 2> "=" <internal variable or code 2> "," -% " ..." -% "}{" -% " "\meta{implementation code} -% " \AssignTemplateKeys" -% " "\meta{more implementation code} -% "}" -% \end{syntax} -% After the keys have been declared with "\DeclareTemplateInterface", the -% implementation binds each <name of key> with an <internal variable> -% (for key types such as `integer', `length', `tokenlist', etc.) -% \unskip\footnote{^^A -% It is possible, if you wish, to use the same variable for multiple keys; -% this allows `key synonyms' to be defined such as |color| and |colour| which -% can perform the same function in the template implementation.} -% or with a certain <code> fragment to execute, which will be described below. -% -% Assignments to variables which should be made globally are indicated by adding the -% word \texttt{global} before the variable name: -% -% \begin{syntax} -% " "<name of key 1> "=" <internal variable 1> "," -% " "<name of key 2> "=" global <internal variable 2> "," -% \end{syntax} -% -% The key types "choices" and "code" do not take variable bindings; instead, -% fragments of code are defined which are executed instead. The complete list -% of bindings taken by different key types is shown in \autoref{tab:keyvariables}. -% The "choices" key type is explained fully in \autoref{sec:choices-key} below. -% -% \begin{function}{\AssignTemplateKeys} -% \par -% The final argument of \cs{DeclareTemplateCode} contains the <implementation code> -% for the template design, taking arguments |#1|, |#2|, etc.\ according to the number of -% arguments allowed, <Nargs>. \cs{AssignTemplateKeys} must be -% executed in order to assign variables and perform code executions according -% to the keys set. -% \end{function} -% \end{function} -% -% \subsection{Multiple choices} -% \label{sec:choices-key} -% -% The \texttt{choice} keytype implements multiple choice input. At the -% interface level, only the list of valid choices is needed: -% \begin{verbatim} -% \DeclareTemplateInterface { foo } { bar } 0 { -% key-name : choice { A,B,C } -% } -% \end{verbatim} -% where the choices are given as a comma-list (which must therefore -% be wrapped in braces). A default value can also be given: -% \begin{verbatim} -% \DeclareTemplateInterface { foo } { bar } 0 { -% key-name : choice { A,B,C } = A -% } -% \end{verbatim} -% -% At the implementation level, each choice is associated with code, -% using a nested key--value list. -% \begin{verbatim} -% \DeclareTemplateCode { foo } { bar } 0 { -% key-name = { -% A = Code-A , -% B = Code-B , -% C = Code-C , -% } -% } { ... } -% \end{verbatim} -% The two choice lists should match, but in the implementation a -% special \texttt{unknown} choice is also available. This can be used -% to ignore values and implement an `else' branch: -% \begin{verbatim} -% \DeclareTemplateCode { foo } { bar } 0 { -% key-name = { -% A = Code-A , -% B = Code-B , -% C = Code-C , -% unknown = Else-code -% } -% } { ... } -% \end{verbatim} -% The \texttt{unknown} entry must be the last one given, and should -% \emph{not} be listed in the interface part of of the template. -% -% For keys which accept the values "true" and "false" both the boolean -% and choice key types can be used. As template interfaces are intended -% to prompt clarity at the design level, the boolean key type should be -% favoured, with the choice type reserved for keys which take arbitrary -% values. -% -% \subsection{Instances}\label{sec:instances} -% -% After a template is defined it still needs to be put to use. -% The parameters that it expects need to be defined before it can be used in -% a document. -% Every time a template has parameters given to it, an \emph{instance} is -% created, and this is the code that ends up in the document to perform the -% typesetting of whatever pieces of information are input into it. -% -% For example, a template might say `here is a section with or without a -% number that might be centred or left aligned and print its contents in a -% certain font of a certain size, with a bit of a gap before and after it' -% whereas an instance declares `this is a section with a number, which is centred and set -% in 12pt italic with a 10pt skip before and a 12pt skip after it'. -% -% Therefore, an instance is just a frozen version of a template with specific -% settings as chosen by the designer. -% -% \begin{function}{\DeclareInstance} -% \par -% \begin{syntax} -% "\DeclareInstance" \Arg{object type} \Arg{instance} \Arg{template} \Arg{parameters} -% \end{syntax} -% The name of the instance being declared is <instance>, with <parameters> -% the keyval input to set some or all of the <template> keys to specific values. -% -% Here is a hypothetical example, where |sectioning| might be an object to be used -% for document subdivisions, |section-num| an instance referring to a `numbered section', -% and |basic| a template for |sectioning| that performs just the basic layout, say: -% \begin{quote} -% \begin{verbatim} -% \DeclareInstance{sectioning}{section-num}{basic} { -% numbered = true , -% justification = center , -% font = \normalsize\itshape , -% before-skip = 10pt , -% after-skip = 12pt , -% } -% \end{verbatim} -% \end{quote} -% \end{function} -% -% -% \subsection{Document interface} -% -% After the instances have been chosen, document commands must be declared to -% use those instances in the document. \cmd\UseInstance\ calls instances directly, -% and this command should be used internally in document-level mark-up. -% -% \begin{function}{\UseInstance} -% \par -% \begin{syntax} -% "\UseInstance" \Arg{object type} \Arg{instance} <arguments> -% \end{syntax} -% \end{function} -% -% It will take as many arguments as were defined for the object type. -% -% Use \textsf{xparse} to declare the document commands in terms of instances. -% Another hypothetical example: -% \begin{quote} -% \begin{verbatim} -% \DeclareDocumentCommand\section{ som }{ -% \IfBooleanTF #1 -% { -% \UseInstance{sectioning}{section-nonum}{#2}{#3} -% } -% { -% \UseInstance{sectioning}{section-num}{#2}{#3} -% } -% } -% \end{verbatim} -% \end{quote} -% -% \begin{function}{\UseTemplate} -% \par -% \begin{syntax} -% "\UseTemplate" \Arg{object type} \Arg{template} \Arg{settings} <arguments> -% \end{syntax} -% There are occasions where creating an instance of a template does not -% make sense, as it will only be used once. In this case, templates can -% be used directly, with the key settings given as an argument to the -% \cs{UseTemplate} function. This will also work when giving an argument -% to a key which needs an instance. For example, if we have an key -% \texttt{instance-key} which expects an instance of \texttt{object2}, -% then we can either declare an instance: -% \begin{quote} -% \begin{verbatim} -% \DeclareInstance {object2} {template2} {temp-instance} { -% <settings> -% } -% \DeclareInstance {object} {template} {instance} { -% instance-key = temp-instance -% } -% \end{verbatim} -% \end{quote} -% or use the template directly: -% \begin{quote} -% \begin{verbatim} -% \DeclareInstance {object} {template} {instance} { -% instance-key = \UseTemplate {object2} {template2} {<settings>} -% } -% \end{verbatim} -% \end{quote} -% Which is the best approach will depend on the exact nature of the -% situation. -% \end{function} -% -% \subsection{Summaries} -% -% For the document designer: -% \begin{itemize} -% \item The class will define which object types are used in a document. -% \item The class will define user commands that contain the required -% instances that the document must use. -% \item Having knowledge of a variety of suitable templates, for each -% required instance a template can be selected and instantiated based on the -% parameters defined by \cmd\DeclareTemplateInterface. -% \end{itemize} -% -% For the class programmer: -% \begin{itemize} -% \item Define the different object types of document elements: what the semantics -% are and what information is required. -% \item Create document commands to call instances that fulfil the needs of -% the object types. -% \item Implement the required templates to produce typeset implementations -% of the document elements and instantiate them with the appropriate names. -% \end{itemize} -% -% \section{Instances in different contexts} -% -% We may wish the behaviour of an instance to change as it is used in varying contexts. -% For example, in the frontmatter of a document, section numbering is -% different. Semantics are the same, but the typesetting changes. But we want -% to use the same user commands, and hence the same instance names. -% -% \emph{Collections} allow us to define multiple instances that we can switch -% between. Collections are activated with \cmd\UseCollection. -% -% At present, it is not clear whether collections fully address the -% issues they target. They should therefore be regarded as highly -% experimental, and may be changed or withdrawn in the future if -% it appears that they do not work well enough! -% -% \begin{function}{\DeclareCollectionInstance} -% -% \begin{syntax} -% "\DeclareCollectionInstance" \Arg{collection} \Arg{object type} \Arg{instance} \Arg{template}\\\hfill \Arg{parameters} -% \end{syntax} -% \end{function} -% -% \begin{function}{\UseCollection} -% \begin{syntax} -% "\UseCollection" \Arg{object type} \Arg{collection} -% \end{syntax} -% \end{function} -% -% The instance declared will override another instance of the same name when -% the collection is active. Note that a collection instance can only be declared if -% the \emph{original} instance already exists. -% -% An example might be: -% \begin{verbatim} -% \UseCollection{sectioning}{frontmatter} -% \section{Nomenclature} -% ... -% \UseCollection{sectioning}{default} -% \section{Introduction} -% \end{verbatim} -% In both cases, the same instance (perhaps `"section-num"') is being used inside -% the \cs{section}. But \cs{DeclareCollectionInstance} will have been used for -% the `"frontmatter"' and override the instance that is used in the default case. -% -% \section{Bits 'n' pieces} -% -% \subsection{Does an instance exist?} -% -% \begin{function}{\IfInstanceExist / (TF)} -% -% \begin{syntax} -% "\IfInstanceExistTF" \Arg{object type} \Arg{instance} \Arg{true code} \Arg{false code} -% "\IfInstanceExistT" \Arg{object type} \Arg{instance} \Arg{true code} -% "\IfInstanceExistF" \Arg{object type} \Arg{instance} \Arg{false code} -% \end{syntax} -% Test if <instance> has been declared. This is useful when the use of an instance -% depends on some global variable, such as the current font selection. Designers -% or users can then implement specific designs for exact situations rather than -% relying on blanket parameter redefinitions. See \pkg{xfrac} for a good example of this. -% \end{function} -% -% \subsection{Changing the defaults of a template's keys} -% -% Template parameters may be assigned specific defaults for instances to use -% if the instance declaration doesn't explicit set those parameters. -% In some cases, the document designer will wish to edit these defaults to -% allow them to `cascade' to the instances. -% The alternative would be to set each parameter identically for each -% instance declaration, a tedious and error-prone process. -% \begin{function}{\EditTemplateDefaults} -% -% \begin{syntax} -% "\EditTemplateDefaults" \Arg{object type} \Arg{template} \Arg{new defaults} -% \end{syntax} -% \end{function} -% -% This command only takes effect for instances that have not yet been declared. -% Use "\EditInstance" if you wish to change an instance that already exists. -% -% \subsection{Small changes to an instance} -% -% When a designer creates an instance but the user wishes to slightly tweak -% it, it is convenient to not have to reset all of the (possibly many) -% parameters defining that instance and only override the specific parameter -% that should be changed. -% \begin{function}{\EditInstance|\EditCollectionInstance} -% \par -% \begin{syntax} -% "\EditInstance" \Arg{object type} \Arg{instance} \Arg{new parameters} -% "\EditCollectionInstance" \Arg{object type} \Arg{collection} \Arg{instance}\\\hfill \Arg{template} \Arg{new parameters} -% \end{syntax} -% These functions change the key settings of an instance of an object -% type. If the instance was derived from a template, this information -% is used to find the correct keys to use for the editing process. -% It may be convenient to use "\ShowInstanceValues" to inspect the values -% used to set the keys originally. -% \end{function} -% -% -% \subsection{Parameters evaluated now} -% -% \begin{function}{\EvaluateNow} -% \begin{syntax} -% "\EvaluteNow" \Arg{expression} -% \end{syntax} -% The standard method when creating an instance from a template is to -% evaluate the <expression> when the instance is used. However, it may -% be desirable to calculate the value when declared, which can be -% forced using \cs{EvaluateNow}. Currently, this functionality is -% regarded as experimental: the team have not found an example where it -% is actually needed, and so it may be dropped \emph{if} no good -% examples are suggested! -% \end{function} -% -% -% \subsection{Setting one key to the value of another} -% -% It is often useful to use the value of one key as the default for another. -% \begin{function}{\KeyValue} -% \begin{syntax} -% "\KeyValue" \Arg{key name} -% \end{syntax} -% This command is used as the argument to an instance key; it will set that -% key to the value of <key name> each time the instance is executed at run-time. -% Using \cs{KeyValue} means that the designer does not need to know -% how a particular key has been implemented. -% \end{function} -% -% \subsection{When template parameters should be frozen} -% -% A class designer may be inheriting templates declared by someone else, -% either third-party code or the \LaTeX\ kernel itself. Sometimes these -% templates will be overly general for the purposes of the document. The user -% should be able to customise parts of the template instances, but otherwise -% be restricted to only those parameters allowed by the designer. -% -% "\DeclareRestrictedTemplate" creates a derived version of a template for -% which certain parameters are frozen as specified but the remaining parameters are -% available to be set as usual in an instance declaration. -% -% \begin{function}{\DeclareRestrictedTemplate} -% \par -% \begin{syntax} -% |\DeclareRestrictedTemplate| \Arg{object type} \Arg{parent} \Arg{new template} \Arg{frozen parameters} -% \end{syntax} -% Defines <new template> based on template <parent> (of certain <object type>) -% with certain keys set and frozen as defined in <keyvals>. -% \end{function} -% -% \section{Getting information about templates and instances} -% -% \begin{function}{ -% \ShowTemplateCode | -% \ShowTemplateDefaults | -% \ShowTemplateKeytypes | -% \ShowTemplateVariables } -% -% \begin{syntax} -% "\ShowTemplateCode" \Arg{object type} \Arg{template} -% \end{syntax} -% These functions pause the typesetting and display -% in the console the various pieces of information for a template. -% \end{function} -% -% \begin{function}{ \ShowInstanceValues | \ShowCollectionInstanceValues } -% -% \begin{syntax} -% "\ShowInstanceValues" \Arg{object type} \Arg{instance} -% "\ShowCollectionInstanceValues" \Arg{object type} \Arg{collection} \Arg{instance} -% \end{syntax} -% These functions pause the typesetting and display in the console -% information about an instance or a collection instance. -% \end{function} -% -% Note that \pkg{xtemplate} uses various special key names internally. -% These all contain a space when stored (which normal keys do not: -% spaces are removed). The same applies to choices: these are stored -% internally as \texttt{\meta{key}~\meta{choice}}. These will show up -% when using the \cs{Show\ldots} functions. The design means that -% there is no danger of a clash between user keys and internal keys. -% Also, standard keys are stored with all letters detokenized, whereas -% the special keys use letters with category code $11$ (letter), again -% to avoid any issues. -% -% \section{Examples} -% -% (Nothing here yet.) -% -%\section{Code documentation} -% -%\subsection{Variables and constants} -% -%\begin{variable}{ -% \c_xtemplate_code_root_tl | -% \c_xtemplate_defaults_root_tl | -% \c_xtemplate_instances_root_tl | -% \c_xtemplate_keytypes_root_tl | -% \c_xtemplate_restrict_root_tl | -% \c_xtemplate_values_root_tl | -% \c_xtemplate_vars_root_tl | -%} -% A number of pieces of code and lists of properties have to be stored -% for templates and instances. The various csname roots are set up as -% token lists to avoid use of the literal text in the code. -%\end{variable} -% -%\begin{variable}{\c_xtemplate_key_order_tl} -% The order keys are declared in must be stored (as property lists -% have no `order'). The special property used is named here. -%\end{variable} -% -%\begin{variable}{\c_xtemplate_keytypes_arg_clist} -% Some keytypes (such as \texttt{instance}) need additional -% information, given as an argument. The list of keytypes that need this -% extra data is set up here, for later use when splitting things. -%\end{variable} -% -%\begin{variable}{\g_xtemplate_object_type_prop} -% For tracking which object types have been declared, and the number -% of arguments each requires. -%\end{variable} -% -%\begin{variable}{\l_xtemplate_assignments_tl} -% This token list variable is used in two places. First, it is where the -% list of assignments for an instance is constructed during -% \cs{DeclareInstance}. Second, it is where these are copied to to -% allow \cs{AssignTemplateKeys} to work correctly. -%\end{variable} -% -%\begin{variable}{\l_xtemplate_collection_tl} -% The name of the current instance collection active. If no collection -% is in use, this will simply be empty. -%\end{variable} -% -%\begin{variable}{\l_xtemplate_collections_prop} -% Records the collection in force for each object type. -%\end{variable} -% -%\begin{variable}{ -% \l_xtemplate_default_tl | -% \l_xtemplate_key_name_tl | -% \l_xtemplate_keytype_tl | -% \l_xtemplate_keytype_arg_tl | -% \l_xtemplate_value_tl | -% \l_xtemplate_var_tl | -%} -% When processing keys, various properties for the current key need to -% be available. These are copied from the property list to appropriately -% named token lists, and back again, as needed. -%\end{variable} -% -%\begin{variable}{\l_xtemplate_error_bool} -% Used to indicate an error when parsing a key list, so that further -% processing can be abandoned. -%\end{variable} -% -%\begin{variable}{\l_xtemplate_global_bool} -% When actually assigning data to variables, a check is made to see -% if this should be global. The flag here is used to indicate this. -%\end{variable} -% -%\begin{variable}{\l_xtemplate_key_seq} -% The order in which keys are defined is stored here for later -% recovery and use. It is transferred into the property list for the -% template when the template is saved. -%\end{variable} -% -%\begin{variable}{\l_xtemplate_restrict_bool} -% Flag used when editing templates, so that simple editing and -% restricting can share the same underlying editing method. -%\end{variable} -% -%\begin{variable}{ -% \l_xtemplate_restricted_clist | -% \l_xtemplate_keytypes_prop | -% \l_xtemplate_values_prop | -% \l_xtemplate_vars_prop | -%} -% To avoid needing to refer to the data about a template or instance -% by csname in a large number of locations, the data is copied to these -% scratch variables and back again for processing. This makes the code -% easier to follow. -%\end{variable} -% -%\begin{variable}{ -% \l_xtemplate_tmp_clist | -% \l_xtemplate_tmp_dim | -% \l_xtemplate_tmp_int | -% \l_xtemplate_tmp_skip | -% \l_xtemplate_tmp_tl | -%} -% Used when carrying out assignments, as the pre-processing can take -% place here before passing data through to the storage area defined -% by the implementation part of a template. The token list is also used -% for general scratch purposes by \pkg{xtemplate}. -%\end{variable} -% -%\begin{variable}{\l_xtemplate_restrict_bool} -% Flag used when editing templates, so that simple editing and -% restricting can share the same underlying editing method. -%\end{variable} -% -%\subsection{Execute or error functions} -% -% These all either execute code (if the tests are true) or issue -% errors (if the test fails). -% -%\begin{function}{\xtemplate_execute_if_arg_agree:nnT} -% \begin{syntax} -% "\xtemplate_execute_if_arg_agree:nnT" \marg{type} \marg{num} -% ~~~~\marg{true code} -% \end{syntax} -% Tests if the number of arguments required by <type> is equal -% to <num>, then executes either <true code> or generates an error as -% appropriate. -%\end{function} -% -%\begin{function}{\xtemplate_execute_if_code_exist:nnT} -% \begin{syntax} -% "\xtemplate_execute_if_code_exist:nnT" \marg{type} \marg{template} -% ~~~~\marg{true code} -% \end{syntax} -% Tests if <template> of <type> has been defined (i.e., the code has -% been created for an implementation), then executes either -% <true code> or generates an error as appropriate. -%\end{function} -% -%\begin{function}{ -% \xtemplate_execute_if_keytype_exist:nT | -% \xtemplate_execute_if_keytype_exist:VT -%} -% \begin{syntax} -% "\xtemplate_execute_if_keytype_exist:nT" \marg{keytype} -% ~~~~\marg{true code} -% \end{syntax} -% Tests if <keytype> is a known keytype, then executes either -% <true code> or generates an error as appropriate. -%\end{function} -% -%\begin{function}{\xtemplate_execute_if_type_exist:nT} -% \begin{syntax} -% "\xtemplate_if_type_exist:nT" \marg{type} \marg{true code} -% \end{syntax} -% Tests if template <type> has been created, then executes either -% <true code> or generates an error as appropriate. -%\end{function} -% -%\begin{function}{\xtemplate_execute_if_keys_exist:nnT} -% \begin{syntax} -% "\xtemplate_if_keys_exist:nnT" \marg{type} \marg{template} -% ~~~~\marg{true code} -% \end{syntax} -% Tests if keys for <template> of <type> have been declared (but -% not necessarily given an implementation), , then executes either -% <true code> or generates an error as appropriate. -%\end{function} -% -%\subsection{Utility functions} -% -%\begin{function}{ -% \xtemplate_if_key_value:nT / (EXP) | -% \xtemplate_if_key_value:VT / (EXP) -%} -% \begin{syntax} -% "\xtemplate_if_key_value:nT" \marg{tokens} \marg{true code} -% \end{syntax} -% Tests if the first token in <tokens> is \cs{KeyValue}. -%\end{function} -% -%\begin{function}{\xtemplate_if_eval_now:nTF / (EXP)} -% \begin{syntax} -% "\xtemplate_if_eval_now:nTF" \marg{tokens} -% ~~~~\marg{true code} \marg{false code} -% \end{syntax} -% Tests if the first token in <tokens> is a marker for evaluating -% now (\cs{EvaluateNow}). -%\end{function} -% -%\begin{function}{\xtemplate_if_instance_exist:nnn / (TF) (EXP)} -% \begin{syntax} -% "\xtemplate_if_instance_exist:nnnTF" \marg{type} -% ~~~~\marg{collection} \marg{instance} \marg{true code} -% \marg{false code} -% \end{syntax} -% Tests if <instance> of <type> exists for the <collection> given. -%\end{function} -% -%\begin{function}{\xtemplate_if_use_template:nTF / (EXP)} -% \begin{syntax} -% "\xtemplate_if_use_template:nTF" \marg{assignment} -% ~~~~\marg{true code} \marg{false code} -% \end{syntax} -% Tests if {assignment} begins with \cs{UseTemplate}. -%\end{function} -% -%\begin{function}{ -% \xtemplate_store_defaults:n | -% \xtemplate_store_keytypes:n | -% \xtemplate_store_restrictions:n | -% \xtemplate_store_values:n | -% \xtemplate_store_vars:n | -%} -% \begin{syntax} -% "\xtemplate_store_defaults:n" \marg{full name} -% \end{syntax} -% These functions copy information about the current template or -% instance from the scratch variables to those for storing the -% information. The <full name> of the instance or template is needed: -% this includes the <type> and <collection> (if applicable). -%\end{function} -% -%\begin{function}{ -% \xtemplate_recover_defaults:n | -% \xtemplate_recover_keytypes:n | -% \xtemplate_recover_restrictions:n | -% \xtemplate_recover_values:n | -% \xtemplate_recover_vars:n | -%} -% \begin{syntax} -% "\xtemplate_recover_defaults:n" \marg{full name} -% \end{syntax} -% The reverse of the \texttt{store} functions, these functions copy -% data from the storage areas to the scratch variables for use in the -% module. Again, the <full name> is needed, including the <type>. -%\end{function} -% -%\subsection{Creating object types} -% -%\begin{function}{\xtemplate_declare_object_type:nn} -% \begin{syntax} -% "\xtemplate_declare_object_type:nn" \marg{type} \marg{num} -% \end{syntax} -% Declares <type> of object, to accept <num> arguments. -%\end{function} -% -%\subsection{Declaring template keys} -% -%\begin{function}{\xtemplate_declare_template_keys:nnnn} -% \begin{syntax} -% "\xtemplate_declare_template_keys:nnnn" \marg{type} -% ~~~~\marg{template} \marg{num} \marg{keyvals} -% \end{syntax} -% Declares <template> of <type>, and accepting <num> arguments, with -% key types and default values defined by <keyvals>. -%\end{function} -% -%\begin{function}{ -% \xtemplate_parse_keys_elt:n | -% \xtemplate_parse_keys_elt:nn -%} -% \begin{syntax} -% "\xtemplate_parse_keys_elt:nn" \marg{key} \marg{value} -% \end{syntax} -% Functions used to process each key--value pair when declaring -% keys from <keyvals>. -%\end{function} -% -%\begin{function}{\xtemplate_split_keytype:n} -% \begin{syntax} -% "\xtemplate_split_keytype:n" \marg{key} -% \end{syntax} -% Splits a <key> into a key name (stored as \cs{l_xtemplate_key_tl}) -% and a keytype (stored as \cs{l_xtemplate_keytype_tl}). -%\end{function} -% -%\begin{function}{ -% \xtemplate_split_keytype_arg:n | -% \xtemplate_split_keytype_arg:V -%} -% \begin{syntax} -% "\xtemplate_split_keytype_arg:n" \marg{keytype} -% \end{syntax} -% Splits a <keytype> into the type itself and any optional qualifying -% text. The results are stored in \cs{l_xtemplate_keytype_tl} and -% \cs{l_xtemplate_keytype_arg_tl}. -%\end{function} -% -%\subsection{Storing defaults and values} -% -%\begin{function}{ -% \xtemplate_store_value_boolean:n | -% \xtemplate_store_value_choice:n | -% \xtemplate_store_value_choice:V | -% \xtemplate_store_value_code:n | -% \xtemplate_store_value_commalist:n | -% \xtemplate_store_value_function:n | -% \xtemplate_store_value_function:n | -% \xtemplate_store_value_instance:n | -% \xtemplate_store_value_tokenlist:n | -% \xtemplate_store_value_integer:n | -% \xtemplate_store_value_length:n | -% \xtemplate_store_value_skip:n | -%} -% \begin{syntax} -% "\xtemplate_store_value_boolean:n" \marg{value} -% \end{syntax} -% Store values of the given keytype for later assignment to variables. -% For the numeric and Boolean data types, the value is evaluated -% at this stage unless \cs{DelayEvaluation} or \cs{KeyValue} are -% used in the <value>. -%\end{function} -% -%\begin{function}{\xtemplate_store_value_choice_name:n} -% \begin{syntax} -% "\xtemplate_store_value_choice_name:n" \marg{value} -% \end{syntax} -% Stores the name of a choice for a multiple choice key, which will -% be turned into an implementation when code is available. -%\end{function} -% -%\subsection{Implementing templates} -% -%\begin{function}{\xtemplate_declare_template_code:nnnnn} -% \begin{syntax} -% "\xtemplate_declare_template_code:nnnnn" \marg{type} -% ~~~~\marg{template} \marg{num} \marg{keyvals} \marg{code} -% \end{syntax} -% Declares implementation of <template> of <type>, and accepting <num> -% arguments, with keys implemented as listed in <keyvals> and with -% <code> to be executed when the <template> is used. -%\end{function} -% -%\begin{function}{\xtemplate_store_key_implementation:nnn} -% \begin{syntax} -% "\xtemplate_store_key_implementation:nnn" \marg{type} -% ~~~~\marg{template} \marg{keyvals} -% \end{syntax} -% Stores the implementation for keys as specified in <keyvals> for -% a <template> of <type>. -%\end{function} -% -%\begin{function}{ -% \xtemplate_parse_vars_elt:n | -% \xtemplate_parse_vars_elt:nn -%} -% \begin{syntax} -% "\xtemplate_parse_vars_elt:nn" \marg{key} \marg{variable} -% \end{syntax} -% Used by the key--value parser to assign a <variable> for each -% <key> listed. -%\end{function} -% -% -%\begin{function}{\xtemplate_store_key_implementation:nnn} -% \begin{syntax} -% "\xtemplate_store_key_implementation:nnn" \marg{type} -% ~~~~\marg{template} \marg{keyvals} -% \end{syntax} -% Stores the implementation for keys as specified in <keyvals> for -% a <template> of <type>. -%\end{function} -% -%\begin{function}{\xtemplate_implement_choices:n} -% \begin{syntax} -% "\xtemplate_implement_choices:n" {key--value list} -% \end{syntax} -% Master function for turning <key-value lsit> into a set of choices. -%\end{function} - -% -%\begin{function}{ -% \xtemplate_implement_choice_elt:n | -% \xtemplate_implement_choice_elt:nn -%} -% \begin{syntax} -% "\xtemplate_implement_choice_elt:nn" \marg{choice} \marg{code} -% \end{syntax} -% Used by the key--value parser to convert a key--value list of -% choices and code into working multiple choice values. -%\end{function} -% -%\subsection{Modifying templates} -% -%\begin{function}{\xtemplate_declare_restricted:nnnn} -% \begin{syntax} -% "\xtemplate_declare_restricted:nnnn" \marg{type} \marg{parent} -% ~~~~\marg{restricted} \marg{keyvals} -% \end{syntax} -% Creates <restricted> template of <type> based on <parent> by fixing -% values as listed in <keyvals>. -%\end{function} -% -%\begin{function}{\xtemplate_edit_defaults:nnn} -% \begin{syntax} -% "\xtemplate_edit_defaults:nnn" \marg{type} \marg{template} -% ~~~~\marg{keyvals} -% \end{syntax} -% Modifies the default values for <template> of <type> as instructed -% in <keyvals>. -%\end{function} -% -%\begin{function}{\xtemplate_parse_values:nn} -% \begin{syntax} -% "\xtemplate_parse_values:nn" \marg{name} \marg{keyvals} -% \end{syntax} -% Parses <keyvals> for full <name>, finding the value for each key -% and storing it for later assignment. -%\end{function} -% -%\begin{function}{ -% \xtemplate_parse_values_elt:n | -% \xtemplate_parse_values_elt:nn -%} -% \begin{syntax} -% "\xtemplate_parse_values_elt:nn" \marg{key} \marg{variable} -% \end{syntax} -% Used by the key--value parser to find <value> to assing to -% implementation of <key>. -%\end{function} -% -%\begin{function}{\xtemplate_set_template_eq:nn} -% \begin{syntax} -% "\xtemplate_set_template_eq:nn" \marg{copy} \marg{parent} -% \end{syntax} -% Copies all of <parent> template to the <copy>, where both are full -% names (i.e., a template plus type). -%\end{function} -% -%\subsection{Creating instances} -% -%\begin{function}{\xtemplate_declare_instance:nnnnn} -% \begin{syntax} -% "\xtemplate_declare_instance:nnnnn" \marg{type} \marg{template} -% ~~~~\marg{collection} \marg{instance} \marg{keyvals} -% \end{syntax} -% Declares an <instance> (within <collection>) of <template> of <type>, -% using <keyvals> to define the instance. -%\end{function} -% -%\begin{function}{\xtemplate_edit_instance:nnnn} -% \begin{syntax} -% "\xtemplate_declare_instance:nnnn" \marg{type} \marg{collection} -% ~~~~\marg{instance} \marg{keyvals} -% \end{syntax} -% Modifies an <instance> (within <collection>) of <type>, using -% <keyvals> to modify the instance. -%\end{function} -% -%\begin{function}{\xtemplate_convert_to_assignments:} -% \begin{syntax} -% "\xtemplate_convert_to_assignments:" -% \end{syntax} -% Converts the contents of the various scratch property lists into -% a list of variable assignments in \cs{l_xtemplate_assignments_tl}. -%\end{function} -% -%\begin{function}{\xtemplate_find_global:} -% \begin{syntax} -% "\xtemplate_find_global:" -% \end{syntax} -% Checks in \cs{l_xtemplate_var_tl} for the special text -% \texttt{global}, which is removed from the variable is found. The -% flag \cs{l_xtemplate_global_bool} is then set as appropriate. -%\end{function} -% -%\subsection{Converting values to assignments} -% -%\begin{function}{ -% \xtemplate_assign_boolean: | -% \xtemplate_assign_choice: | -% \xtemplate_assign_code: | -% \xtemplate_assign_code:n | -% \xtemplate_assign_commalist: | -% \xtemplate_assign_function: | -% \xtemplate_assign_instance: | -% \xtemplate_assign_integer: | -% \xtemplate_assign_length: | -% \xtemplate_assign_skip: | -% \xtemplate_assign_tokenlist: -%} -% \begin{syntax} -% "\xtemplate_assign_boolean:" -% \end{syntax} -% Convert the given <keytype> of <key> into an assignment to a -% <variable>. -%\end{function} -% -%\begin{function}{\xtemplate_assign_variable:N} -% \begin{syntax} -% "\xtemplate_assign_variable:N" <function> -% \end{syntax} -% Convert the current contents of \cs{l_xtemplate_value_tl} into an -% assignment using <function> to the variable named in -% \cs{l_xtemplate_var_tl}. -%\end{function} -% -%\begin{function}{\xtemplate_key_to_value:} -% \begin{syntax} -% "\xtemplate_key_to_value:" -% \end{syntax} -% Converts an attribute named using \cs{KeyValue} into the -% value of the underlying implementation variable. -%\end{function} -% -%\subsection{Using instances} -% -%\begin{function}{\xtemplate_use_instance:nn} -% \begin{syntax} -% "\xtemplate_use_instance:nn" \marg{type} \marg{instance} -% \end{syntax} -% Executes code stored for <instance> of <type>, taking account of -% any active collection. -%\end{function} -% -%\begin{function}{\xtemplate_use_template:nnn} -% \begin{syntax} -% "\xtemplate_use_template:nnn" \marg{type} \marg{template} -% ~~~~\marg{settings} -% \end{syntax} -% Executes code stored for <template> of <type> using <settings>. -%\end{function} -% -%\begin{function}{\xtemplate_use_collection:nn} -% \begin{syntax} -% "\xtemplate_use_collection:nn" \marg{type} \marg{collection} -% \end{syntax} -% Activates <collection> for instances of \marg{type}. -%\end{function} -% -%\begin{function}{\xtemplate_get_collection:n} -% \begin{syntax} -% "\xtemplate_get_collection:n" \marg{type} -% \end{syntax} -% Sets \cs{l_xtemplate_collection_tl} to the name of the collection -% in force for templates of <type>. -%\end{function} -% -%\begin{function}{\xtemplate_assignments_pop:} -% \begin{syntax} -% "\xtemplate_assignments_pop:" -% \end{syntax} -% Pops \cs{l_xtemplate_assignment_tl}, and therefore executes -% the assignements stored there. -%\end{function} -% -%\begin{function}{\xtemplate_assignments_push:n} -% \begin{syntax} -% "\xtemplate_assignments_push:n" \marg{assignments} -% \end{syntax} -% Pushes <assignments> to \cs{l_xtemplate_assignment_tl} for later -% execution. -%\end{function} -% -%\subsection{Showing details} -% -%\begin{function}{\xtemplate_show_code:nn} -% \begin{syntax} -% "\xtemplate_show_code:nn" \marg{type} \marg{template} -% \end{syntax} -% Shows code associated with <template> of <type>. -%\end{function} -% -%\begin{function}{\xtemplate_show_code:nn} -% \begin{syntax} -% "\xtemplate_show_code:nn" \marg{type} \marg{template} -% \end{syntax} -% Shows code associated with <template> of <type>. -%\end{function} -% -%\begin{function}{\xtemplate_show_defaults:nn} -% \begin{syntax} -% "\xtemplate_show_default:nn" \marg{type} \marg{template} -% \end{syntax} -% Shows default values associated with <template> of <type>. -%\end{function} -% -%\begin{function}{\xtemplate_show_keytypes:nn} -% \begin{syntax} -% "\xtemplate_show_keytypes:nn" \marg{type} \marg{template} -% \end{syntax} -% Shows key types associated with <template> of <type>. -%\end{function} -% -%\begin{function}{\xtemplate_show_values:nnn} -% \begin{syntax} -% "\xtemplate_show_code:nnn" \marg{type} \marg{collection} -% ~~~~\marg{instance} -% \end{syntax} -% Shows values associated with <instance> of <type> within -% <collection>. -%\end{function} -% - -%\begin{function}{\xtemplate_show_vars:nn} -% \begin{syntax} -% "\xtemplate_show_vars:nn" \marg{type} \marg{template} -% \end{syntax} -% Shows variables associated with <template> of <type>. -%\end{function} -% -% \end{documentation} -% -% \begin{implementation} -% -%\section{Implementation} -% -% \pkg{xtemplate} only needs \pkg{expl3}; in format mode, this can be -% skipped. -% \begin{macrocode} -%<*package> -\ProvidesExplPackage - {\filename}{\filedate}{\fileversion}{\filedescription} -\RequirePackage{expl3} -%</package> -%<*initex|package> -% \end{macrocode} -% -%\subsubsection{Variables and constants} -% -%\begin{macro}{\c_xtemplate_code_root_tl} -%\begin{macro}{\c_xtemplate_defaults_root_tl} -%\begin{macro}{\c_xtemplate_instances_root_tl} -%\begin{macro}{\c_xtemplate_keytypes_root_tl} -%\begin{macro}{\c_xtemplate_restrict_root_tl} -%\begin{macro}{\c_xtemplate_values_root_tl} -%\begin{macro}{\c_xtemplate_vars_root_tl} -% So that literal values are kept to a minimum. -% \begin{macrocode} -\tl_const:Nn \c_xtemplate_code_root_tl { xtemplate_code > } -\tl_new:Nn \c_xtemplate_defaults_root_tl { xtemplate_defaults > } -\tl_new:Nn \c_xtemplate_instances_root_tl { xtemplate_instances > } -\tl_new:Nn \c_xtemplate_keytypes_root_tl { xtemplate_keytypes > } -\tl_new:Nn \c_xtemplate_restrict_root_tl { xtemplate_restrict > } -\tl_new:Nn \c_xtemplate_values_root_tl { xtemplate_values > } -\tl_new:Nn \c_xtemplate_vars_root_tl { xtemplate_vars > } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\c_xtemplate_key_order_tl} -% A special property name, used to store the order keys are defined -% in. -% \begin{macrocode} -\tl_new:Nn \c_xtemplate_key_order_tl { key~order } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\c_xtemplate_keytypes_arg_clist} -% A list of keytypes which also need additional data (an argument), used -% to parse the keytype correctly. -% \begin{macrocode} -\clist_new:N \c_xtemplate_keytypes_arg_clist -\clist_put_right:Nn \c_xtemplate_keytypes_arg_clist { choice } -\clist_put_right:Nn \c_xtemplate_keytypes_arg_clist { function } -\clist_put_right:Nn \c_xtemplate_keytypes_arg_clist { instance } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\g_xtemplate_object_type_prop} -% For storing types and the associated number of arguments. -% \begin{macrocode} -\prop_new:N \g_xtemplate_object_type_prop -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_assignments_tl} -% When creating an instance, the assigned values are collected here. -% \begin{macrocode} -\tl_new:N \l_xtemplate_assignments_tl -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_collection_tl} -% The current instance collection name is stored here. -% \begin{macrocode} -\tl_new:N \l_xtemplate_collection_tl -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_collections_prop} -% Lists current collection in force, indexed by object type. -% \begin{macrocode} -\prop_new:N \l_xtemplate_collections_prop -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_default_tl} -% The default value for a key is recovered here from the property list -% in which it is stored. The internal implementation of property lists -% means that this is safe even with un-escaped |#| tokens. -% \begin{macrocode} -\tl_new:N \l_xtemplate_default_tl -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_error_bool} -% A flag for errors to be carried forward. -% \begin{macrocode} -\bool_new:N \l_xtemplate_error_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_global_bool} -% Used to indicate that assignments should be global. -% \begin{macrocode} -\bool_new:N \l_xtemplate_global_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_restrict_bool} -% A flag to indicate that a template is being restricted. -% \begin{macrocode} -\bool_new:N \l_xtemplate_restrict_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_restrict_clist} -% A scratch list for restricting templates. -% \begin{macrocode} -\clist_new:N \l_xtemplate_restrict_clist -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_key_name_tl} -%\begin{macro}{\l_xtemplate_keytype_tl} -%\begin{macro}{\l_xtemplate_keytype_arg_tl} -%\begin{macro}{\l_xtemplate_value_tl} -%\begin{macro}{\l_xtemplate_var_tl} -% When defining each key in a template, the name and type of the key -% need to be separated and stored. Any argument needed by the -% keytype is also stored separately. -% \begin{macrocode} -\tl_new:N \l_xtemplate_key_name_tl -\tl_new:N \l_xtemplate_keytype_tl -\tl_new:N \l_xtemplate_keytype_arg_tl -\tl_new:N \l_xtemplate_value_tl -\tl_new:N \l_xtemplate_var_tl -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_key_seq} -% The order that keys are declared needs to be know, so that they can -% be set in the same way. As property lists are not ordered data types, -% a separate list needs to be kept which \emph{is} ordered. This will -% then be stored in the property list. -% \begin{macrocode} -\seq_new:N \l_xtemplate_key_seq -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_keytypes_prop} -%\begin{macro}{\l_xtemplate_values_prop} -%\begin{macro}{\l_xtemplate_vars_prop} -% To avoid needing too many difficult-to-follow csname assignments, -% various scratch token registers are used to build up data, which is -% then transferred -% \begin{macrocode} -\prop_new:N \l_xtemplate_keytypes_prop -\prop_new:N \l_xtemplate_values_prop -\prop_new:N \l_xtemplate_vars_prop -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_tmp_clist} -%\begin{macro}{\l_xtemplate_tmp_dim} -%\begin{macro}{\l_xtemplate_tmp_int} -%\begin{macro}{\l_xtemplate_tmp_skip} -% For pre-processing the data stored by \pkg{xtemplate}, a number of -% scratch variables are needed. The assignments are made to these in the -% first instance, unless evaluation is delayed. -% \begin{macrocode} -\clist_new:N \l_xtemplate_tmp_clist -\dim_new:N \l_xtemplate_tmp_dim -\int_new:N \l_xtemplate_tmp_int -\skip_new:N \l_xtemplate_tmp_skip -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_xtemplate_tmp_tl} -% A scratch variable for comparisons and so on. -% \begin{macrocode} -\tl_new:N \l_xtemplate_tmp_tl -% \end{macrocode} -%\end{macro} -% -%\subsection{Testing existence and validity} -% -% There are a number of checks needed for either the existence of -% a object type, template or instance. There are also some for the -% validity of a particular call. All of these are collected up here. -% -%\begin{macro}{\xtemplate_execute_if_arg_agree:nnT} -% A test agreement between the number of arguments for the template -% type and that specified when creating a template. This is not done as a -% separate conditional for efficiency and better error message -% \begin{macrocode} -\cs_new:Npn \xtemplate_execute_if_arg_agree:nnT #1#2#3 { - \prop_get:NnN \g_xtemplate_object_type_prop {#1} \l_xtemplate_tmp_tl - \int_compare:nTF { #2 = \l_xtemplate_tmp_tl } - {#3} - { - \msg_kernel_error:nnxxx { xtemplate } - { argument-number-mismatch } {#1} { \l_xtemplate_tmp_tl } {#2} - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_execute_if_code_exist:nnT} -% A template is only fully declared if the code has been set up, -% which can be checked by looking for the template function itself. -% \begin{macrocode} -\cs_new:Npn \xtemplate_execute_if_code_exist:nnT #1#2#3 { - \cs_if_exist:cTF { \c_xtemplate_code_root_tl #1 / #2 :w } - {#3} - { - \msg_kernel_error:nnxx { xtemplate } { no-template-code } - {#1} {#2} - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_execute_if_keytype_exist:nT} -%\begin{macro}{\xtemplate_execute_if_keytype_exist:VF} -% The test for valid keytypes looks for a function to set up the key, -% which is part of the `code' side of the template definition. This -% avoids having different lists for the two parts of the process. -% \begin{macrocode} -\cs_new:Npn \xtemplate_execute_if_keytype_exist:nT #1#2 { - \cs_if_exist:cTF { xtemplate_store_value_ #1 :n } - {#2} - { \msg_kernel_error:nnx { xtemplate } { unknown-keytype } {#1} } -} -\cs_generate_variant:Nn \xtemplate_execute_if_keytype_exist:nT { V } -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_execute_if_type_exist:nT} -% To check that a particular object type is valid. -% \begin{macrocode} -\cs_new:Npn \xtemplate_execute_if_type_exist:nT #1#2 { - \prop_if_in:NnTF \g_xtemplate_object_type_prop {#1} - {#2} - { \msg_kernel_error:nnx { xtemplate } { unknown-object-type } {#1} } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_execute_if_keys_exist:nnT} -% To check that the keys for a template have been set up before trying -% to create any code, a simple check for the correctly-named keytype -% property list. -% \begin{macrocode} -\cs_new:Npn \xtemplate_if_keys_exist:nnT #1#2#3 { - \cs_if_exist:cTF - { g_ \c_xtemplate_keytypes_root_tl #1 / #2 _prop } - {#3} - { - \msg_kernel_error:nnxx { xtemplate } { unknown-template } - {#1} {#2} - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_if_key_value:nT} -%\begin{macro}{\xtemplate_if_key_value:VT} -% Tests for the first token in a string being \cs{KeyValue}, where -% \cs{EvaluateNow} is not important. -% \begin{macrocode} -\prg_set_conditional:Nnn \xtemplate_if_key_value:n { T } { - \str_if_eq:noTF { \KeyValue } { \tl_head:w #1 \q_stop } { - \prg_return_true: - }{ - \prg_return_false: - } -} -\cs_generate_variant:Nn \xtemplate_if_key_value:nT { V } -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_if_eval_now:nTF} -% Tests for the first token in a string being \cs{EvaluateNow}. -% \begin{macrocode} -\prg_new_conditional:Nnn \xtemplate_if_eval_now:n { TF } { - \str_if_eq:noTF { \EvaluateNow } { \tl_head:w #1 \q_stop } { - \prg_return_true: - }{ - \prg_return_false: - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}[TF]{\xtemplate_if_instance_exist:nnn} -% Testing for an instance is collection dependent. -% \begin{macrocode} -\prg_new_conditional:Nnn \xtemplate_if_instance_exist:nnn { T, F, TF } { - \cs_if_exist:cTF { \c_xtemplate_instances_root_tl #1 / #2 / #3 :w } { - \prg_return_true: - }{ - \prg_return_false: - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_if_use_template:nTF} -% Tests for the first token in a string being \cs{UseTemplate}. -% \begin{macrocode} -\prg_new_conditional:Nnn \xtemplate_if_use_template:n { TF } { - \str_if_eq:noTF { \UseTemplate } { \tl_head:w #1 \q_stop } { - \prg_return_true: - }{ - \prg_return_false: - } -} -% \end{macrocode} -%\end{macro} -% -%\subsubsection{Saving and recovering property lists} -% -% The various property lists for templates have to be shuffled in -% and out of storage. -% -%\begin{macro}{\xtemplate_store_defaults:n} -%\begin{macro}{\xtemplate_store_keytypes:n} -%\begin{macro}{\xtemplate_store_restrictions:n} -%\begin{macro}{\xtemplate_store_values:n} -%\begin{macro}{\xtemplate_store_vars:n} -% The defaults and keytypes are transferred from the scratch property -% lists to the `proper' lists for the template being created. -% \begin{macrocode} -\cs_new:Npn \xtemplate_store_defaults:n #1 { - \cs_if_free:cT { g_ \c_xtemplate_defaults_root_tl #1 _prop } { - \prop_new:c { g_ \c_xtemplate_defaults_root_tl #1 _prop } - } - \prop_gset_eq:cN { g_ \c_xtemplate_defaults_root_tl #1 _prop } - \l_xtemplate_values_prop -} -\cs_new:Npn \xtemplate_store_keytypes:n #1 { - \cs_if_free:cTF { g_ \c_xtemplate_keytypes_root_tl #1 _prop } { - \msg_kernel_info:nnx { xtemplate } { define-template-interface } - {#1} - \prop_new:c { g_ \c_xtemplate_keytypes_root_tl #1 _prop } - } - { - \msg_kernel_warning:nnx { xtemplate } - { redefine-template-interface } {#1} - } - \prop_gset_eq:cN { g_ \c_xtemplate_keytypes_root_tl #1 _prop } - \l_xtemplate_keytypes_prop -} -\cs_new:Npn \xtemplate_store_values:n #1 { - \cs_if_free:cT { l_ \c_xtemplate_values_root_tl #1 _prop } { - \prop_new:c { l_ \c_xtemplate_values_root_tl #1 _prop } - } - \prop_set_eq:cN { l_ \c_xtemplate_values_root_tl #1 _prop } - \l_xtemplate_values_prop -} -\cs_new:Npn \xtemplate_store_restrictions:n #1 { - \cs_if_free:cT { g_ \c_xtemplate_restrict_root_tl #1 _clist } { - \clist_new:c { g_ \c_xtemplate_restrict_root_tl #1 _clist } - } - \clist_gset_eq:cN { g_ \c_xtemplate_restrict_root_tl #1 _clist } - \l_xtemplate_restrict_clist -} -\cs_new:Npn \xtemplate_store_vars:n #1 { - \cs_if_free:cTF { g_ \c_xtemplate_vars_root_tl #1 _prop } { - \msg_kernel_info:nnx { xtemplate } { define-template-code } {#1} - \prop_new:c { g_ \c_xtemplate_vars_root_tl #1 _prop } - } - { - \msg_kernel_warning:nnx { xtemplate } { redefine-template-code } - {#1} - } - \prop_gset_eq:cN { g_ \c_xtemplate_vars_root_tl #1 _prop } - \l_xtemplate_vars_prop -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_recover_defaults:n} -%\begin{macro}{\xtemplate_recover_keytypes:n} -%\begin{macro}{\xtemplate_recover_restrictions:n} -%\begin{macro}{\xtemplate_recover_values:n} -%\begin{macro}{\xtemplate_recover_vars:n} -% Recovering the stored data for a template is rather less complex -% than storing it. All that happens is the data is transferred from -% the permanent to the scratch storage. -% \begin{macrocode} -\cs_new:Npn \xtemplate_recover_defaults:n #1 { - \prop_set_eq:Nc \l_xtemplate_values_prop - { g_ \c_xtemplate_defaults_root_tl #1 _prop } -} -\cs_new:Npn \xtemplate_recover_keytypes:n #1 { - \prop_set_eq:Nc \l_xtemplate_keytypes_prop - { g_ \c_xtemplate_keytypes_root_tl #1 _prop } -} -\cs_new:Npn \xtemplate_recover_restrictions:n #1 { -% FMi why is this called before being defined???? - \cs_if_free:cT { g_ \c_xtemplate_restrict_root_tl #1 _clist } { - \clist_new:c { g_ \c_xtemplate_restrict_root_tl #1 _clist } - } - \clist_set_eq:Nc \l_xtemplate_restrict_clist - { g_ \c_xtemplate_restrict_root_tl #1 _clist } -} -\cs_new:Npn \xtemplate_recover_values:n #1 { - \prop_set_eq:Nc \l_xtemplate_values_prop - { l_ \c_xtemplate_values_root_tl #1 _prop } -} -\cs_new:Npn \xtemplate_recover_vars:n #1 { - \prop_set_eq:Nc \l_xtemplate_vars_prop - { g_ \c_xtemplate_vars_root_tl #1 _prop } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\subsubsection{Creating new object types} -% -%\begin{macro}{\xtemplate_declare_object_type:nn} -% Although the object type is the `top level' of the template system, -% it is actually very easy to implement. All that happens is that the -% number of arguments required is recorded, indexed by the name of the -% object type. -% \begin{macrocode} -\cs_new:Npn \xtemplate_declare_object_type:nn #1#2 { - \int_set:Nn \l_xtemplate_tmp_int {#2} - \bool_if:nTF { - \int_compare_p:n { #2 > \c_nine } || - \int_compare_p:n { #2 < \c_zero } - } { - \msg_kernel_error:nnxx { xtemplate } { bad-number-of-arguments } - {#1} { \exp_not:V \l_xtemplate_tmp_int } - }{ - \prop_if_in:NnTF \g_xtemplate_object_type_prop {#1} - { - \msg_kernel_warning:nnxx { xtemplate } { redefine-object-type } - {#1} {#2} - } - { - \msg_kernel_info:nnxx { xtemplate } { define-object-type } - {#1} {#2} - } - \prop_gput:NnV \g_xtemplate_object_type_prop {#1} - \l_xtemplate_tmp_int - } -} -% \end{macrocode} -%\end{macro} -% -%\subsection{Design part of template declaration} -% -% The `design' part of a template declaration defines the general -% behaviour of each key, and possibly a default value. However, it does -% not include the implementation. This means that what happens here is -% the two properties are saved to appropriate lists, which can then -% be used later to recover the information when implementing the keys. -% -%\begin{macro}{\xtemplate_declare_template_keys:nnnn} -% The main function for the `design' part of creating a template starts -% by checking that the object type exists and that the number of -% arguments required agree. If that is all fine, then the two storage -% areas for defaults and keytypes are initialised. The mechanism is then -% set up for the \pkg{l3keyval} module to actually parse the keys. -% Finally, the code hands of to the storage routine to save the parsed -% information properly. -% \begin{macrocode} -\cs_new:Npn \xtemplate_declare_template_keys:nnnn #1#2#3#4 { - \xtemplate_execute_if_type_exist:nT {#1} - { - \xtemplate_execute_if_arg_agree:nnT {#1} {#3} - { - \prop_clear:N \l_xtemplate_values_prop - \prop_clear:N \l_xtemplate_keytypes_prop - \seq_clear:N \l_xtemplate_key_seq - \KV_process_space_removal_sanitize:NNn - \xtemplate_parse_keys_elt:n \xtemplate_parse_keys_elt:nn {#4} - \prop_put:NVV \l_xtemplate_keytypes_prop \c_xtemplate_key_order_tl - \l_xtemplate_key_seq - \xtemplate_store_defaults:n { #1 / #2 } - \xtemplate_store_keytypes:n { #1 / #2 } - } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_parse_keys_elt:n} -%\begin{macro}[aux]{\xtemplate_parse_keys_elt_aux:n} -%\begin{macro}[aux]{\xtemplate_parse_keys_elt_aux:} -% Processing the key part of the key--value pair is always carried out -% using this function, even if a value was found. First, the key name -% is separated from the keytype, and if necessary the keytype is -% separated into two parts. This information is then used to check that -% the keytype is valid, before storing the keytype (plus argument if -% necessary) as a property of the key name. The key name is also stored -% (in braces) in the token list to record the order the keys are defined -% in. -% \begin{macrocode} -\cs_new:Npn \xtemplate_parse_keys_elt:n #1 { - \xtemplate_split_keytype:n {#1} - \bool_if:NF \l_xtemplate_error_bool - { - \xtemplate_execute_if_keytype_exist:VT \l_xtemplate_keytype_tl - { - \clist_map_function:nN { choice , function , instance } - \xtemplate_parse_keys_elt_aux:n - \bool_if:NF \l_xtemplate_error_bool - { - \seq_if_in:NVTF \l_xtemplate_key_seq - \l_xtemplate_key_name_tl - { - \msg_kernel_error:nnx { xtemplate } - { duplicate-key-interface } - { \l_xtemplate_key_name_tl } - } - { \xtemplate_parse_keys_elt_aux: } - } - } - } -} -\cs_new_nopar:Npn \xtemplate_parse_keys_elt_aux:n #1 { - \str_if_eq:VnT \l_xtemplate_keytype_tl {#1} { - \tl_if_empty:NT \l_xtemplate_keytype_arg_tl { - \msg_kernel_error:nnx { xtemplate } - { keytype-requires-argument } {#1} - \bool_set_true:N \l_xtemplate_error_bool - \clist_map_break: - } - } -} -\cs_new_nopar:Npn \xtemplate_parse_keys_elt_aux: { - \tl_set:Nx \l_xtemplate_tmp_tl { - \l_xtemplate_keytype_tl - \l_xtemplate_keytype_arg_tl - } - \prop_put:NVV \l_xtemplate_keytypes_prop \l_xtemplate_key_name_tl - \l_xtemplate_tmp_tl - \seq_put_right:NV \l_xtemplate_key_seq \l_xtemplate_key_name_tl - \str_if_eq:VnT \l_xtemplate_keytype_tl { choice } { - \clist_if_in:NnT \l_xtemplate_keytype_arg_tl { unknown } { - \msg_kernel_error:nn { xtemplate } { choice-unknown-reserved } - } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_parse_keys_elt:nn} -% For keys which have a default, the keytype and key name are first -% separated out by the \cs{xtemplate_parse_keys_elt:n} -% routine, before storing the default value in the scratch property list. -% Choices have special handling as the code is not yet available to -% actually do the storing! -% \begin{macrocode} -\cs_new:Npn \xtemplate_parse_keys_elt:nn #1#2 { - \xtemplate_parse_keys_elt:n {#1} - \str_if_eq:VnTF \l_xtemplate_keytype_tl { choice } { - \xtemplate_store_value_choice_name:n {#2} - }{ - \use:c { xtemplate_store_value_ \l_xtemplate_keytype_tl :n } {#2} - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_split_keytype:n} -%\begin{macro}[aux]{\xtemplate_split_keytype_aux:w} -% The keytype and key name should be separated by `\texttt{:}'. As the -% definition might be given inside or outside of a code block, spaces -% are removed and the category code of colons is standardised. After -% that, the standard delimited argument method is used to separate the -% two parts. -% \begin{macrocode} -\group_begin: -\char_set_lccode:nn { `\@ } { `\: } -\char_make_other:N \@ -\tl_to_lowercase:n { - \group_end: - \cs_new:Npn \xtemplate_split_keytype:n #1 { - \bool_set_false:N \l_xtemplate_error_bool - \tl_set:Nn \l_xtemplate_tmp_tl {#1} - \tl_remove_all_in:Nn \l_xtemplate_tmp_tl { ~ } - \tl_replace_all_in:Nnn \l_xtemplate_tmp_tl { : } { @ } - \tl_if_in:VnTF \l_xtemplate_tmp_tl { @ } { - \exp_after:wN \xtemplate_split_keytype_aux:w \l_xtemplate_tmp_tl - \q_stop - }{ - \bool_set_true:N \l_xtemplate_error_bool - \msg_kernel_error:nnx { xtemplate } { no-keytype } {#1} - } - } - \cs_new:Npn \xtemplate_split_keytype_aux:w #1 @ #2 \q_stop { - \tl_if_empty:nT {#1} { - \msg_kernel_error:nnx { xtemplate } { empty-key-name } { @ #2 } - } - \tl_set:Nx \l_xtemplate_key_name_tl { \tl_to_str:n {#1} } - \xtemplate_split_keytype_arg:n {#2} - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_split_keytype_arg:n} -%\begin{macro}{\xtemplate_split_keytype_arg:V} -%\begin{macro}[aux]{\xtemplate_split_keytype_arg_aux:n} -%\begin{macro}[aux]{\xtemplate_split_keytype_arg_aux:w} -% The second stage of sorting out the keytype is to check for an -% argument. As there is no convenient delimiting token to look for, -% a check is made instead for each possible text value for the keytype. -% To keep things faster, this only involves the keytypes that need an -% argument. If a match is made, then a check is also needed to see that -% it is at the start of the keytype information. All being well, the -% split can then be applied. Any non-matching keytypes are assumed to -% be `correct' as given, and are left alone (this is checked by other -% code). -% \begin{macrocode} -\cs_new:Npn \xtemplate_split_keytype_arg:n #1 { - \tl_set:Nn \l_xtemplate_keytype_tl {#1} - \tl_clear:N \l_xtemplate_keytype_arg_tl - \cs_set_nopar:Npn \xtemplate_split_keytype_arg_aux:n ##1 { - \tl_if_in:nnT {#1} {##1} { - \cs_set:Npn \xtemplate_split_keytype_arg_aux:w - ####1 ##1 ####2 \q_stop { - \tl_if_empty:nT {####1} { - \tl_set:Nn \l_xtemplate_keytype_tl {##1} - \tl_set:Nn \l_xtemplate_keytype_arg_tl {####2} - \clist_map_break: - } - } - \xtemplate_split_keytype_arg_aux:w #1 \q_stop - } - } - \clist_map_function:NN \c_xtemplate_keytypes_arg_clist - \xtemplate_split_keytype_arg_aux:n -} -\cs_generate_variant:Nn \xtemplate_split_keytype_arg:n { V } -\cs_new_nopar:Npn \xtemplate_split_keytype_arg_aux:n #1 { } -\cs_new_nopar:Npn \xtemplate_split_keytype_arg_aux:w #1 \q_stop { } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\subsubsection{Storing values} -% -% As \pkg{xtemplate} pre-processes key values for efficiency reasons, -% there is a need to convert the values given as defaults into -% `ready to use' data. The same general idea is true when an instance -% is declared. However, assignments are not made until an instance is -% used, and so there has to be some intermediate storage. Furthermore, -% the ability to delay evaluation of results is needed. To achieve these -% aims, a series of `process and store' functions are defined here. -% -% All of the information about the key (the key name and the keytype) -% is already stored as variables. The same property list is always used -% to store the data, meaning that the only argument required is the -% value to be processed and potentially stored. -% -%\begin{macro}{\xtemplate_store_value_boolean:n} -% Storing Boolean values requires a test for delayed evaluation, but -% is different to the various numerical variable types as there are -% only two possible values to store. So the code here tests the default -% switch and then records the meaning (either \texttt{true} or -% \texttt{false}). -% \begin{macrocode} -\cs_new:Npn \xtemplate_store_value_boolean:n #1 { - \xtemplate_if_eval_now:nTF {#1} { - \bool_if:cTF { c_ #1 _bool } { - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl - { true } - }{ - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl - { false } - } - }{ - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl {#1} - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_store_value_choice:n} -%\begin{macro}{\xtemplate_store_value_choice:V} -%\begin{macro}[aux]{\xtemplate_store_value_choice_aux:n} -%\begin{macro}[aux]{\xtemplate_store_value_choice_aux:V} -%\begin{macro}{\xtemplate_store_value_choice_name:n} -% Choices are a bit odd, as they have to be handled in two parts. When -% an interface is being created, the default is stored with a hidden -% name (using spaces and letter category codes). When a choice is -% actually being used, there is a check for the choice itself, then -% code to handle an unknown before issuing an error. -% \begin{macrocode} -\cs_new:Npn \xtemplate_store_value_choice:n #1 { - \tl_set:Nx \l_xtemplate_tmp_tl - { \l_xtemplate_key_name_tl \c_space_tl #1 } - \prop_if_in:NVTF \l_xtemplate_vars_prop \l_xtemplate_tmp_tl { - \xtemplate_store_value_choice_aux:V \l_xtemplate_tmp_tl - }{ - \tl_set:Nx \l_xtemplate_tmp_tl - { \l_xtemplate_key_name_tl \c_space_tl unknown } - \prop_if_in:NVTF \l_xtemplate_vars_prop \l_xtemplate_tmp_tl { - \xtemplate_store_value_choice_aux:V \l_xtemplate_tmp_tl - }{ - \prop_get:NVN \l_xtemplate_keytypes_prop \l_xtemplate_key_name_tl - \l_xtemplate_tmp_tl - \xtemplate_split_keytype_arg:V \l_xtemplate_tmp_tl - \msg_kernel_error:nnxxx { xtemplate } { unknown-choice } - {#1} - { \l_xtemplate_key_name_tl } - { \l_xtemplate_keytype_arg_tl } - \prop_gdel:NV \l_xtemplate_values_prop \l_xtemplate_key_name_tl - } - } -} -\cs_generate_variant:Nn \xtemplate_store_value_choice:n { V } -\cs_new:Npn \xtemplate_store_value_choice_aux:n #1 { - \prop_get:NnN \l_xtemplate_vars_prop {#1} \l_xtemplate_tmp_tl - \prop_put:NVV \l_xtemplate_values_prop \l_xtemplate_key_name_tl - \l_xtemplate_tmp_tl -} -\cs_generate_variant:Nn \xtemplate_store_value_choice_aux:n { V } -\cs_new:Npn \xtemplate_store_value_choice_name:n #1 { - \tl_set:Nx \l_xtemplate_tmp_tl - { \l_xtemplate_key_name_tl \c_space_tl default } - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_tmp_tl {#1} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_store_value_code:n} -%\begin{macro}{\xtemplate_store_value_commalist:n} -%\begin{macro}{\xtemplate_store_value_function:n} -%\begin{macro}{\xtemplate_store_value_instance:n} -%\begin{macro}{\xtemplate_store_value_tokenlist:n} -% With no need to worry about delayed evaluation, these keytypes all -% just store the input directly. -% \begin{macrocode} -\cs_new:Npn \xtemplate_store_value_code:n #1 { - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl {#1} -} -\cs_new:Npn \xtemplate_store_value_commalist:n #1 { - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl {#1} -} -\cs_new:Npn \xtemplate_store_value_function:n #1 { - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl {#1} -} -\cs_new:Npn \xtemplate_store_value_instance:n #1 { - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl {#1} -} -\cs_new:Npn \xtemplate_store_value_tokenlist:n #1 { - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl {#1} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_store_value_integer:n} -%\begin{macro}{\xtemplate_store_value_length:n} -%\begin{macro}{\xtemplate_store_value_skip:n} -% Storing the value of a number is in all cases more or less the same. -% If evaluation is taking place now, assignment is made to a scratch -% variable, and this result is then stored. On the other hand, if -% evaluation is delayed the current data is simply stored `as is'. -% \begin{macrocode} -\cs_new:Npn \xtemplate_store_value_integer:n #1 { - \xtemplate_if_eval_now:nTF {#1} { - \int_set:Nn \l_xtemplate_tmp_int {#1} - \prop_put:NVV \l_xtemplate_values_prop \l_xtemplate_key_name_tl - \l_xtemplate_tmp_int - }{ - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl {#1} - } -} -\cs_new:Npn \xtemplate_store_value_length:n #1 { - \xtemplate_if_eval_now:nTF {#1} { - \dim_set:Nn \l_xtemplate_tmp_dim {#1} - \prop_put:NVV \l_xtemplate_values_prop \l_xtemplate_key_name_tl - \l_xtemplate_tmp_dim - }{ - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl {#1} - } -} -\cs_new:Npn \xtemplate_store_value_skip:n #1 { - \xtemplate_if_eval_now:nTF {#1} { - \skip_set:Nn \l_xtemplate_tmp_skip {#1} - \prop_put:NVV \l_xtemplate_values_prop \l_xtemplate_key_name_tl - \l_xtemplate_tmp_skip - }{ - \prop_put:NVn \l_xtemplate_values_prop \l_xtemplate_key_name_tl {#1} - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\subsubsection{Implementation part of template declaration} -% -%\begin{macro}{\xtemplate_declare_template_code:nnnnn} -% The main function for implementing a template starts with a couple of -% simple checks to make sure that there are no obvious mistakes: the -% number of arguments must agree and the template keys must have been -% declared. -% \begin{macrocode} -\cs_new:Npn \xtemplate_declare_template_code:nnnnn #1#2#3#4#5 { - \xtemplate_execute_if_type_exist:nT {#1} - { - \xtemplate_execute_if_arg_agree:nnT {#1}{#3} - { - \xtemplate_if_keys_exist:nnT {#1} {#2} - { - \xtemplate_store_key_implementation:nnn {#1} {#2} {#4} - \cs_generate_from_arg_count:cNnn - { \c_xtemplate_code_root_tl #1 / #2 :w } \cs_gset:Npn - {#3} {#5} - } - } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_store_key_implementation:nnn} -% Actually storing the implementation part of a template is quite easy -% as it only requires the list of keys given to be turned into a -% property list. There is also some error-checking to do, hence the need -% to have the list of defined keytypes available. In certain cases -% (when choices are involved) parsing the key results in changes to the -% default values. That is why they are loaded and then saved again. -% \begin{macrocode} -\cs_set:Npn \xtemplate_store_key_implementation:nnn #1#2#3 { - \xtemplate_recover_defaults:n { #1 / #2 } - \xtemplate_recover_keytypes:n { #1 / #2 } - \prop_clear:N \l_xtemplate_vars_prop - \KV_process_space_removal_sanitize:NNn - \xtemplate_parse_vars_elt:n \xtemplate_parse_vars_elt:nn {#3} -% \end{macrocode} -% In certain cases (when choices are involved) parsing the key results in -% changes to the default values. Therefore we have to save those back. -% \begin{macrocode} - \xtemplate_store_defaults:n { #1 / #2 } - \xtemplate_store_vars:n { #1 / #2 } - \clist_clear:N \l_xtemplate_restrict_clist - \xtemplate_store_restrictions:n { #1 / #2 } - \prop_del:NV \l_xtemplate_keytypes_prop \c_xtemplate_key_order_tl - \prop_if_empty:NF \l_xtemplate_keytypes_prop { - \prop_map_inline:Nn \l_xtemplate_keytypes_prop { - \msg_kernel_error:nnxxx { xtemplate } { key-not-implemented } - {##1} {#2} {#1} - } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_parse_vars_elt:n} -% At the implementation stage, every key must have a value given. So -% this is an error function. -% \begin{macrocode} -\cs_new:Npn \xtemplate_parse_vars_elt:n #1 { - \msg_kernel_error:nnx { xtemplate } { key-no-variable } {#1} -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_parse_vars_elt:nn} -% The actual storage part here is very simple: the storage bin name -% is placed into the property list. At the same time, a comparison is -% made with the keytypes defined earlier: if there is a mismatch then -% an error is raised. -% \begin{macrocode} -\cs_new:Npn \xtemplate_parse_vars_elt:nn #1#2 { - \tl_set:Nx \l_xtemplate_key_name_tl { \tl_to_str:n {#1} } - \tl_replace_all_in:Nnn \l_xtemplate_key_name_tl { ~ } { } - \prop_if_in:NVTF \l_xtemplate_keytypes_prop \l_xtemplate_key_name_tl { - \prop_get:NVN \l_xtemplate_keytypes_prop \l_xtemplate_key_name_tl - \l_xtemplate_keytype_tl - \xtemplate_split_keytype_arg:V \l_xtemplate_keytype_tl - \xtemplate_parse_vars_elt_aux:n {#2} - \prop_del:NV \l_xtemplate_keytypes_prop \l_xtemplate_key_name_tl - }{ - \msg_kernel_error:nnx { xtemplate } { unknown-key } {#1} - } -} -% \end{macrocode} -%\end{macro} -%\begin{macro}[aux]{\xtemplate_parse_vars_elt_aux:n} -%\begin{macro}[aux]{\xtemplate_parse_vars_elt_aux:w} -% There now needs to be some sanity checking on the variable name -% given. This does not apply for \texttt{choice} or -% \texttt{code} `variables', but in all other cases the variable needs -% to exist. Also, the only prefix acceptable is \texttt{global}. So -% there are a few related checks to make. -% \begin{macrocode} -\cs_new:Npn \xtemplate_parse_vars_elt_aux:n #1 { - \str_if_eq:VnTF \l_xtemplate_keytype_tl { choice } - { \xtemplate_implement_choices:n {#1} } - { - \str_if_eq:VnTF \l_xtemplate_keytype_tl { code } - { - \prop_put:NVn \l_xtemplate_vars_prop - \l_xtemplate_key_name_tl {#1} - } - { - \str_if_eq:noTF {#1} { \tl_head:w #1 \q_stop } - { - \cs_if_exist:NTF #1 - { - \prop_put:NVn \l_xtemplate_vars_prop - \l_xtemplate_key_name_tl {#1} - } - { - \msg_kernel_error:nnx { xtemplate } - { undeclared-variable } - { \exp_not:N #1 } - } - } - { - \tl_if_in:nnTF {#1} { global } - { \xtemplate_parse_vars_elt_aux:w #1 \q_stop } - { - \msg_kernel_error:nnx { xtemplate } { bad-variable } - { \exp_not:n {#1} } - } - } - } - } -} -\cs_new:Npn \xtemplate_parse_vars_elt_aux:w #1 global #2 \q_stop { - \tl_if_empty:nTF {#1} - { - \str_if_eq:noTF {#2} { \tl_head:w #2 \q_stop } - { - \cs_if_exist:NTF #2 - { - \prop_put:NVn \l_xtemplate_vars_prop - \l_xtemplate_key_name_tl { #1 global #2 } - } - { - \msg_kernel_error:nnx { xtemplate } - { undeclared-variable } - { \exp_not:N #2 } - } - } - { - \msg_kernel_error:nnx { xtemplate } { bad-variable } - { \exp_not:n { #1 global #2 } } - } - } - { - \msg_kernel_error:nnx { xtemplate } { bad-variable } - { \exp_not:n { #1 global #2 } } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_implement_choices:n} -% Implementing choices requires a second key--value loop. So after a -% little set-up, the standard parser is called. There is then a -% check for a default choice being set: at this stage the name of -% the choice is replaced by the code to implement it. -% \begin{macrocode} -\cs_new:Npn \xtemplate_implement_choices:n #1 { - \clist_set_eq:NN \l_xtemplate_tmp_clist \l_xtemplate_keytype_arg_tl - \prop_put:NVn \l_xtemplate_vars_prop \l_xtemplate_key_name_tl { } - \KV_process_space_removal_sanitize:NNn - \xtemplate_implement_choice_elt:n \xtemplate_implement_choice_elt:nn - {#1} - \tl_set:Nx \l_xtemplate_tmp_tl - { \l_xtemplate_key_name_tl \c_space_tl default } - \prop_if_in:NVT \l_xtemplate_values_prop \l_xtemplate_tmp_tl { - \prop_get:NVN \l_xtemplate_values_prop \l_xtemplate_tmp_tl - \l_xtemplate_tmp_tl - \xtemplate_store_value_choice:V \l_xtemplate_tmp_tl - } - \clist_if_empty:NF \l_xtemplate_tmp_clist { - \clist_map_inline:Nn \l_xtemplate_tmp_clist - { - \msg_kernel_error:nnx { xtemplate } { choice-not-implemented } - {##1} - } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_implement_choice_elt:n} -%\begin{macro}{\xtemplate_implement_choice_elt:nn} -% The actual storage of the implementation of a choice is mainly about -% error checking. The code here ensures that all choices have to have -% been declared, apart from the special \texttt{unknown} choice, which -% must come last. The code for each choice is stored along with the -% key name in the variables property list. -% \begin{macrocode} -\cs_new:Npn \xtemplate_implement_choice_elt:n #1 { - \clist_if_empty:NTF \l_xtemplate_tmp_clist { - \str_if_eq:nnF {#1} { unknown } { - \prop_get:NVN \l_xtemplate_keytypes_prop \l_xtemplate_key_name_tl - \l_xtemplate_tmp_tl - \xtemplate_split_keytype_arg:V \l_xtemplate_tmp_tl - \msg_kernel_error:nnxxx { xtemplate } { unknown-choice } - {#1} - { \l_xtemplate_key_name_tl } - { \l_xtemplate_keytype_arg_tl } - } - }{ - \clist_if_in:NnTF \l_xtemplate_tmp_clist {#1} { - \clist_remove_element:Nn \l_xtemplate_tmp_clist {#1} - }{ - \prop_get:NVN \l_xtemplate_keytypes_prop \l_xtemplate_key_name_tl - \l_xtemplate_tmp_tl - \xtemplate_split_keytype_arg:V \l_xtemplate_tmp_tl - \msg_kernel_error:nnxxx { xtemplate } { unknown-choice } - {#1} - { \l_xtemplate_key_name_tl } - { \l_xtemplate_keytype_arg_tl } - } - } -} -\cs_new:Npn \xtemplate_implement_choice_elt:nn #1#2 { - \xtemplate_implement_choice_elt:n {#1} - \tl_set:Nx \l_xtemplate_tmp_tl - { \l_xtemplate_key_name_tl \c_space_tl #1 } - \prop_put:NVn \l_xtemplate_vars_prop \l_xtemplate_tmp_tl {#2} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\subsubsection{Editing template defaults} -% -% Template defaults can be edited either with no other changes or -% to prevent further editing, forming a ``restricted template''. -% In the later case, a new template results, whereas simple editing -% does not produce a new template name. -% -%\begin{macro}{\xtemplate_declare_restricted:nnnn} -% Creating a restricted template means copying the old template to the -% new one first. -% \begin{macrocode} -\cs_new:Npn \xtemplate_declare_restricted:nnnn #1#2#3#4 { - \xtemplate_if_keys_exist:nnT {#1} {#2} - { - \xtemplate_set_template_eq:nn { #1 / #3 } { #1 / #2 } - \bool_set_true:N \l_xtemplate_restrict_bool - \xtemplate_edit_defaults_aux:nnn {#1} {#3} {#4} - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_edit_defaults:nnn} -%\begin{macro}[aux]{\xtemplate_edit_defaults_aux:nnn} -% Editing the template defaults means getting the values back out -% of the store, then parsing the list of new values before putting -% the updated list back into storage. The auxiliary function is used -% to allow code-sharing with the template-restriction system. -% \begin{macrocode} -\cs_new:Npn \xtemplate_edit_defaults:nnn { - \bool_set_false:N \l_xtemplate_restrict_bool - \xtemplate_edit_defaults_aux:nnn -} -\cs_new:Npn \xtemplate_edit_defaults_aux:nnn #1#2#3 { - \xtemplate_if_keys_exist:nnT {#1} {#2} - { - \xtemplate_recover_defaults:n { #1 / #2 } - \xtemplate_recover_restrictions:n { #1 / #2 } - \xtemplate_parse_values:nn { #1 / #2 } {#3} - \xtemplate_store_defaults:n { #1 / #2 } - \xtemplate_store_restrictions:n { #1 / #2 } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_parse_values:nn} -% The routine to parse values is the same for both editing a -% template and setting up an instance. So the code here does only the -% minimum necessary for reading the values. -% \begin{macrocode} -\cs_new:Npn \xtemplate_parse_values:nn #1#2 { - \xtemplate_recover_keytypes:n {#1} - \clist_clear:N \l_xtemplate_restrict_clist - \KV_process_space_removal_sanitize:NNn - \xtemplate_parse_values_elt:n \xtemplate_parse_values_elt:nn {#2} -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_parse_values_elt:n} -% Every key needs a value, so this is just an error routine. -% \begin{macrocode} -\cs_new:Npn \xtemplate_parse_values_elt:n #1 { - \bool_set_true:N \l_xtemplate_error_bool - \msg_kernel_error:nnx { xtemplate } { key-no-value } {#1} -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_parse_values_elt:nn} -%\begin{macro}[aux]{\xtemplate_parse_values_elt_aux:nn} -%\begin{macro}[aux]{\xtemplate_parse_values_elt_aux:Vn} -% To store the value, find the keytype then call the saving function. -% These need the current key name saved as \cs{l_xtemplate_key_name_tl}. -% When a template is being restricted, the setting code will be -% skipped for restricted keys. -% \begin{macrocode} -\cs_new:Npn \xtemplate_parse_values_elt:nn #1#2 { - \tl_set:Nx \l_xtemplate_key_name_tl { \tl_to_str:n {#1} } - \tl_replace_all_in:Nnn \l_xtemplate_key_name_tl { ~ } { } - \prop_if_in:NVTF \l_xtemplate_keytypes_prop \l_xtemplate_key_name_tl { - \bool_if:NTF \l_xtemplate_restrict_bool { - \clist_if_in:NVF \l_xtemplate_restrict_clist - \l_xtemplate_key_name_tl { - \xtemplate_parse_values_elt_aux:Vn \l_xtemplate_key_name_tl {#2} - } - }{ - \xtemplate_parse_values_elt_aux:Vn \l_xtemplate_key_name_tl {#2} - } - }{ - \msg_kernel_error:nnx { xtemplate } { unknown-key } - { \l_xtemplate_key_name_tl } - } -} -\cs_new:Npn \xtemplate_parse_values_elt_aux:nn #1#2 { - \clist_put_right:Nn \l_xtemplate_restrict_clist {#1} - \prop_get:NnN \l_xtemplate_keytypes_prop {#1} \l_xtemplate_tmp_tl - \xtemplate_split_keytype_arg:V \l_xtemplate_tmp_tl - \use:c { xtemplate_store_value_ \l_xtemplate_keytype_tl :n } {#2} -} -\cs_generate_variant:Nn \xtemplate_parse_values_elt_aux:nn { Vn } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_set_template_eq:nn} -% To copy a template, each of the lists plus the code has to be copied -% across. To keep this independent of the list storage system, it is -% all done with two-part shuffles. -% \begin{macrocode} -\cs_new:Npn \xtemplate_set_template_eq:nn #1#2 { - \xtemplate_recover_defaults:n {#2} - \xtemplate_store_defaults:n {#1} - \xtemplate_recover_keytypes:n {#2} - \xtemplate_store_keytypes:n {#1} - \xtemplate_recover_vars:n {#2} - \xtemplate_store_vars:n {#1} - \cs_gset_eq:cc { \c_xtemplate_code_root_tl #1 :w } - { \c_xtemplate_code_root_tl #2 :w } -} -% \end{macrocode} -%\end{macro} -% -%\subsubsection{Creating instances of templates} -% -%\begin{macro}{\xtemplate_declare_instance:nnnnn} -%\begin{macro}[aux]{\xtemplate_declare_instance_aux:nnnnn} -% Making an instance has two distinct parts. First, the keys given are -% parsed to transfer the values into the structured data format used -% internally. This allows the default and given values to be combined -% with no repetition. In the second step, the structured data is -% converted to pre-defined variable assignments, and these are stored -% in the function for the instance. A final check is also made so that -% there is always an instance `outside' of any collection. -% \begin{macrocode} -\cs_new:Npn \xtemplate_declare_instance:nnnnn #1#2#3#4#5 { - \xtemplate_execute_if_code_exist:nnT {#1} {#2} - { - \xtemplate_recover_defaults:n { #1 / #2 } - \xtemplate_recover_vars:n { #1 / #2 } - \xtemplate_declare_instance_aux:nnnnn {#1} {#2} {#3} {#4} {#5} - } -} -\cs_new:Npn \xtemplate_declare_instance_aux:nnnnn #1#2#3#4#5 { - \bool_set_false:N \l_xtemplate_error_bool - \xtemplate_parse_values:nn { #1 / #2 } {#5} - \bool_if:NF \l_xtemplate_error_bool { - \prop_put:Nnn \l_xtemplate_values_prop { from~template } {#2} - \xtemplate_store_values:n { #1 / #3 / #4 } - \xtemplate_convert_to_assignments: - \cs_set:cpx { \c_xtemplate_instances_root_tl #1 / #3 / #4 :w } { - \exp_not:N \xtemplate_assignments_push:n { - \exp_not:V \l_xtemplate_assignments_tl - } - \exp_not:c { \c_xtemplate_code_root_tl #1 / #2 :w } - } - \xtemplate_if_instance_exist:nnnF {#1} { } {#4} { - \cs_set_eq:cc - { \c_xtemplate_instances_root_tl #1 / / #4 :w } - { \c_xtemplate_instances_root_tl #1 / #3 / #4 :w } - } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_edit_instance:nnnn} -%\begin{macro}[aux]{\xtemplate_edit_instance_aux:nnnnn} -%\begin{macro}[aux]{\xtemplate_edit_instance_aux:nVnnn} -% Editing an instance is almost identical to declaring one. The only -% variation is the source of the values to use. When editing, they are -% recovered from the previous instance run. -% \begin{macrocode} -\cs_new:Npn \xtemplate_edit_instance:nnnn #1#2#3 { - \xtemplate_if_instance_exist:nnnTF {#1} {#2} {#3} - { - \xtemplate_recover_values:n { #1 / #2 / #3 } - \prop_get:NnN \l_xtemplate_values_prop { from~template } - \l_xtemplate_tmp_tl - \xtemplate_edit_instance_aux:nVnnn {#1} \l_xtemplate_tmp_tl - {#2} {#3} - } - { - \msg_kernel_error:nnxx { xtemplate } { unknown-instance } - {#1} {#3} - } -} -\cs_new:Npn \xtemplate_edit_instance_aux:nnnnn #1#2 { - \xtemplate_recover_vars:n { #1 / #2 } - \xtemplate_declare_instance_aux:nnnnn {#1} {#2} -} -\cs_generate_variant:Nn \xtemplate_edit_instance_aux:nnnnn { nV } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_convert_to_assignments:} -%\begin{macro}[aux]{\xtemplate_convert_to_assignments_aux:n} -%\begin{macro}[aux]{\xtemplate_convert_to_assignments_aux:nn} -%\begin{macro}[aux]{\xtemplate_convert_to_assignments_aux:nV} -% The idea on converting to a set of assignments is to loop over each -% key, so that the loop order follows the declaration order of the keys. -% This is done using a sequence as property lists are not ``ordered''. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_convert_to_assignments: { - \tl_clear:N \l_xtemplate_assignments_tl - \prop_get:NVN \l_xtemplate_keytypes_prop \c_xtemplate_key_order_tl - \l_xtemplate_key_seq - \seq_map_function:NN \l_xtemplate_key_seq - \xtemplate_convert_to_assignments_aux:n -} -\cs_new:Npn \xtemplate_convert_to_assignments_aux:n #1 { - \prop_get:NnN \l_xtemplate_keytypes_prop {#1} \l_xtemplate_tmp_tl - \xtemplate_convert_to_assignments_aux:nV {#1} \l_xtemplate_tmp_tl -} -% \end{macrocode} -% The second auxiliary function actually does the work. The -% arguments here are the key name (|#1|) and the keytype (|#2|). -% From those, the value to assign and the name of the appropriate -% variable are recovered. A bit of work is then needed to sort out -% keytypes with arguments (for example instances), and to look for -% global assignments. Once that is done, a hand-off can be made to the -% handler for the relevant keytype. -% \begin{macrocode} -\cs_new:Npn \xtemplate_convert_to_assignments_aux:nn #1#2 { - \prop_if_in:NnT \l_xtemplate_values_prop {#1} { - \prop_if_in:NnTF \l_xtemplate_vars_prop {#1} { - \prop_get:NnN \l_xtemplate_values_prop {#1} \l_xtemplate_value_tl - \prop_get:NnN \l_xtemplate_vars_prop {#1} \l_xtemplate_var_tl - \xtemplate_split_keytype_arg:n {#2} - \str_if_eq:VnF \l_xtemplate_keytype_tl { choice } { - \str_if_eq:VnF \l_xtemplate_keytype_tl { code } { - \xtemplate_find_global: - } - } - \use:c { xtemplate_assign_ \l_xtemplate_keytype_tl : } - }{ - \msg_kernel_error:nnx { xtemplate } { unknown-attribute } {#1} - } - } -} -\cs_generate_variant:Nn \xtemplate_convert_to_assignments_aux:nn { nV } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_find_global:} -%\begin{macro}[aux]{\xtemplate_find_global_aux:w} -% Global assignments should have the phrase ``global'' at the front. -% This is pretty easy to find: no other error checking, though. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_find_global: { - \bool_set_false:N \l_xtemplate_global_bool - \tl_if_in:VnT \l_xtemplate_var_tl { global } { - \exp_after:wN \xtemplate_find_global_aux:w \l_xtemplate_var_tl \q_stop - } -} -\cs_new:Npn \xtemplate_find_global_aux:w #1 global #2 \q_stop { - \tl_set:Nn \l_xtemplate_var_tl {#2} - \bool_set_true:N \l_xtemplate_global_bool -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\subsection{Using templates directly} -% -% \begin{macro}{\xtemplate_use_template:nnn} -% Directly use a template with a particular parameter setting. -% This is also picked up if used in a nested fashion inside a parameter -% list. The idea is essentially the same as creating an instance, -% just with no saving of the result. -% \begin{macrocode} -\cs_new:Npn \xtemplate_use_template:nnn #1#2#3 { - \xtemplate_execute_if_code_exist:nnT {#1} {#2} - { - \xtemplate_recover_defaults:n { #1 / #2 } - \xtemplate_recover_vars:n { #1 / #2 } - \xtemplate_parse_values:nn { #1 / #2 } {#3} - \xtemplate_convert_to_assignments: - \use:c { \c_xtemplate_code_root_tl #1 / #2 :w } - } -} -% \end{macrocode} -% \end{macro} -% -%\subsubsection{Assigning values to variables} -% -%\begin{macro}{\xtemplate_assign_boolean:} -%\begin{macro}[aux]{\xtemplate_assign_boolean_aux:n} -% Setting a Boolean value is slightly different to everything else -% as the value can be used to work out which \texttt{set} function to -% call. As long as there is no need to recover things from another -% variable, everything is pretty easy. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_assign_boolean: { - \bool_if:NTF \l_xtemplate_global_bool { - \xtemplate_assign_boolean_aux:n { bool_gset } - }{ - \xtemplate_assign_boolean_aux:n { bool_set } - } -} -\cs_new_nopar:Npn \xtemplate_assign_boolean_aux:n #1 { - \xtemplate_if_key_value:VT \l_xtemplate_value_tl { - \xtemplate_key_to_value: - } - \tl_put_left:Nx \l_xtemplate_assignments_tl { - \exp_not:c { #1 _ \l_xtemplate_value_tl :N } - \exp_not:V \l_xtemplate_var_tl - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_assign_choice:} -% Assigning a choice is actually trivial: the code needed will -% be in \cs{l_xtemplate_value_tl}, and is simply copied to the correct -% place. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_assign_choice: { - \tl_put_left:NV \l_xtemplate_assignments_tl \l_xtemplate_value_tl -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_assign_code:} -%\begin{macro}{\xtemplate_assign_code:n} -% Assigning general code to a key needs a scratch function to be created -% and run when \cs{AssignTemplateKeys} is called. So the appropriate -% definition then use is created in the token list variable. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_assign_code: { - \tl_put_left:Nx \l_xtemplate_assignments_tl { - \exp_not:N \cs_set:Npn \exp_not:N \xtemplate_assign_code:n - \exp_not:n {##1} - { \exp_not:V \l_xtemplate_var_tl } - \exp_not:N \xtemplate_assign_code:n - { \exp_not:V \l_xtemplate_value_tl } - } -} -\cs_new:Npn \xtemplate_assign_code:n #1 { } -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_assign_function:} -%\begin{macro}[aux]{\xtemplate_assign_function_aux:N} -% This looks a bit messy but is only actually one function. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_assign_function: { - \bool_if:NTF \l_xtemplate_global_bool { - \xtemplate_assign_function_aux:N \cs_gset:Npn - }{ - \xtemplate_assign_function_aux:N \cs_set:Npn - } -} -\cs_new_nopar:Npn \xtemplate_assign_function_aux:N #1 { - \tl_put_left:Nx \l_xtemplate_assignments_tl { - \exp_not:N \cs_generate_from_arg_count:NNnn - \exp_not:V \l_xtemplate_var_tl - \exp_not:N #1 - { \exp_not:V \l_xtemplate_keytype_arg_tl } - { \exp_not:V \l_xtemplate_value_tl } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_assign_instance:} -%\begin{macro}[aux]{\xtemplate_assign_instance_aux:N} -% Using an instance means adding the appropriate function creation to -% the tl. No checks are made at this stage, so if the instance is -% not valid then errors will arise later. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_assign_instance: { - \bool_if:NTF \l_xtemplate_global_bool { - \xtemplate_assign_instance_aux:N \cs_gset:Npn - }{ - \xtemplate_assign_instance_aux:N \cs_set:Npn - } -} -\cs_new_nopar:Npn \xtemplate_assign_instance_aux:N #1 { - \tl_put_left:Nx \l_xtemplate_assignments_tl { - \exp_not:N #1 \exp_not:V \l_xtemplate_var_tl { - \exp_not:N \xtemplate_use_instance:nn - { \exp_not:V \l_xtemplate_keytype_arg_tl } - { \exp_not:V \l_xtemplate_value_tl } - } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_assign_integer:} -%\begin{macro}{\xtemplate_assign_length:} -%\begin{macro}{\xtemplate_assign_skip:} -% All of the calculated assignments use the same underlying code, with -% only the low-level assignment function changing. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_assign_integer: { - \bool_if:NTF \l_xtemplate_global_bool { - \xtemplate_assign_variable:N \int_gset:Nn - }{ - \xtemplate_assign_variable:N \int_set:Nn - } -} -\cs_new_nopar:Npn \xtemplate_assign_length: { - \bool_if:NTF \l_xtemplate_global_bool { - \xtemplate_assign_variable:N \dim_gset:Nn - }{ - \xtemplate_assign_variable:N \dim_set:Nn - } -} -\cs_new_nopar:Npn \xtemplate_assign_skip: { - \bool_if:NTF \l_xtemplate_global_bool { - \xtemplate_assign_variable:N \skip_gset:Nn - }{ - \xtemplate_assign_variable:N \skip_set:Nn - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_assign_tokenlist:} -%\begin{macro}{\xtemplate_assign_commalist:} -%\begin{macro}[aux]{\xtemplate_assign_tokenlist_aux:N} -% Storing lists of tokens is easy: no complex calculations and no -% need to worry about numbers of arguments. The comma list version -% takes advantage of the low-level implementation of the variable type -% to keep down code duplication. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_assign_tokenlist: { - \bool_if:NTF \l_xtemplate_global_bool { - \xtemplate_assign_tokenlist_aux:N \tl_gset:Nn - }{ - \xtemplate_assign_tokenlist_aux:N \tl_set:Nn - } -} -\cs_new_eq:NN \xtemplate_assign_commalist: - \xtemplate_assign_tokenlist: -\cs_new_nopar:Npn \xtemplate_assign_tokenlist_aux:N #1 { - \tl_put_left:Nx \l_xtemplate_assignments_tl { - \exp_not:N #1 \exp_not:V \l_xtemplate_var_tl - { \exp_not:V \l_xtemplate_value_tl } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_assign_variable:N} -% A general-purpose function for all of the numerical assignments. -% As long as the value is not coming from another variable, the stored -% value is simply transferred for output. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_assign_variable:N #1 { - \xtemplate_if_key_value:VT \l_xtemplate_value_tl { - \xtemplate_key_to_value: - } - \tl_put_left:Nx \l_xtemplate_assignments_tl { - \exp_not:N #1 \exp_not:V \l_xtemplate_var_tl - { \exp_not:V \l_xtemplate_value_tl } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_key_to_value:} -%\begin{macro}[aux]{\xtemplate_key_to_value_aux:w} -% The idea here is to recover the attribute value of another key. To -% do that, the marker is removed and a look up takes place. If this -% is successful, then the name of the variable of the attribute is -% returned. This assumes that the value will be used in context where -% it will be converted to a value, for example when setting a number. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_key_to_value: { - \exp_after:wN \xtemplate_key_to_value_aux:w \l_xtemplate_value_tl -} -\cs_new:Npn \xtemplate_key_to_value_aux:w \KeyValue #1 { - \tl_set:Nx \l_xtemplate_tmp_tl { \tl_to_str:n {#1} } - \tl_replace_all_in:Nnn \l_xtemplate_key_name_tl { ~ } { } - \prop_if_in:NVTF \l_xtemplate_vars_prop \l_xtemplate_tmp_tl { - \prop_get:NVN \l_xtemplate_vars_prop \l_xtemplate_tmp_tl - \l_xtemplate_value_tl - }{ - \msg_kernel_error:nnx { xtemplate } { unknown-attribute } - { \l_xtemplate_tmp_tl } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\subsubsection{Using instances} -% -%\begin{macro}{\xtemplate_use_instance:nn} -%\begin{macro}[aux]{\xtemplate_use_instance_aux:nNnnn} -%\begin{macro}[aux]{\xtemplate_use_instance_aux:nn} -% Using an instance is just a question of finding the appropriate -% function. There is the possibility that a collection instance exists, -% so this is checked before trying the general instance. If nothing is -% found, an error is raised. One additional complication is that -% if the first token of argument |#2| is \cs{UseTemplate} then that -% is also valid. There is an error-test to make sure that the -% types agree, and if so the template is used directly. -% \begin{macrocode} -\cs_new:Npn \xtemplate_use_instance:nn #1#2 { - \xtemplate_if_use_template:nTF {#2} { - \xtemplate_use_instance_aux:nNnnn {#1} #2 - }{ - \xtemplate_use_instance_aux:nn {#1} {#2} - } -} -\cs_new:Npn \xtemplate_use_instance_aux:nNnnn #1#2#3#4#5 { - \str_if_eq:nnTF {#1} {#3} { - \xtemplate_use_template:nnn {#3} {#4} {#5} - }{ - \msg_kernel_error:nnxx { xtemplate } { type-mismatch } {#1} {#3} - } -} -\cs_new:Npn \xtemplate_use_instance_aux:nn #1#2 { - \xtemplate_get_collection:n {#1} - \xtemplate_if_instance_exist:nnnTF - {#1} { \l_xtemplate_collection_tl } {#2} { - \use:c { - \c_xtemplate_instances_root_tl #1 / \l_xtemplate_collection_tl /#2 - :w - } - }{ - \xtemplate_if_instance_exist:nnnTF {#1} { } {#2} { - \use:c { \c_xtemplate_instances_root_tl #1 / / #2 :w } - }{ - \msg_kernel_error:nnxx { xtemplate } { unknown-instance } - {#1} {#2} - } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\xtemplate_use_collection:nn} -% Switching to an instance collection is just a question of setting the -% appropriate list. -% \begin{macrocode} -\cs_new:Npn \xtemplate_use_collection:nn #1#2 { - \prop_put:Nnn \l_xtemplate_collections_prop {#1} {#2} -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_get_collection:n} -% Recovering the collection for a given type is pretty easy: just a read -% from the list. -% \begin{macrocode} -\cs_new:Npn \xtemplate_get_collection:n #1 { - \prop_if_in:NnTF \l_xtemplate_collections_prop {#1} { - \prop_get:NnN \l_xtemplate_collections_prop {#1} - \l_xtemplate_collection_tl - }{ - \tl_clear:N \l_xtemplate_collection_tl - } -} -% \end{macrocode} -%\end{macro} -% -%\subsubsection{Assignment manipulation} -% -% A few functions to transfer assignments about, as this is needed by -% \cs{AssignTemplateKeys}. -% -%\begin{macro}{\xtemplate_assignments_pop:} -% To actually use the assignments. -% \begin{macrocode} -\cs_new_nopar:Npn \xtemplate_assignments_pop: { - \tl_use:N \l_xtemplate_assignments_tl -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_assignments_push:n} -% Here, the assignments are stored for later use. -% \begin{macrocode} -\cs_new:Npn \xtemplate_assignments_push:n #1 { - \tl_set:Nn \l_xtemplate_assignments_tl {#1} -} -% \end{macrocode} -%\end{macro} -% -%\subsubsection{Showing templates and instances} -% -%\begin{macro}{\xtemplate_show_code:nn} -% Showing the code for a template is just a translation of -% \cs{cs_show:c}. -% \begin{macrocode} -\cs_new:Npn \xtemplate_show_code:nn #1#2 { - \xtemplate_execute_if_code_exist:nnT {#1} {#2} - { \cs_show:c { \c_xtemplate_code_root_tl #1 / #2 :w } } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\xtemplate_show_defaults:nn} -%\begin{macro}{\xtemplate_show_keytypes:nn} -%\begin{macro}{\xtemplate_show_values:nnn} -%\begin{macro}{\xtemplate_show_vars:nn} -% Showing the internal data is a case of getting the appropriate -% property list back, then displaying the scratch variable. -% \begin{macrocode} -\cs_new:Npn \xtemplate_show_defaults:nn #1#2 { - \xtemplate_if_keys_exist:nnT {#1} {#2} - { - \xtemplate_recover_defaults:n { #1 / #2 } - \prop_display:N \l_xtemplate_values_prop - } -} -\cs_new:Npn \xtemplate_show_keytypes:nn #1#2 { - \xtemplate_if_keys_exist:nnT {#1} {#2} - { - \xtemplate_recover_keytypes:n { #1 / #2 } - \prop_display:N \l_xtemplate_keytypes_prop - } -} -\cs_new:Npn \xtemplate_show_values:nnn #1#2#3 { - \xtemplate_if_instance_exist:nnnTF {#1} {#2} {#3} - { - \xtemplate_recover_values:n { #1 / #2 / #3 } - \prop_display:N \l_xtemplate_values_prop - } - { - \msg_kernel_error:nnxx { xtemplate } { unknown-instance } - {#1} {#2} - } -} -\cs_new:Npn \xtemplate_show_vars:nn #1#2 { - \xtemplate_execute_if_code_exist:nnT {#1} {#2} - { - \xtemplate_recover_vars:n { #1 / #2 } - \prop_display:N \l_xtemplate_vars_prop - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\subsubsection{Messages} -% -% The text for error messages: short and long text for all of them. -% \begin{macrocode} -\msg_kernel_new:nnnn { xtemplate } { argument-number-mismatch } - { Object~type~'#1'~takes~'#2'~not~'#3'~argument(s). } - { - Objects~of~type~'#1'~require~'#2'~arguments.\\ - You~have~tried~to~make~a~template~for~'#1'\\ - with~'#3'~arguments,~which~is~not~possible:\\ - the~number~of~arguments~must~agree.% - } -\msg_kernel_new:nnnn { xtemplate } { bad-number-of-arguments } - { - Impossible~number~of~arguments~declared~for \\ - object~type~'#1'. - } - { - An~object~may~accept~between~0~and~9~arguments.\\ - You~asked~to~use~#2~arguments:~this~is~not~supported. - } -\msg_kernel_new:nnnn { xtemplate } { bad-variable } - { Incorrect~variable~description~\msg_line_context:. } - { - The~argument~'#1'\\ - is~not~of~the~form~'<variable>'~or~'global~<variable>'.\\ - It~must~be~given~in~one~of~these~formats~to~be~used~in~a~template. - } -\msg_kernel_new:nnnn { xtemplate } { choice-not-implemented } - { The~choice~'#1'~has~no~implementation~\msg_line_context:. } - { - Each~choice~listed~in~the~interface~for~a~template~must\\ - have~an~implementation.\\ - I~did~not~find~an~implementation~for~'#1'. - } -\msg_kernel_new:nnnn { xtemplate } { choice-unknown-reserved } - { The~choice~'unknown'~cannot~be~given~for~a~template~key.} - { - The~'unknown'~choice~is~automatically~checked~by~template~when \\ - a~choice~key~is~given~with~an~unknown~value.~It~should~not~be \\ - included~in~the~list~of~named~choices~for~a~key,~and~is~always \\ - given~last~in~the~implementation~of~choices. - } -\msg_kernel_new:nnnn { xtemplate } { duplicate-key-interface } - { Key~'#1'~appears~twice~in~interface~definition~\msg_line_context:. } - { - Each~key~can~only~have~one~interface~declared~in~a~template.\\ - I~found~two~interfaces~for~'#1':~probably~a~typing~error. - } -\msg_kernel_new:nnnn { xtemplate } { empty-key-name } - { No~key~name~found~in~'#1'~\msg_line_context:. } - { - A~template~key~name~and~type~is~given~in~the~form:\\ - \c_space_tl <name>~:~<type> \\ - Parsing~your~input~I~found~a~:'~but~nothing~before~it! - } -\msg_kernel_new:nnnn { xtemplate } { key-no-value } - { The~key~'#1'~has~no~value~\msg_line_context:.} - { - When~creating~an~instance~of~a~template\\ - every~key~listed~must~include~a~value: - \c_space_tl \c_space_tl <key>~=~<value> - } -\msg_kernel_new:nnnn { xtemplate } { key-no-variable } - { The~key~'#1'~requires~implementation~details~\msg_line_context:. } - { - When~creating~template~code~using~\DeclareTemplateCode,\\ - each~key~name~must~have~an~associated~implementation.\\ - This~should~be~given~after~a~'='~sign:~I~did~not~find~one. - } -\msg_kernel_new:nnnn { xtemplate } { key-not-implemented } - { Key~'#1'~has~no~implementation~\msg_line_context:. } - { - The~definition~of~key~implementations~for~template~'#2'\\ - of~object~type~'#3'~does not~include~any~details~for~key~'#1'.\\ - The~key~was~declared~in~the~interface~definition,\\ - and~so~an~implementation~is~required. - } -\msg_kernel_new:nnnn { xtemplate } { keytype-requires-argument } - { The~keytype~'#1'~requires~an~argument~\msg_line_context:. } - { - You~should~have~put:\\ - \c_space_tl \c_space_tl <key-name>~:~#1~ - \token_to_str:N {~<argument>~\token_to_str:N } \\ - but~I~did~not~find~an~<argument>. - } -\msg_kernel_new:nnnn { xtemplate } { no-keytype } - { The~key~'#1'~is missing~a~keytype~\msg_line_context:. } - {% - You~should~have~put:\\ - \c_space_tl \c_space_tl #1~:~<keytype>\\ - but~I~did~not~find~a~<keytype>. - } -\msg_kernel_new:nnnn { xtemplate } { no-template-code } - { - The~template~'#2'~of~type~'#1'~is~unknown\\ - or~has~no~implementation. - } - { - You~need~to~declare~a~template~with~\DeclareTemplateInterface \\ - and~its~code~with~\DeclareTemplateCode prior~to~using~it. - } -\msg_kernel_new:nnnn { xtemplate } { type-mismatch } - { Object~types~'#1'~and~'#2'~do~not~agree. } - { - You~are~trying~to~use~a~template~directly~with~\UseInstance \\ - (or~a~similar~function),~but~the~object~types~do~not~match. - } -\msg_kernel_new:nnnn { xtemplate } { undeclared-variable } - { The~variable~#1~has~not~been~declared. } - { - Before~declaring~an~instance,~all~of~the~required~variables\\ - used~in~template~keys~must~be~created. - } -\msg_kernel_new:nnnn { xtemplate } { unknown-attribute } - { The~template~attribute~'#1'~is~unknown. } - { - There~is~a~definition~in~the~current~template~reading\\ - \token_to_str:N \KeyValue - \token_to_str:N {~#1~\token_to_str:N }\\ - but~there~is~no~key~called~'#1'. - } -\msg_kernel_new:nnnn { xtemplate } { unknown-choice } - { The~choice~'#1'~was~not~declared~for~key~'#2'~\msg_line_context:. } - { - The~key~'#2'~takes~a~fixed~number~of~choices:\\ - \clist_map_function:NN #3 \xtemplate_unknown_choice_aux:n - and~this~list~does~not~include~'#1'. - } -\cs_new:Npn \xtemplate_unknown_choice_aux:n #1 { -~ #1 ;\\} -\msg_kernel_new:nnnn { xtemplate } { unknown-keytype } - { The~keytype~'#1'~is~unknown~\msg_line_context:. } - { - Valid~keytypes~are:\\ - -~boolean;\\ - -~choice;\\ - -~code;\\ - -~commalist;\\ - -~function;\\ - -~instance;\\ - -~integer;\\ - -~length;\\ - -~skip;\\ - -~tokenlist. - } -\msg_kernel_new:nnnn { xtemplate } { unknown-object-type } - { The~object~type~'#1'~is~unknown~\msg_line_context:. } - { - An~object~type~needs~to~be~declared~with~ - \DeclareObjectType prior~to~using~it. - } -\msg_kernel_new:nnnn { xtemplate } { unknown-instance } - { The~instance~'#2'~of~type~'#1'~is~unknown. } - { - You~have~asked~to~use~an~instance~'#2',\\ - but~this~has~not~been~created. - } -\msg_kernel_new:nnnn { xtemplate } { unknown-key } - { Unknown~template~key~'#1'~\msg_line_context:. } - { - The~key~'#1'~was~not~declared~in~the~interface\\ - for~the~current~template.\\ - Probably~you~have~misspelled~the~key~name. - } -\msg_kernel_new:nnnn { xtemplate } { unknown-template } - { The~template~'#2'~of~type~'#1'~is~unknown~\msg_line_context:. } - { - No~interface~has~been~declared~for~a~template\\ - '#2'~of~object~type~'#1'. - } -% \end{macrocode} -% -% Information messages only have text: more text should not be needed. -% \begin{macrocode} -\msg_kernel_new:nnn { xtemplate } { define-template-code } - {Defining~template~code~for~'#1'~\msg_line_context:.} -\msg_kernel_new:nnn { xtemplate } { define-template-interface } - {Defining~template~interface~for~'#1'~\msg_line_context:.} -\msg_kernel_new:nnn { xtemplate } { define-object-type } - {Defining~object~type~'#1'~with~#2~argument(s)~\msg_line_context:.} -\msg_kernel_new:nnn { xtemplate } { redefine-template-code } - {Redefining~template~code~for~'#1'~\msg_line_context:.} -\msg_kernel_new:nnn { xtemplate } { redefine-template-interface } - {Redefining~template~interface~for~'#1'~\msg_line_context:.} -\msg_kernel_new:nnn { xtemplate } { redefine-object-type } - {Redefining~object~type~'#1'~with~#2~argument(s)~\msg_line_context:.} -% \end{macrocode} -% -%\subsubsection{User functions} -% -% The user functions provided by \pkg{xtemplate} are pretty much direct -% copies of internal ones. However, by sticking to the \pkg{xparse} -% approach only the appropriate arguments are long. -% -%\begin{macro}{\DeclareObjectType} -%\begin{macro}{\DeclareTemplateInterface} -%\begin{macro}{\DeclareTemplateCode} -%\begin{macro}{\DeclareRestrictedTemplate} -%\begin{macro}{\EditTemplateDefaults} -%\begin{macro}{\DeclareInstance} -%\begin{macro}{\DeclareCollectionInstance} -%\begin{macro}{\EditInstance} -%\begin{macro}{\EditCollectionInstance} -%\begin{macro}{\UseTemplate} -%\begin{macro}{\UseInstance} -%\begin{macro}{\UseCollection} -% All simple translations, with the appropriate long/short argument -% filtering. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \DeclareObjectType #1#2 { - \xtemplate_declare_object_type:nn {#1} {#2} -} -\cs_new_protected:Npn \DeclareTemplateInterface #1#2#3#4 { - \xtemplate_declare_template_keys:nnnn {#1} {#2} {#3} {#4} -} -\cs_new_protected:Npn \DeclareTemplateCode #1#2#3#4#5 { - \xtemplate_declare_template_code:nnnnn {#1} {#2} {#3} {#4} {#5} -} -\cs_new_protected:Npn \DeclareRestrictedTemplate #1#2#3#4 { - \xtemplate_declare_restricted:nnnn {#1} {#2} {#3} {#4} -} -\cs_new_protected:Npn \DeclareInstance #1#2#3#4 { - \xtemplate_declare_instance:nnnnn {#1} {#3} { } {#2} {#4} -} -\cs_new_protected:Npn \DeclareCollectionInstance #1#2#3#4#5 { - \xtemplate_declare_instance:nnnnn {#2} {#4} {#1} {#3} {#5} -} -\cs_new_protected:Npn \EditTemplateDefaults #1#2#3 { - \xtemplate_edit_defaults:nnn {#1} {#2} {#3} -} -\cs_new_protected:Npn \EditInstance #1#2#3 { - \xtemplate_edit_instance:nnnn {#1} { } {#2} {#3} -} -\cs_new_protected:Npn \EditCollectionInstance #1#2#3#4 { - \xtemplate_edit_instance:nnnn {#2} {#1} {#3} {#4} -} -\cs_new_protected_nopar:Npn \UseTemplate #1#2#3 { - \xtemplate_use_template:nnn {#1} {#2} {#3} -} -\cs_new_protected_nopar:Npn \UseInstance #1#2 { - \xtemplate_use_instance:nn {#1} {#2} -} -\cs_new_protected_nopar:Npn \UseCollection #1#2 { - \xtemplate_use_collection:nn {#1} {#2} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\ShowTemplateCode} -%\begin{macro}{\ShowTemplateDefaults} -%\begin{macro}{\ShowTemplateKeytypes} -%\begin{macro}{\ShowTemplateVariables} -%\begin{macro}{\ShowInstanceValues} -%\begin{macro}{\ShowCollectionInstanceValues} -% The show functions are again just translation. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \ShowTemplateCode #1#2 { - \xtemplate_show_code:nn {#1} {#2} -} -\cs_new_protected_nopar:Npn \ShowTemplateDefaults #1#2 { - \xtemplate_show_defaults:nn {#1} {#2} -} -\cs_new_protected_nopar:Npn \ShowTemplateKeytypes #1#2 { - \xtemplate_show_keytypes:nn {#1} {#2} -} -\cs_new_protected_nopar:Npn \ShowTemplateVariables #1#2 { - \xtemplate_show_vars:nn {#1} {#2} -} -\cs_new_protected_nopar:Npn \ShowInstanceValues #1#2 { - \xtemplate_show_values:nnn {#1} { } {#2} -} -\cs_new_protected_nopar:Npn \ShowCollectionInstanceValues #1#2#3 { - \xtemplate_show_values:nnn {#1} {#2} {#3} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}[TF]{\IfInstanceExist} -% More direct translation: only the base instance is checked for. -% \begin{macrocode} -\cs_new_nopar:Npn \IfInstanceExistTF #1#2 { - \xtemplate_if_instance_exist:nnnTF {#1} { } {#2} -} -\cs_new_nopar:Npn \IfInstanceExistT #1#2 { - \xtemplate_if_instance_exist:nnnT {#1} { } {#2} -} -\cs_new_nopar:Npn \IfInstanceExistF #1#2 { - \xtemplate_if_instance_exist:nnnF {#1} { } {#2} -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\EvaluateNow} -%\begin{macro}{\KeyValue} -% These are both do nothing functions. Both simply dump their arguments -% when executed: this should not happen with \cs{KeyValue}. -% -% They need to be expandable as they might get called in the context of -% setting some register value. -% \begin{macrocode} -\cs_new_protected:Npn \EvaluateNow #1 {#1} -\cs_new_protected:Npn \KeyValue #1 {#1} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\AssignTemplateKeys} -% A short call to use a token register by proxy. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \AssignTemplateKeys { - \xtemplate_assignments_pop: -} -% \end{macrocode} -%\end{macro} -% -% -% -%\subsubsection{Recent additions to the code} -% -% \begin{macro}{\TP_split_finite_skip_value:nnNN} -% This macro is for use in error checking template values like -% "text-float-sep" that can't contain infinite glue and needs the -% shrink and/or stretch components. First argument is the skip -% register (which is likely to be user input), second is a template -% key name, and the last two are the \meta{dimen} registers that -% stores the stretch and shrink components. Assignments are global. -% \begin{macrocode} -\cs_new_nopar:Npn \TP_split_finite_skip_value:nnNN #1#2{ - \skip_split_finite_else_action:nnNN {#1} { - \PackageError{xtemplate}{Value~ for~ key~ #2~ contains~ `fil(ll)'} - {Only~ finite~ minus~ or~ plus~ parts~ are~ allowed~ for~ this~ key.} - } -} -% \end{macrocode} -% \end{macro} -% -% \begin{macrocode} -%</initex|package> -% \end{macrocode} -% -%\PrintIndex -% -%\end{implementation} diff --git a/Master/texmf-dist/source/latex/xpackages/xcoffins/l3coffins.dtx b/Master/texmf-dist/source/latex/xpackages/xcoffins/l3coffins.dtx deleted file mode 100644 index 59958df042f..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xcoffins/l3coffins.dtx +++ /dev/null @@ -1,2137 +0,0 @@ -% \iffalse -%% File l3coffins.dtx (C) Copyright 2010 LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%% -%% This file is part of the ``xcoffins bundle'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -%<*driver|package> -\RequirePackage{expl3} -\RequirePackage{graphicx,xcolor,trace} -\GetIdInfo$Id: l3coffins.dtx 2209 2011-03-23 08:33:19Z joseph $ - {Coffins} -%</driver|package> -%<*driver> -%\fi -\ProvidesFile{\filename.\filenameext} - [\filedate\space v\fileversion\space\filedescription] -%\iffalse -\documentclass{l3doc} -\begin{document} - \DocInput{\jobname.dtx} -\end{document} -%</driver> -%\fi -% -%\title{^^A -% The \LaTeX3 kernel: coffins\thanks{^^A -% This file describes v\fileversion, last revised \filedate.^^A -% }^^A -%} -%\author{\Team}^^A -% -%\date{Released \filedate} -% -%\maketitle -% -%\begin{abstract} -% A \LaTeX3 `coffin' is a design-level method for typesetting -% boxed material. The structure of coffins contains not only the -% boxed material itself but also information about the size of the -% box and potential alignment positions. This structure makes it is -% possible to build complex layouts rapidly by assembling coffins. -% The code here provides the low-level support system for coffins. -%\end{abstract} -% -%\tableofcontents -% -%\begin{documentation} -% -%\section{Introduction} -% -% The material in this module provides the low-level support system -% for coffins. For details about the design concept of a coffin, see -% the \pkg{xcoffins} module. -% -%\section{Code-level functions} -% -%\begin{function}{ -% \coffin_new:N , -% \coffin_new:c , -%} -% \begin{syntax} -% \cs{coffin_new:N} \meta{coffin} -% \end{syntax} -% Creates a new \meta{coffin} or raises an error if the name is -% already taken. The declaration is global. The \meta{coffin} will -% initially be empty. -%\end{function} -% -%\begin{function}{ -% \coffin_clear:N , -% \coffin_clear:c , -%} -% \begin{syntax} -% \cs{coffin_clear:N} \meta{coffin} -% \end{syntax} -% Clears the content of the \meta{coffin} within the current \TeX\ -% group level. -%\end{function} -% -%\begin{function}{ -% \coffin_set_eq:NN , -% \coffin_set_eq:Nc , -% \coffin_set_eq:cN , -% \coffin_set_eq:cc , -%} -% \begin{syntax} -% \cs{coffin_set_eq:NN} \meta{coffin1} \meta{coffin2} -% \end{syntax} -% Sets both the content and poles of \meta{coffin1} equal to those -% of \meta{coffin2} within the current \TeX\ group level. -%\end{function} -% -%\begin{function}{ -% \hcoffin_set:Nn , -% \hcoffin_set:cn , -%} -% \begin{syntax} -% \cs{hcoffin_set:Nn} \meta{coffin} \Arg{material} -% \end{syntax} -% Typesets the \meta{material} in horizontal mode, storing the result -% in the \meta{coffin}. The standard poles for the \meta{coffin} are -% then set up based on the size of the typeset material. -%\end{function} -% -%\begin{function}{ -% \vcoffin_set:Nnn , -% \vcoffin_set:cnn , -%} -% \begin{syntax} -% \cs{vcoffin_set:Nnn} \meta{coffin} \Arg{width} \Arg{material} -% \end{syntax} -% Typesets the \meta{material} in vertical mode constrained to the -% given \meta{width} and stores the result in the \meta{coffin}. The -% standard poles for the \meta{coffin} are then set up based on the -% size of the typeset material. -%\end{function} -% -%\begin{function}{ -% \coffin_set_horizontal_pole:Nnn , -% \coffin_set_horizontal_pole:cnn , -%} -% \begin{syntax} -% \cs{coffin_set_horizontal_pole:Nnn} \meta{coffin} -% ~~\Arg{pole} \Arg{offset} -% \end{syntax} -% Sets the \meta{pole} to run horizontally through the \meta{coffin}. -% The \meta{pole} will be located at the \meta{offset} from the -% bottom edge of the bounding box of the \meta{coffin}. The -% \meta{offset} should be given as a dimension expression; this may -% include the terms cs{TotalHeight}, \cs{Height}, \cs{Depth} and -% \cs{Width}, which will evaluate to the appropriate dimensions of -% the \meta{coffin}. -%\end{function} -% -%\begin{function}{ -% \coffin_set_vertical_pole:Nnn , -% \coffin_set_vertical_pole:cnn , -%} -% \begin{syntax} -% \cs{coffin_set_vertical_pole:Nnn} \meta{coffin} -% ~~\Arg{pole} \Arg{offset} -% \end{syntax} -% Sets the \meta{pole} to run vertically through the \meta{coffin}. -% The \meta{pole} will be located at the \meta{offset} from the -% left-hand edge of the bounding box of the \meta{coffin}. The -% \meta{offset} should be given as a dimension expression; this may -% include the terms \cs{TotalHeight}, \cs{Height}, \cs{Depth} and -% \cs{Width}, which will evaluate to the appropriate dimensions of -% the \meta{coffin}. -%\end{function} -% -%\begin{function}{ -% \coffin_rotate:Nn , -% \coffin_rotate:cn , -%} -% \begin{syntax} -% \cs{coffin_rotate:Nn} \meta{coffin} \Arg{angle} -% \end{syntax} -% Rotates the \meta{coffin} by the given \meta{angle} (given in -% degrees counter-clockwise). This process will rotate both the -% coffin content and poles. Multiple rotations will not result in -% the bounding box of the coffin growing unnecessarily. -%\end{function} -% -%\begin{function}{ -% \coffin_attach:NnnNnnnn , -% \coffin_attach:cnnNnnnn , -% \coffin_attach:Nnncnnnn , -% \coffin_attach:cnncnnnn , -%} -% \begin{syntax} -% \cs{coffin_attach:NnnNnnnn} -% ~~\meta{coffin1} \Arg{coffin1-pole1} \Arg{coffin1-pole2} -% ~~\meta{coffin2} \Arg{coffin2-pole1} \Arg{coffin2-pole2} -% ~~\Arg{x-offset} \Arg{y-offset} -% \end{syntax} -% This function carries out alignment such that the bounding box -% of \meta{coffin1} is not altered, \emph{i.e.}~\meta{coffin2} can -% protrude outside of the bounding box of the coffin. The alignment -% is carried out by first calculating \meta{handle1}, the -% point of intersection of \meta{coffin1-pole1} and -% \meta{coffin1-pole2}, and \meta{handle2}, the point of intersection -% of \meta{coffin2-pole1} and \meta{coffin2-pole2}. \meta{coffin2} is -% then attached to \meta{coffin1} such that the relationship between -% \meta{handle1} and \meta{handle2} is described by the \meta{x-offset} -% and \meta{y-offset}. The two offsets should be given as dimension -% expressions. -%\end{function} -% -%\begin{function}{ -% \coffin_join:NnnNnnnn , -% \coffin_join:cnnNnnnn , -% \coffin_join:Nnncnnnn , -% \coffin_join:cnncnnnn , -%} -% \begin{syntax} -% \cs{coffin_join:NnnNnnnn} -% ~~\meta{coffin1} \Arg{coffin1-pole1} \Arg{coffin1-pole2} -% ~~\meta{coffin2} \Arg{coffin2-pole1} \Arg{coffin2-pole2} -% ~~\Arg{x-offset} \Arg{y-offset} -% \end{syntax} -% This function carries out alignment such that the bounding box -% of \meta{coffin1} after the process will expand. The new bounding -% box will cover the area contain the bounding boxes of the two -% original coffins. The alignment is carried out by first calculating -% \meta{handle1}, the point of intersection of \meta{coffin1-pole1} and -% \meta{coffin1-pole2}, and \meta{handle2}, the point of intersection -% of \meta{coffin2-pole1} and \meta{coffin2-pole2}. \meta{coffin2} is -% then attached to \meta{coffin1} such that the relationship between -% \meta{handle1} and \meta{handle2} is described by the \meta{x-offset} -% and \meta{y-offset}. The two offsets should be given as dimension -% expressions. -%\end{function} -% -%\begin{function}{ -% \coffin_typeset:Nnnnn | -% \coffin_typeset:cnnnn | -%} -% \begin{syntax} -% \cs{coffin_typeset:Nnnnn} \meta{coffin} \Arg{pole1} \Arg{pole2} -% ~~\Arg{x-offset} \Arg{y-offset} -% \end{syntax} -% Typesetting is carried out by first calculating \meta{handle}, the -% point of intersection of \meta{pole1} and \meta{pole2}. The coffin -% is then typeset such that the relationship between the current -% reference point in the document and the \meta{handle} is described -% by the \meta{x-offset} and \meta{y-offset}. The two offsets should -% be given as dimension expressions. Typesetting a coffin is -% therefore analogous to carrying out an alignment where the -% `parent' coffin is the current insertion point. -%\end{function} -% -%\begin{function}{ -% \coffin_display_handles:cn , -% \coffin_display_handles:cn , -%} -% \begin{syntax} -% \cs{coffin_display_handles:Nn} \meta{coffin} \Arg{colour} -% \end{syntax} -% This function first calculates the intersections between all of -% the \meta{poles} of the \meta{coffin} to give a set of -% \meta{handles}. It then prints the \meta{coffin} at the current -% location in the source, with the position of the \meta{handles} -% marked on the coffin. The \meta{handles} will be labelled as part -% of this process: the locations of the \meta{handles} and the labels -% are both printed in the \meta{colour} specified. -%\end{function} -% -%\begin{function}{ -% \coffin_mark_handle:Nnnn , -% \coffin_mark_handle:cnnn , -%} -% \begin{syntax} -% \cs{coffin_mark_handle:Nnnn} \meta{coffin} \Arg{pole1} \Arg{pole2} -% ~~\Arg{colour} -% \end{syntax} -% This function first calculates the \meta{handle} for the -% \meta{coffin} as defined by the intersection of \meta{pole1} and -% \meta{pole2}. It then marks the position of the \meta{handle} -% on the \meta{coffin}. The \meta{handle} will be labelled as part of -% this process: the location of the \meta{handle} and the label are -% both printed in the \meta{colour} specified. -%\end{function} -% -%\begin{function}{ -% \coffin_show_structure:N , -% \coffin_show_structure:c , -%} -% \begin{syntax} -% \cs{coffin_show_structure:N} \meta{coffin} -% \end{syntax} -% This function shows the structural information about the -% \meta{coffin} in the terminal. The width, height and depth of the -% typeset material are given, along with the location of all of the -% poles of the coffin. -% -% Notice that the poles of a coffin are defined by four values: -% the \( x \) and \( y \) co-ordinates of a point that the pole -% passes through and the \( x \)- and \( y \)-components of a -% vector denoting the direction of the pole. It is the ratio between -% the later, rather than the absolute values, which determines the -% direction of the pole. -%\end{function} -% -%\end{documentation} -% -%\begin{implementation} -% -%\section{Implementation} -% -% \begin{macrocode} -%<*package> -% \end{macrocode} -% -% \begin{macrocode} -\ProvidesExplPackage - {\filename}{\filedate}{\fileversion}{\filedescription} -% \end{macrocode} -% -%\subsection{Coffins: data structures and general variables} -% -%\begin{macro}{\l_coffin_tmp_box} -%\begin{macro}{\l_coffin_tmp_dim} -%\begin{macro}{\l_coffin_tmp_fp} -%\begin{macro}{\l_coffin_tmp_tl} -% Scratch variables. -% \begin{macrocode} -\box_new:N \l_coffin_tmp_box -\dim_new:N \l_coffin_tmp_dim -\fp_new:N \l_coffin_tmp_fp -\tl_new:N \l_coffin_tmp_tl -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\c_coffin_corners_prop} -% The `corners;' of a coffin define the real content, as -% opposed to the \TeX\ bounding box. They all start off in the same -% place, of course. -% \begin{macrocode} -\prop_new:N \c_coffin_corners_prop -\tl_set:Nn \l_coffin_tmp_tl { { 0 pt } { 0 pt } } -\prop_put:Nno \c_coffin_corners_prop { tl } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_corners_prop { tr } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_corners_prop { bl } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_corners_prop { br } { \l_coffin_tmp_tl } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\c_coffin_poles_prop} -% Pole positions are given for horizontal, vertical and reference-point -% based values. -% \begin{macrocode} -\prop_new:N \c_coffin_poles_prop -\tl_set:Nn \l_coffin_tmp_tl { { 0 pt } { 0 pt } { 0 pt } { 1000 pt } } -\prop_put:Nno \c_coffin_poles_prop { l } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_poles_prop { hc } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_poles_prop { r } { \l_coffin_tmp_tl } -\tl_set:Nn \l_coffin_tmp_tl { { 0 pt } { 0 pt } { 1000 pt } { 0 pt } } -\prop_put:Nno \c_coffin_poles_prop { b } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_poles_prop { vc } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_poles_prop { t } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_poles_prop { B } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_poles_prop { H } { \l_coffin_tmp_tl } -\prop_put:Nno \c_coffin_poles_prop { T } { \l_coffin_tmp_tl } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_coffin_calc_a_fp} -%\begin{macro}{\l_coffin_calc_b_fp} -%\begin{macro}{\l_coffin_calc_c_fp} -%\begin{macro}{\l_coffin_calc_d_fp} -%\begin{macro}{\l_coffin_calc_result_fp} -% Used for calculations of intersections and in other internal places. -% \begin{macrocode} -\fp_new:N \l_coffin_calc_a_fp -\fp_new:N \l_coffin_calc_b_fp -\fp_new:N \l_coffin_calc_c_fp -\fp_new:N \l_coffin_calc_d_fp -\fp_new:N \l_coffin_calc_result_fp -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_coffin_error_bool} -% For propagating errors so that parts of the code can work around them. -% \begin{macrocode} -\bool_new:N \l_coffin_error_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_coffin_offset_x_dim} -%\begin{macro}{\l_coffin_offset_y_dim} -% The offset between two sets of coffin handles when typesetting. These -% values are corrected from those requested in an alignment for the -% positions of the handles. -% \begin{macrocode} -\dim_new:N \l_coffin_offset_x_dim -\dim_new:N \l_coffin_offset_y_dim -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_coffin_pole_a_tl} -%\begin{macro}{\l_coffin_pole_b_tl} -% Needed for finding the intersection of two poles. -% \begin{macrocode} -\tl_new:N \l_coffin_pole_a_tl -\tl_new:N \l_coffin_pole_b_tl -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_coffin_sin_fp} -%\begin{macro}{\l_coffin_cos_fp} -% Used for rotations to get the sine and cosine values. -% \begin{macrocode} -\fp_new:N \l_coffin_sin_fp -\fp_new:N \l_coffin_cos_fp -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_coffin_x_dim} -%\begin{macro}{\l_coffin_y_dim} -%\begin{macro}{\l_coffin_x_prime_dim} -%\begin{macro}{\l_coffin_y_prime_dim} -% For calculating intersections and so forth. -% \begin{macrocode} -\dim_new:N \l_coffin_x_dim -\dim_new:N \l_coffin_y_dim -\dim_new:N \l_coffin_x_prime_dim -\dim_new:N \l_coffin_y_prime_dim -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_coffin_x_fp} -%\begin{macro}{\l_coffin_y_fp} -%\begin{macro}{\l_coffin_x_prime_fp} -%\begin{macro}{\l_coffin_y_prime_fp} -% Used for calculations where there are clear \( x \)- and -% \( y \)-components, for example during vector rotation. -% \begin{macrocode} -\fp_new:N \l_coffin_x_fp -\fp_new:N \l_coffin_y_fp -\fp_new:N \l_coffin_x_prime_fp -\fp_new:N \l_coffin_y_prime_fp -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_coffin_Depth_dim} -%\begin{macro}{\l_coffin_Height_dim} -%\begin{macro}{\l_coffin_TotalHeight_dim} -%\begin{macro}{\l_coffin_Width_dim} -% Dimensions for the various parts of a coffin. -% \begin{macrocode} -\dim_new:N \l_coffin_Depth_dim -\dim_new:N \l_coffin_Height_dim -\dim_new:N \l_coffin_TotalHeight_dim -\dim_new:N \l_coffin_Width_dim -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\coffin_saved_Depth:} -%\begin{macro}{\coffin_saved_Height:} -%\begin{macro}{\coffin_saved_TotalHeight:} -%\begin{macro}{\coffin_saved_Width:} -% Used to save the meaning of \cs{Depth}, \cs{Height}, \cs{TotalHeight} -% and \cs{Width}. -% \begin{macrocode} -\cs_new_nopar:Npn \coffin_saved_Depth: { } -\cs_new_nopar:Npn \coffin_saved_Height: { } -\cs_new_nopar:Npn \coffin_saved_TotalHeight: { } -\cs_new_nopar:Npn \coffin_saved_Width: { } -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\subsection{Basic coffin functions} -% -% There are a number of basic functions needed for creating coffins and -% placing material in them. This all relies on the following data -% structures. -% -%\begin{macro}{\coffin_if_exist_execute:Nn} -% Several of the higher-level coffin functions will give multiple -% errors if the coffin does not exist. A cleaner way to handle this -% is provided here: both the box and the coffin structure are -% checked. -% \begin{macrocode} -\cs_new_protected:Npn \coffin_if_exist_execute:Nn #1#2 { - \cs_if_exist:NTF #1 - { - \cs_if_exist:cTF { l_coffin_poles_ \tex_number:D #1 _prop } - { #2 } - { - \msg_kernel_error:nnx { coffin } { unknown-coffin } - { \token_to_str:N #1 } - } - } - { - \msg_kernel_error:nnx { coffin } { unknown-coffin } - { \token_to_str:N #1 } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{ -% \coffin_clear:N , -% \coffin_clear:c , -%} -% Clearing coffins means emptying the box and resetting all of the -% structures. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_clear:N #1 { - \coffin_if_exist_execute:Nn #1 - { - \box_clear:N #1 - \coffin_reset_structure:N #1 - } -} -\cs_generate_variant:Nn \coffin_clear:N { c } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{ -% \coffin_new:N , -% \coffin_new:c , -%} -% Creating a new coffin means making the underlying box and adding the -% data structures. These are created globally, as there is a need to -% avoid any strange effects if the coffin is created inside a group. -% This means that the usual rule about \cs{l_\ldots} variables has -% to be broken. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_new:N #1 { - \box_new:N #1 - \cs_gundefine:c { l_coffin_corners_ \tex_number:D #1 _prop } - \cs_gundefine:c { l_coffin_poles_ \tex_number:D #1 _prop } - \prop_new:c { l_coffin_corners_ \tex_number:D #1 _prop } - \prop_new:c { l_coffin_poles_ \tex_number:D #1 _prop } - \prop_gset_eq:cN { l_coffin_corners_ \tex_number:D #1 _prop } - \c_coffin_corners_prop - \prop_gset_eq:cN { l_coffin_poles_ \tex_number:D #1 _prop } - \c_coffin_poles_prop -} -\cs_generate_variant:Nn \coffin_new:N { c } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{ -% \hcoffin_set:Nn , -% \hcoffin_set:cn , -%} -% Horizontal coffins are relatively easy: set the appropriate box, -% reset the structures then update the handle positions. -% \begin{macrocode} -\cs_new_protected:Npn \hcoffin_set:Nn #1#2 { - \coffin_if_exist_execute:Nn #1 - { - \hbox_set:Nn #1 - { - \group_begin: - \set@color - #2 - \group_end: - } - \coffin_reset_structure:N #1 - \coffin_update_poles:N #1 - \coffin_update_corners:N #1 - } -} -\cs_generate_variant:Nn \hcoffin_set:Nn { c } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{ -% \vcoffin_set:Nnn , -% \vcoffin_set:cnn , -%} -% Setting vertical coffins is more complex. First, the material is -% typeset with a given width. The default handles and poles are set as -% for a horizontal coffin, before finding the top baseline using a -% temporary box. -% \begin{macrocode} -\cs_new_protected:Npn \vcoffin_set:Nnn #1#2#3 { - \coffin_if_exist_execute:Nn #1 - { - \vbox_set:Nn #1 - { - \dim_set:Nn \tex_hsize:D {#2} - \group_begin: - \set@color - #3 - \group_end: - } - \coffin_reset_structure:N #1 - \coffin_update_poles:N #1 - \coffin_update_corners:N #1 - \vbox_set_top:Nn \l_coffin_tmp_box { \vbox_unpack:N #1 } - \dim_set:Nn \l_coffin_tmp_dim - { \box_ht:N #1 - \box_ht:N \l_coffin_tmp_box } - \coffin_set_pole:Nnx #1 { T } - { - { 0 pt } { \dim_use:N \l_coffin_tmp_dim } { 1000 pt } { 0 pt } - } - } -} -\cs_generate_variant:Nn \vcoffin_set:Nnn { c } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{ -% \coffin_set_eq:NN , -% \coffin_set_eq:Nc , -% \coffin_set_eq:cN , -% \coffin_set_eq:cc , -%} -% Setting two coffins equal is just a wrapper around other functions. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_set_eq:NN #1#2 { - \coffin_if_exist_execute:Nn #1 - { - \box_set_eq:NN #1 #2 - \coffin_set_eq_structure:NN #1 #2 - } -} -\cs_generate_variant:Nn \coffin_set_eq:NN { c , Nc , cc } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\c_empty_coffin} -%\begin{macro}{\l_coffin_aligned_coffin} -%\begin{macro}{\l_coffin_aligned_internal_coffin} -% Special coffins: these cannot be set up earlier as they need -% \cs{coffin_new:N}. The empty coffin is set as a box as the full -% coffin-setting system needs some material which is not yet available. -% \begin{macrocode} -\coffin_new:N \c_empty_coffin -\hbox_set:Nn \c_empty_coffin { } -\coffin_new:N \l_coffin_aligned_coffin -\coffin_new:N \l_coffin_aligned_internal_coffin -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\subsection{Coffins: handle and pole management} -% -%\begin{macro}{\coffin_get_pole:NnN} -% A simple wrapper around the recovery of a coffin pole, with some -% error checking and recovery built-in. -% \begin{macrocode} -\cs_set_protected_nopar:Npn \coffin_get_pole:NnN #1#2#3 { - \prop_get:cnN { l_coffin_poles_ \tex_number:D #1 _prop } {#2} #3 - \quark_if_no_value:NT #3 - { - \msg_kernel_error:nnxx { coffin } { unknown-coffin-pole } - {#2} { \token_to_str:N #1 } - \tl_set:Nn #3 { { 0 pt } { 0 pt } { 0 pt } { 0 pt } } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_reset_structure:N} -% Resetting the structure is a simple copy job. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_reset_structure:N #1 { - \prop_set_eq:cN { l_coffin_corners_ \tex_number:D #1 _prop } - \c_coffin_corners_prop - \prop_set_eq:cN { l_coffin_poles_ \tex_number:D #1 _prop } - \c_coffin_poles_prop -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_set_eq_structure:NN} -% Setting coffin structures equal simply means copying the property -% list. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_set_eq_structure:NN #1#2 { - \prop_set_eq:cc { l_coffin_corners_ \tex_number:D #1 _prop } - { l_coffin_corners_ \tex_number:D #2 _prop } - \prop_set_eq:cc { l_coffin_poles_ \tex_number:D #1 _prop } - { l_coffin_poles_ \tex_number:D #2 _prop } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_set_user_dimensions:N} -%\begin{macro}{\coffin_end_user_dimensions:} -%\begin{macro}{\Depth} -%\begin{macro}{\Height} -%\begin{macro}{\TotalHeight} -%\begin{macro}{\Width} -% These make design-level names for the dimensions of a coffin easy to -% get at. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_set_user_dimensions:N #1 { - \cs_set_eq:NN \coffin_saved_Height: \Height - \cs_set_eq:NN \coffin_saved_Depth: \Depth - \cs_set_eq:NN \coffin_saved_TotalHeight: \TotalHeight - \cs_set_eq:NN \coffin_saved_Width: \Width - \cs_set_eq:NN \Height \l_coffin_Height_dim - \cs_set_eq:NN \Depth \l_coffin_Depth_dim - \cs_set_eq:NN \TotalHeight \l_coffin_TotalHeight_dim - \cs_set_eq:NN \Width \l_coffin_Width_dim - \dim_set:Nn \Height { \box_ht:N #1 } - \dim_set:Nn \Depth { \box_dp:N #1 } - \dim_set:Nn \TotalHeight { \box_ht:N #1 - \box_dp:N #1 } - \dim_set:Nn \Width { \box_wd:N #1 } -} -\cs_new_protected_nopar:Npn \coffin_end_user_dimensions: { - \cs_set_eq:NN \Height \coffin_saved_Height: - \cs_set_eq:NN \Depth \coffin_saved_Depth: - \cs_set_eq:NN \TotalHeight \coffin_saved_TotalHeight: - \cs_set_eq:NN \Width \coffin_saved_Width: -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{ -% \coffin_set_horizontal_pole:Nnn , -% \coffin_set_horizontal_pole:cnn , -% \coffin_set_vertical_pole:Nnn , -% \coffin_set_vertical_pole:cnn , -% \coffin_set_pole:Nnn , -% \coffin_set_pole:Nnx , -%} -% Setting the pole of a coffin at the user/designer level requires a -% bit more care. The idea here is to provide a reasonable interface to -% the system, then to do the setting with full expansion. The -% three-argument version is used internally to do a direct setting. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_set_horizontal_pole:Nnn #1#2#3 { - \coffin_if_exist_execute:Nn #1 - { - \coffin_set_user_dimensions:N #1 - \coffin_set_pole:Nnx #1 {#2} - { - { 0 pt } { \dim_eval:n {#3} } - { 1000 pt } { 0 pt } - } - \coffin_end_user_dimensions: - } -} -\cs_new_protected_nopar:Npn \coffin_set_vertical_pole:Nnn #1#2#3 { - \coffin_if_exist_execute:Nn #1 - { - \coffin_set_user_dimensions:N #1 - \coffin_set_pole:Nnx #1 {#2} - { - { \dim_eval:n {#3} } { 0 pt } - { 0 pt } { 1000 pt } - } - \coffin_end_user_dimensions: - } -} -\cs_new_protected_nopar:Npn \coffin_set_pole:Nnn #1#2#3 { - \prop_put:cnn { l_coffin_poles_ \tex_number:D #1 _prop } {#2} {#3} -} -\cs_generate_variant:Nn \coffin_set_horizontal_pole:Nnn { c } -\cs_generate_variant:Nn \coffin_set_vertical_pole:Nnn { c } -\cs_generate_variant:Nn \coffin_set_pole:Nnn { Nnx } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_update_corners:N} -% Updating the corners of a coffin is straight-forward as at this stage -% there can be no rotation. So the corners of the content are just those -% of the underlying \TeX\ box. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_update_corners:N #1 { - \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } { tl } - { { 0 pt } { \dim_use:N \box_ht:N #1 } } - \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } { tr } - { { \dim_use:N \box_wd:N #1 } { \dim_use:N \box_ht:N #1 } } - \dim_set:Nn \l_coffin_tmp_dim { - \dim_use:N \box_dp:N #1 } - \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } { bl } - { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } } - \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } { br } - { { \dim_use:N \box_wd:N #1 } { \dim_use:N \l_coffin_tmp_dim } } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_update_poles:N} -% This function is called when a coffin is set, and updates the poles to -% reflect the nature of size of the box. Thus this function only alters -% poles where the default position is dependent on the size of the box. -% It also does not set poles which are relevant only to vertical -% coffins. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_update_poles:N #1 { - \dim_set:Nn \l_coffin_tmp_dim { 0.5 \box_wd:N #1 } - \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { hc } - { { \dim_use:N \l_coffin_tmp_dim } { 0 pt } { 0 pt } { 1000 pt } } - \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { r } - { { \dim_use:N \box_wd:N #1 } { 0 pt } { 0 pt } { 1000 pt } } - \dim_set:Nn \l_coffin_tmp_dim { ( \box_ht:N #1 - \box_dp:N #1 ) / 2 } - \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { vc } - { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } { 1000 pt } { 0 pt } } - \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { t } - { { 0 pt } { \dim_use:N \box_ht:N #1 } { 1000 pt } { 0 pt } } - \dim_set:Nn \l_coffin_tmp_dim { \box_dp:N #1 } - \dim_compare:nNnF { \l_coffin_tmp_dim } = { \c_zero_dim } - { \dim_set:Nn \l_coffin_tmp_dim { -\l_coffin_tmp_dim } } - \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } { b } - { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } { 1000 pt } { 0 pt } } -} -% \end{macrocode} -%\end{macro} -% -%\subsection{Coffins: calculation of pole intersections} -% -%\begin{macro}{\coffin_calculate_intersection:Nnn} -%\begin{macro}[aux]{\coffin_calculate_intersection:nnnnnnnn} -%\begin{macro}[aux]{\coffin_calculate_intersection_aux:nnnnnN} -% The lead off in finding intersections is to recover the two poles -% and then hand off to the auxiliary for the actual calculation. There -% may of course not be an intersection, for which an error trap is -% needed. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_calculate_intersection:Nnn #1#2#3 { - \coffin_get_pole:NnN #1 {#2} \l_coffin_pole_a_tl - \coffin_get_pole:NnN #1 {#3} \l_coffin_pole_b_tl - \bool_set_false:N \l_coffin_error_bool - \exp_last_two_unbraced:Noo - \coffin_calculate_intersection:nnnnnnnn - \l_coffin_pole_a_tl \l_coffin_pole_b_tl - \bool_if:NT \l_coffin_error_bool - { - \msg_kernel_error:nn { coffin } { no-pole-intersection } - \dim_zero:N \l_coffin_x_dim - \dim_zero:N \l_coffin_y_dim - } -} -% \end{macrocode} -% The two poles passed here each have four values (as dimensions), -% (\( a \), \( b \), \( c \), \( d \)) and -% (\( a' \), \( b' \), \( c' \), \( d' \)). These are arguments -% \( 1 \)--\( 4 \) and \( 5 \)--\( 8 \), respectively. In both -% cases \( a \) and \( b \) are the co-ordinates of a point on the -% pole and \( c \) and \( d \) define the direction of the pole. Finding -% the intersection depends on the directions of the poles, which are -% given by \( d / c \) and \( d' / c' \). However, if one of the poles -% is either horizontal or vertical then one or more of \( c \), \( d \), -% \( c' \) and \( d' \) will be zero and a special case is needed. -% \begin{macrocode} -\cs_new_protected_nopar:Npn - \coffin_calculate_intersection:nnnnnnnn #1#2#3#4#5#6#7#8 { - \dim_compare:nNnTF {#3} = { \c_zero_dim } -% \end{macrocode} -% The case where the first pole is vertical. So the \( x \)-component -% of the interaction will be at \( a \). There is then a test on the -% second pole: if it is also vertical then there is an error. -% \begin{macrocode} - { - \dim_set:Nn \l_coffin_x_dim {#1} - \dim_compare:nNnTF {#7} = { \c_zero_dim } - { \bool_set_true:N \l_coffin_error_bool } -% \end{macrocode} -% The second pole may still be horizontal, in which case the -% \( y \)-component of the intersection will be \( b' \). If not, -% \[ -% y = \frac{d'}{c'} \left ( x - a' \right ) + b' -% \] -% with the \( x \)-component already known to be "#1". This calculation -% is done as a generalised auxiliary. -% \begin{macrocode} - { - \dim_compare:nNnTF {#8} = { \c_zero_dim } - { \dim_set:Nn \l_coffin_y_dim {#6} } - { - \coffin_calculate_intersection_aux:nnnnnN - {#1} {#5} {#6} {#7} {#8} \l_coffin_y_dim - } - } - } -% \end{macrocode} -% If the first pole is not vertical then it may be horizontal. If so, -% then the procedure is essentially the same as that already done but -% with the \( x \)- and \( y \)-components interchanged. -% \begin{macrocode} - { - \dim_compare:nNnTF {#4} = { \c_zero_dim } - { - \dim_set:Nn \l_coffin_y_dim {#2} - \dim_compare:nNnTF {#8} = { \c_zero_dim } - { \bool_set_true:N \l_coffin_error_bool } - { - \dim_compare:nNnTF {#7} = { \c_zero_dim } - { \dim_set:Nn \l_coffin_x_dim {#5} } -% \end{macrocode} -% The formula for the case where the second pole is neither horizontal -% nor vertical is -% \[ -% x = \frac{c'}{d'} \left ( y - b' \right ) + a' -% \] -% which is again handled by the same auxiliary. -% \begin{macrocode} - { - \coffin_calculate_intersection_aux:nnnnnN - {#2} {#6} {#5} {#8} {#7} \l_coffin_x_dim - } - } - } -% \end{macrocode} -% The first pole is neither horizontal nor vertical. This still leaves -% the second pole, which may be a special case. For those possibilities, -% the calculations are the same as above with the first and second poles -% interchanged. -% \begin{macrocode} - { - \dim_compare:nNnTF {#7} = { \c_zero_dim } - { - \dim_set:Nn \l_coffin_x_dim {#5} - \coffin_calculate_intersection_aux:nnnnnN - {#5} {#1} {#2} {#3} {#4} \l_coffin_y_dim - } - { - \dim_compare:nNnTF {#8} = { \c_zero_dim } - { - \dim_set:Nn \l_coffin_x_dim {#6} - \coffin_calculate_intersection_aux:nnnnnN - {#6} {#2} {#1} {#4} {#3} \l_coffin_x_dim - } -% \end{macrocode} -% If none of the special cases apply then there is still a need to -% check that there is a unique intersection between the two pole. This -% is the case if they have different slopes. -% \begin{macrocode} - { - \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#3} - \fp_set_from_dim:Nn \l_coffin_calc_b_fp {#4} - \fp_set_from_dim:Nn \l_coffin_calc_c_fp {#7} - \fp_set_from_dim:Nn \l_coffin_calc_d_fp {#8} - \fp_div:Nn \l_coffin_calc_b_fp \l_coffin_calc_a_fp - \fp_div:Nn \l_coffin_calc_d_fp \l_coffin_calc_c_fp - \fp_compare:nNnTF - { \l_coffin_calc_b_fp } = { \l_coffin_calc_d_fp } - { \bool_set_true:N \l_coffin_error_bool } -% \end{macrocode} -% All of the tests pass, so there is the full complexity of the -% calculation: -% \[ -% x = \frac { a ( d / c ) - a' ( d' / c' ) - b + b' } -% { ( d / c ) - ( d' / c' ) } -% \] -% and noting that the two ratios are already worked out from the test -% just performed. There is quite a bit of shuffling from dimensions to -% floating points in order to do the work. The \( y \)-values is then -% worked out using the standard auxiliary starting from the -% \( x \)-position. -% \begin{macrocode} - { - \fp_set_from_dim:Nn \l_coffin_calc_result_fp {#6} - \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#2} - \fp_sub:Nn \l_coffin_calc_result_fp - { \l_coffin_calc_a_fp } - \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#1} - \fp_mul:Nn \l_coffin_calc_a_fp - { \l_coffin_calc_b_fp } - \fp_add:Nn \l_coffin_calc_result_fp - { \l_coffin_calc_a_fp } - \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#5} - \fp_mul:Nn \l_coffin_calc_a_fp - { \l_coffin_calc_d_fp } - \fp_sub:Nn \l_coffin_calc_result_fp - { \l_coffin_calc_a_fp } - \fp_sub:Nn \l_coffin_calc_b_fp - { \l_coffin_calc_d_fp } - \fp_div:Nn \l_coffin_calc_result_fp - { \l_coffin_calc_b_fp } - \dim_set:Nn \l_coffin_x_dim - { \fp_to_dim:N \l_coffin_calc_result_fp } - \coffin_calculate_intersection_aux:nnnnnN - { \l_coffin_x_dim } - {#5} {#6} {#8} {#7} \l_coffin_y_dim - } - } - } - } - } -} -% \end{macrocode} -% The formula for finding the intersection point is in most cases the -% same. The formula here is -% \[ -% \#6 = \frac{\#5}{\#4} \left ( \#1 - \#2 \right ) + \#3 -% \] -% Thus "#4" and "#5" should be the directions of the pole while -% "#2" and "#3" are co-ordinates. -% \begin{macrocode} -\cs_new_protected_nopar:Npn - \coffin_calculate_intersection_aux:nnnnnN #1#2#3#4#5#6 { - \fp_set_from_dim:Nn \l_coffin_calc_result_fp {#1} - \fp_set_from_dim:Nn \l_coffin_calc_a_fp {#2} - \fp_set_from_dim:Nn \l_coffin_calc_b_fp {#3} - \fp_set_from_dim:Nn \l_coffin_calc_c_fp {#4} - \fp_set_from_dim:Nn \l_coffin_calc_d_fp {#5} - \fp_sub:Nn \l_coffin_calc_result_fp { \l_coffin_calc_a_fp } - \fp_div:Nn \l_coffin_calc_result_fp { \l_coffin_calc_d_fp } - \fp_mul:Nn \l_coffin_calc_result_fp { \l_coffin_calc_c_fp } - \fp_add:Nn \l_coffin_calc_result_fp { \l_coffin_calc_b_fp } - \dim_set:Nn #6 { \fp_to_dim:N \l_coffin_calc_result_fp } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\subsection{Aligning and typesetting of coffins} -% -%\begin{macro}{ -% \coffin_join:NnnNnnnn , -% \coffin_join:cnnNnnnn , -% \coffin_join:Nnncnnnn , -% \coffin_join:cnncnnnn , -%} -% This command joins two coffins, using a horizontal and vertical pole -% from each coffin and making an offset between the two. The result -% is stored as the as a third coffin, which will have all of its handles -% reset to standard values. First, the more basic alignment function is -% used to get things started. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_join:NnnNnnnn #1#2#3#4#5#6#7#8 { - \coffin_align:NnnNnnnnN - #1 {#2} {#3} #4 {#5} {#6} {#7} {#8} \l_coffin_aligned_coffin -% \end{macrocode} -% Correct the placement of the reference point. If the \( x \)-offset -% is negative then the reference point of the second box is to the left -% of that of the first, which is corrected using a kern. On the right -% side the first box might stick out, which will show up if it is wider -% than the sum of the \( x \)-offset and the width of the second box. -% So a second kern may be needed. -% \begin{macrocode} - \hbox_set:Nn \l_coffin_aligned_coffin - { - \dim_compare:nNnT { \l_coffin_offset_x_dim } < { \c_zero_dim } - { \tex_kern:D -\l_coffin_offset_x_dim } - \hbox_unpack:N \l_coffin_aligned_coffin - \dim_set:Nn \l_coffin_tmp_dim - { \l_coffin_offset_x_dim - \box_wd:N #1 + \box_wd:N #4 } - \dim_compare:nNnT { \l_coffin_tmp_dim } < { \c_zero_dim } - { \tex_kern:D -\l_coffin_tmp_dim } - } -% \end{macrocode} -% The coffin structure is reset, and the corners are cleared: only -% those from the two parent coffins are needed. -% \begin{macrocode} - \coffin_reset_structure:N \l_coffin_aligned_coffin - \prop_clear:c - { - l_coffin_corners_ \tex_number:D \l_coffin_aligned_coffin _ prop - } - \coffin_update_poles:N \l_coffin_aligned_coffin -% \end{macrocode} -% The structures of the parent coffins are now transferred to the new -% coffin, which requires that the appropriate offsets are applied. That -% will then depend on whether any shift was needed. -% \begin{macrocode} - \dim_compare:nNnTF { \l_coffin_offset_x_dim } < { \c_zero_dim } - { - \coffin_offset_poles:Nnn #1 { -\l_coffin_offset_x_dim } { 0 pt } - \coffin_offset_poles:Nnn #4 { 0 pt } { \l_coffin_offset_y_dim } - \coffin_offset_corners:Nnn #1 { -\l_coffin_offset_x_dim } { 0 pt } - \coffin_offset_corners:Nnn #4 { 0 pt } { \l_coffin_offset_y_dim } - } - { - \coffin_offset_poles:Nnn #1 { 0 pt } { 0 pt } - \coffin_offset_poles:Nnn #4 - { \l_coffin_offset_x_dim } { \l_coffin_offset_y_dim } - \coffin_offset_corners:Nnn #1 { 0 pt } { 0 pt } - \coffin_offset_corners:Nnn #4 - { \l_coffin_offset_x_dim } { \l_coffin_offset_y_dim } - } - \coffin_update_vertical_poles:NNN #1 #4 \l_coffin_aligned_coffin - \coffin_set_eq:NN #1 \l_coffin_aligned_coffin -} -\cs_generate_variant:Nn \coffin_join:NnnNnnnn { c , Nnnc , cnnc } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{ -% \coffin_attach:NnnNnnnn , -% \coffin_attach:cnnNnnnn , -% \coffin_attach:Nnncnnnn , -% \coffin_attach:cnncnnnn , -% \coffin_attach_mark:NnnNnnnn , -%} -% A more simple version of the above, as it simply uses the size of the -% first coffin for the new one. This means that the work here is rather -% simplified compared to the above code. The function used when marking -% a position is hear also as it is similar but without the structure -% updates. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_attach:NnnNnnnn #1#2#3#4#5#6#7#8 { - \coffin_align:NnnNnnnnN - #1 {#2} {#3} #4 {#5} {#6} {#7} {#8} \l_coffin_aligned_coffin - \box_set_ht:Nn \l_coffin_aligned_coffin { \box_ht:N #1 } - \box_set_dp:Nn \l_coffin_aligned_coffin { \box_dp:N #1 } - \box_set_wd:Nn \l_coffin_aligned_coffin { \box_wd:N #1 } - \coffin_reset_structure:N \l_coffin_aligned_coffin - \prop_set_eq:cc - { l_coffin_corners_ \tex_number:D \l_coffin_aligned_coffin _prop } - { l_coffin_corners_ \tex_number:D #1 _prop } - \coffin_update_poles:N \l_coffin_aligned_coffin - \coffin_offset_poles:Nnn #1 { 0 pt } { 0 pt } - \coffin_offset_poles:Nnn #4 - { \l_coffin_offset_x_dim } { \l_coffin_offset_y_dim } - \coffin_update_vertical_poles:NNN #1 #4 \l_coffin_aligned_coffin - \coffin_set_eq:NN #1 \l_coffin_aligned_coffin -} -\cs_new_protected_nopar:Npn - \coffin_attach_mark:NnnNnnnn #1#2#3#4#5#6#7#8 { - \coffin_align:NnnNnnnnN - #1 {#2} {#3} #4 {#5} {#6} {#7} {#8} \l_coffin_aligned_coffin - \box_set_ht:Nn \l_coffin_aligned_coffin { \box_ht:N #1 } - \box_set_dp:Nn \l_coffin_aligned_coffin { \box_dp:N #1 } - \box_set_wd:Nn \l_coffin_aligned_coffin { \box_wd:N #1 } - \box_set_eq:NN #1 \l_coffin_aligned_coffin -} -\cs_generate_variant:Nn \coffin_attach:NnnNnnnn { c , Nnnc , cnnc } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_align:NnnNnnnnN} -% The internal function aligns the two coffins into a third one, but -% performs no corrections on the resulting coffin poles. The process -% begins by finding the points of intersection for the poles for each -% of the input coffins. Those for the first coffin are worked out after -% those for the second coffin, as this allows the `primed' -% storage area to be used for the second coffin. The `real' box -% offsets are then calculated, before using these to re-box the -% input coffins. The default poles are then set up, but the final result -% will depend on how the bounding box is being handled. -% \begin{macrocode} -\cs_new_protected_nopar:Npn - \coffin_align:NnnNnnnnN #1#2#3#4#5#6#7#8#9 { - \coffin_calculate_intersection:Nnn #4 {#5} {#6} - \dim_set:Nn \l_coffin_x_prime_dim { \l_coffin_x_dim } - \dim_set:Nn \l_coffin_y_prime_dim { \l_coffin_y_dim } - \coffin_calculate_intersection:Nnn #1 {#2} {#3} - \dim_set:Nn \l_coffin_offset_x_dim - { \l_coffin_x_dim - \l_coffin_x_prime_dim + #7 } - \dim_set:Nn \l_coffin_offset_y_dim - { \l_coffin_y_dim - \l_coffin_y_prime_dim + #8 } - \hbox_set:Nn \l_coffin_aligned_internal_coffin - { - \box_use:N #1 - \tex_kern:D -\box_wd:N #1 - \tex_kern:D \l_coffin_offset_x_dim - \box_move_up:nn { \l_coffin_offset_y_dim } { \box_use:N #4 } - } - \coffin_set_eq:NN #9 \l_coffin_aligned_internal_coffin -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_offset_poles:Nnn} -%\begin{macro}[aux]{\coffin_offset_pole:Nnnnnnn} -% Transferring structures from one coffin to another requires that the -% positions are updated by the offset between the two coffins. This is -% done by mapping to the property list of the source coffins, moving -% as appropriate and saving to the new coffin data structures. The -% test for a "-" means that the structures from the parent coffins -% are uniquely labelled and do not depend on the order of alignment. -% The pay off for this is that "-" should not be used in coffin pole -% or handle names, and that multiple alignments do not result in a -% whole set of values. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_offset_poles:Nnn #1#2#3 { - \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop } - { \coffin_offset_pole:Nnnnnnn #1 {##1} ##2 {#2} {#3} } -} -\cs_new_protected_nopar:Npn - \coffin_offset_pole:Nnnnnnn #1#2#3#4#5#6#7#8 { - \dim_set:Nn \l_coffin_x_dim { #3 + #7 } - \dim_set:Nn \l_coffin_y_dim { #4 + #8 } - \tl_if_in:nnTF {#2} { - } - { \tl_set:Nn \l_coffin_tmp_tl { {#2} } } - { \tl_set:Nn \l_coffin_tmp_tl { { #1 - #2 } } } - \exp_last_unbraced:NNo \coffin_set_pole:Nnx \l_coffin_aligned_coffin - { \l_coffin_tmp_tl } - { - { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim } - {#5} {#6} - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\coffin_offset_corners:Nnn} -%\begin{macro}[aux]{\coffin_offset_corners:Nnnnn} -% Saving the offset corners of a coffin is very similar, except that -% there is no need to worry about naming: every corner can be saved -% here as order is unimportant. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_offset_corners:Nnn #1#2#3 { - \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop } - { \coffin_offset_corner:Nnnnn #1 {##1} ##2 {#2} {#3} } -} -\cs_new_protected_nopar:Npn \coffin_offset_corner:Nnnnn #1#2#3#4#5#6 { - \prop_put:cnx - { l_coffin_corners_ \tex_number:D \l_coffin_aligned_coffin _prop } - { #1 - #2 } - { - { \dim_eval:n { #3 + #5 } } - { \dim_eval:n { #4 + #6 } } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\coffin_update_vertical_poles:NNN} -%\begin{macro}[aux]{\coffin_update_T:nnnnnnnnN} -%\begin{macro}[aux]{\coffin_update_B:nnnnnnnnN} -% The \texttt{T} and \texttt{B} poles will need to be recalculated -% after alignment. These functions find the larger absolute value for -% the poles, but this is of course only logical when the poles are -% horizontal. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_update_vertical_poles:NNN #1#2#3 { - \coffin_get_pole:NnN #3 { #1 -T } \l_coffin_pole_a_tl - \coffin_get_pole:NnN #3 { #2 -T } \l_coffin_pole_b_tl - \exp_last_two_unbraced:Noo \coffin_update_T:nnnnnnnnN - \l_coffin_pole_a_tl \l_coffin_pole_b_tl #3 - \coffin_get_pole:NnN #3 { #1 -B } \l_coffin_pole_a_tl - \coffin_get_pole:NnN #3 { #2 -B } \l_coffin_pole_b_tl - \exp_last_two_unbraced:Noo \coffin_update_B:nnnnnnnnN - \l_coffin_pole_a_tl \l_coffin_pole_b_tl #3 -} -\cs_new_protected_nopar:Npn - \coffin_update_T:nnnnnnnnN #1#2#3#4#5#6#7#8#9 { - \dim_compare:nNnTF {#2} < {#6} - { - \coffin_set_pole:Nnx #9 { T } - { { 0 pt } {#6} { 1000 pt } { 0 pt } } - } - { - \coffin_set_pole:Nnx #9 { T } - { { 0 pt } {#2} { 1000 pt } { 0 pt } } - } -} -\cs_new_protected_nopar:Npn - \coffin_update_B:nnnnnnnnN #1#2#3#4#5#6#7#8#9 { - \dim_compare:nNnTF {#2} < {#6} - { - \coffin_set_pole:Nnx #9 { B } - { { 0 pt } {#2} { 1000 pt } { 0 pt } } - } - { - \coffin_set_pole:Nnx #9 { B } - { { 0 pt } {#6} { 1000 pt } { 0 pt } } - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{ -% \coffin_typeset:Nnnnn , -% \coffin_typeset:cnnnn , -%} -% Typesetting a coffin means aligning it with the current position, -% which is done using a coffin with no content at all. This is done -% using the same approach as \cs{coffin_align:NnnNnnnnN} but without the -% offset corrections (which would be thrown away). The same is true -% for overlaying coffins, which uses the known size of an empty -% box! -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_typeset:Nnnnn #1#2#3#4#5 { - \coffin_align:NnnNnnnnN \c_empty_coffin { H } { l } - #1 {#2} {#3} {#4} {#5} \l_coffin_aligned_coffin - \hbox_set:Nn \l_coffin_aligned_coffin - { - \dim_compare:nNnT { \l_coffin_offset_x_dim } < { \c_zero_dim } - { \tex_kern:D -\l_coffin_offset_x_dim } - \hbox_unpack:N \l_coffin_aligned_coffin - \dim_set:Nn \l_coffin_tmp_dim - { \l_coffin_offset_x_dim + \box_wd:N #1 } - \dim_compare:nNnT { \l_coffin_tmp_dim } < { \c_zero_dim } - { \tex_kern:D -\l_coffin_tmp_dim } - } - \hbox_unpack:N \c_empty_box - \box_use:N \l_coffin_aligned_coffin -} -\cs_generate_variant:Nn \coffin_typeset:Nnnnn { c } -% \end{macrocode} -%\end{macro} -% -%\subsection{Rotating coffins} -% -%\begin{macro}{\l_coffin_bounding_prop} -% A property list for the bounding box of a coffin. This is only needed -% during the rotation, so there is just the one. -% \begin{macrocode} -\prop_new:N \l_coffin_bounding_prop -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_coffin_bounding_shift_dim} -% The shift of the bounding box of a coffin from the real content. -% \begin{macrocode} -\dim_new:N \l_coffin_bounding_shift_dim -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_coffin_left_corner_dim} -%\begin{macro}{\l_coffin_right_corner_dim} -%\begin{macro}{\l_coffin_bottom_corner_dim} -%\begin{macro}{\l_coffin_top_corner_dim} -% These are used to hold maxima for the various corner values: these -% thus define the minimum size of the bounding box after rotation. -% \begin{macrocode} -\dim_new:N \l_coffin_left_corner_dim -\dim_new:N \l_coffin_right_corner_dim -\dim_new:N \l_coffin_bottom_corner_dim -\dim_new:N \l_coffin_top_corner_dim -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{ -% \coffin_rotate:Nn , -% \coffin_rotate:cn , -%} -% Rotating a coffin requires several steps which can be conveniently -% run together. The first step is to convert the angle given in degrees -% to one in radians. This is then used to set \cs{l_coffin_sin_fp} and -% \cs{l_coffin_cos_fp}, which are carried through unchanged for the rest -% of the procedure. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_rotate:Nn #1#2 { - \fp_set:Nn \l_coffin_tmp_fp {#2} - \fp_div:Nn \l_coffin_tmp_fp { 180 } - \fp_mul:Nn \l_coffin_tmp_fp { \c_pi_fp } - \fp_sin:Nn \l_coffin_sin_fp { \l_coffin_tmp_fp } - \fp_cos:Nn \l_coffin_cos_fp { \l_coffin_tmp_fp } -% \end{macrocode} -% The corners and poles of the coffin can now be rotated around the -% origin. This is best achieved using mapping functions. -% \begin{macrocode} - \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop } - { \coffin_rotate_corner:Nnnn #1 {##1} ##2 } - \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop } - { \coffin_rotate_pole:Nnnnnn #1 {##1} ##2 } -% \end{macrocode} -% The bounding box of the coffin needs to be rotated, and to do this -% the corners have to be found first. They are then rotated in the same -% way as the corners of the coffin material itself. -% \begin{macrocode} - \coffin_set_bounding:N #1 - \prop_map_inline:Nn \l_coffin_bounding_prop - { \coffin_rotate_bounding:nnn {##1} ##2 } -% \end{macrocode} -% At this stage, there needs to be a calculation to find where the -% corners of the content and the box itself will end up. -% \begin{macrocode} - \coffin_find_corner_maxima:N #1 - \coffin_find_bounding_shift: - \hbox_set:Nn #1 { \rotatebox {#2} { \box_use:N #1 } } -% \end{macrocode} -% The correction of the box position itself takes place here. The idea -% is that the bounding box for a coffin is tight up to the content, and -% has the reference point at the bottom-left. The \( x \)-direction is -% handled by moving the content by the difference in the positions of -% the bounding box and the content left edge. The \( y \)-direction is -% dealt with by moving the box down by any depth it has acquired. -% \begin{macrocode} - \hbox_set:Nn #1 - { - \tex_kern:D \l_coffin_bounding_shift_dim - \tex_kern:D -\l_coffin_left_corner_dim - \box_move_down:nn { \l_coffin_bottom_corner_dim } - { \box_use:N #1 } - } -% \end{macrocode} -% If there have been any previous rotations then the size of the -% bounding box will be bigger than the contents. This can be corrected -% easily by setting the size of the box to the height and width of the -% content. -% \begin{macrocode} - \box_set_ht:Nn #1 - { \l_coffin_top_corner_dim - \l_coffin_bottom_corner_dim } - \box_set_dp:Nn #1 { 0 pt } - \box_set_wd:Nn #1 - { \l_coffin_right_corner_dim - \l_coffin_left_corner_dim } -% \end{macrocode} -% The final task is to move the poles and corners such that they are -% back in alignment with the box reference point. -% \begin{macrocode} - \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop } - { \coffin_shift_corner:Nnnn #1 {##1} ##2 } - \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop } - { \coffin_shift_pole:Nnnnnn #1 {##1} ##2 } -} -\cs_generate_variant:Nn \coffin_rotate:Nn { c } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_set_bounding:N} -% The bounding box corners for a coffin are easy enough to find: this -% is the same code as for the corners of the material itself, but -% using a dedicated property list. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_set_bounding:N #1 { - \prop_put:Nnx \l_coffin_bounding_prop { tl } - { { 0 pt } { \dim_use:N \box_ht:N #1 } } - \prop_put:Nnx \l_coffin_bounding_prop { tr } - { { \dim_use:N \box_wd:N #1 } { \dim_use:N \box_ht:N #1 } } - \dim_set:Nn \l_coffin_tmp_dim { - \dim_use:N \box_dp:N #1 } - \prop_put:Nnx \l_coffin_bounding_prop { bl } - { { 0 pt } { \dim_use:N \l_coffin_tmp_dim } } - \prop_put:Nnx \l_coffin_bounding_prop { br } - { { \dim_use:N \box_wd:N #1 } { \dim_use:N \l_coffin_tmp_dim } } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_rotate_bounding:nnn} -%\begin{macro}{\coffin_rotate_corner:Nnnn} -% Rotating the position of the corner of the coffin is just a case -% of treating this as a vector from the reference point. The same -% treatment is used for the corners of the material itself and the -% bounding box. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_rotate_bounding:nnn #1#2#3 { - \coffin_rotate_vector:nnNN {#2} {#3} \l_coffin_x_dim \l_coffin_y_dim - \prop_put:Nnx \l_coffin_bounding_prop {#1} - { { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim } } -} -\cs_new_protected_nopar:Npn \coffin_rotate_corner:Nnnn #1#2#3#4 { - \coffin_rotate_vector:nnNN {#3} {#4} \l_coffin_x_dim \l_coffin_y_dim - \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } {#2} - { { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim } } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\coffin_rotate_pole:Nnnnnn} -% Rotating a single pole simply means shifting the co-ordinate of -% the pole and its direction. The rotation here is about the bottom-left -% corner of the coffin. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_rotate_pole:Nnnnnn #1#2#3#4#5#6 { - \coffin_rotate_vector:nnNN {#3} {#4} \l_coffin_x_dim \l_coffin_y_dim - \coffin_rotate_vector:nnNN {#5} {#6} - \l_coffin_x_prime_dim \l_coffin_y_prime_dim - \coffin_set_pole:Nnx #1 {#2} - { - { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim } - { \dim_use:N \l_coffin_x_prime_dim } - { \dim_use:N \l_coffin_y_prime_dim } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_rotate_vector:nnNN} -% A rotation function, which needs only an input vector (as dimensions) -% and an output space. The values \cs{l_coffin_cos_fp} and -% \cs{l_coffin_sin_fp} should previously have been set up correctly. -% Working this way means that the floating point work is kept to a -% minimum: for any given rotation the sin and cosine values do no -% change, after all. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_rotate_vector:nnNN #1#2#3#4 { - \fp_set_from_dim:Nn \l_coffin_x_fp {#1} - \fp_set_from_dim:Nn \l_coffin_y_fp {#2} - \fp_set_eq:NN \l_coffin_x_prime_fp \l_coffin_x_fp - \fp_set_eq:NN \l_coffin_tmp_fp \l_coffin_y_fp - \fp_mul:Nn \l_coffin_x_prime_fp { \l_coffin_cos_fp } - \fp_mul:Nn \l_coffin_tmp_fp { \l_coffin_sin_fp } - \fp_sub:Nn \l_coffin_x_prime_fp { \l_coffin_tmp_fp } - \fp_set_eq:NN \l_coffin_y_prime_fp \l_coffin_y_fp - \fp_set_eq:NN \l_coffin_tmp_fp \l_coffin_x_fp - \fp_mul:Nn \l_coffin_y_prime_fp { \l_coffin_cos_fp } - \fp_mul:Nn \l_coffin_tmp_fp { \l_coffin_sin_fp } - \fp_add:Nn \l_coffin_y_prime_fp { \l_coffin_tmp_fp } - \dim_set:Nn #3 { \fp_to_dim:N \l_coffin_x_prime_fp } - \dim_set:Nn #4 { \fp_to_dim:N \l_coffin_y_prime_fp } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_find_corner_maxima:N} -%\begin{macro}[aux]{\coffin_find_corner_maxima_aux:nn} -% The idea here is to find the extremities of the content of the -% coffin. This is done by looking for the smallest values for the bottom -% and left corners, and the largest values for the top and right -% corners. The values start at the maximum dimensions so that the -% case where all are positive or all are negative works out correctly. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_find_corner_maxima:N #1 { - \dim_set:Nn \l_coffin_top_corner_dim { -\c_max_dim } - \dim_set:Nn \l_coffin_right_corner_dim { -\c_max_dim } - \dim_set:Nn \l_coffin_bottom_corner_dim { \c_max_dim } - \dim_set:Nn \l_coffin_left_corner_dim { \c_max_dim } - \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop } - { \coffin_find_corner_maxima_aux:nn ##2 } -} -\cs_new_protected_nopar:Npn \coffin_find_corner_maxima_aux:nn #1#2 { - \dim_set_min:Nn \l_coffin_left_corner_dim {#1} - \dim_set_max:Nn \l_coffin_right_corner_dim {#1} - \dim_set_min:Nn \l_coffin_bottom_corner_dim {#2} - \dim_set_max:Nn \l_coffin_top_corner_dim {#2} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\coffin_find_bounding_shift:} -%\begin{macro}[aux]{\coffin_find_bounding_shift_aux:nn} -% The approach to finding the shift for the bounding box is similar to -% that for the corners. However, there is only one value needed here and -% a fixed input property list, so things are a bit clearer. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_find_bounding_shift: { - \dim_set:Nn \l_coffin_bounding_shift_dim { \c_max_dim } - \prop_map_inline:Nn \l_coffin_bounding_prop - { \coffin_find_bounding_shift_aux:nn ##2 } -} -\cs_new_protected_nopar:Npn \coffin_find_bounding_shift_aux:nn #1#2 { - \dim_set_min:Nn \l_coffin_bounding_shift_dim {#1} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\coffin_shift_corner:Nnnn} -%\begin{macro}{\coffin_shift_pole:Nnnnnn} -% Shifting the corners and poles of a coffin means subtracting the -% appropriate values from the \( x \)- and \( y \)-components. For -% the poles, this means that the direction vector is unchanged. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_shift_corner:Nnnn #1#2#3#4 { - \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _ prop } {#2} - { - { \dim_eval:n { #3 - \l_coffin_left_corner_dim } } - { \dim_eval:n { #4 - \l_coffin_bottom_corner_dim } } - } -} -\cs_new_protected_nopar:Npn \coffin_shift_pole:Nnnnnn #1#2#3#4#5#6 { - \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _ prop } {#2} - { - { \dim_eval:n { #3 - \l_coffin_left_corner_dim } } - { \dim_eval:n { #4 - \l_coffin_bottom_corner_dim } } - {#5} {#6} - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\subsection{Resizing coffins} -% -%\begin{macro}{\l_coffin_scale_x_fp} -%\begin{macro}{\l_coffin_scale_y_fp} -% Storage for the scaling factors in \( x \) and \( y \), respectively. -% \begin{macrocode} -\fp_new:N \l_coffin_scale_x_fp -\fp_new:N \l_coffin_scale_y_fp -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_coffin_scaled_total_height_dim} -%\begin{macro}{\l_coffin_scaled_width_dim} -% When scaling, the values given have to be turned into absolute values. -% \begin{macrocode} -\dim_new:N \l_coffin_scaled_total_height_dim -\dim_new:N \l_coffin_scaled_width_dim -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{ -% \coffin_resize:Nnn , -% \coffin_resize:cnn , -%} -% Resizing a coffin begins by setting up the user-friendly names for -% the dimensions of the coffin box. The new sizes are then turned into -% scale factor. This is the same operation as takes place for the -% underlying box, but that operation is grouped and so the same -% calculation is done here. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_resize:Nnn #1#2#3 { - \coffin_set_user_dimensions:N #1 - \fp_set_from_dim:Nn \l_coffin_scale_x_fp {#2} - \fp_set_from_dim:Nn \l_coffin_tmp_fp { \Width } - \fp_div:Nn \l_coffin_scale_x_fp { \l_coffin_tmp_fp } - \fp_set_from_dim:Nn \l_coffin_scale_y_fp {#3} - \fp_set_from_dim:Nn \l_coffin_tmp_fp { \TotalHeight } - \fp_div:Nn \l_coffin_scale_y_fp { \l_coffin_tmp_fp } - \hbox_set:Nn #1 { \resizebox * {#2} {#3} { \box_use:N #1 } } - \coffin_resize_common:Nnn #1 {#2} {#3} -} -\cs_generate_variant:Nn \coffin_resize:Nnn { c } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_resize_common:Nnn} -% The poles and corners of the coffin are scaled to the appropriate -% places before actually resizing the underlying box. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_resize_common:Nnn #1#2#3 { - \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop } - { \coffin_scale_corner:Nnnn #1 {##1} ##2 } - \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop } - { \coffin_scale_pole:Nnnnnn #1 {##1} ##2 } -% \end{macrocode} -% Negative \( x \)-scaling values will place the poles in the wrong -% location: this is corrected here. -% \begin{macrocode} - \fp_compare:NNNT \l_coffin_scale_x_fp < \c_zero_fp - { - \prop_map_inline:cn { l_coffin_corners_ \tex_number:D #1 _prop } - { \coffin_x_shift_corner:Nnnn #1 {##1} ##2 } - \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop } - { \coffin_x_shift_pole:Nnnnnn #1 {##1} ##2 } - } - \coffin_end_user_dimensions: -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{ -% \coffin_scale:Nnn , -% \coffin_scale:cnn , -%} -% For scaling, the opposite calculation is done to find the new -% dimensions for the coffin. Only the total height is needed, as this -% is the shift required for corners and poles. The scaling is done -% the \TeX\ way as this works properly with floating point values -% without needing to use the \texttt{fp} module. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_scale:Nnn #1#2#3 { - \coffin_set_user_dimensions:N #1 - \fp_set:Nn \l_coffin_scale_x_fp {#2} - \fp_set:Nn \l_coffin_scale_y_fp {#3} - \fp_compare:NNNTF \l_coffin_scale_y_fp > \c_zero_fp - { \l_coffin_scaled_total_height_dim #3 \TotalHeight } - { \l_coffin_scaled_total_height_dim -#3 \TotalHeight } - \fp_compare:NNNTF \l_coffin_scale_x_fp > \c_zero_fp - { \l_coffin_scaled_width_dim -#2 \Width } - { \l_coffin_scaled_width_dim #2 \Width } - \hbox_set:Nn #1 { \scalebox {#2} [#3] { \box_use:N #1 } } - \coffin_resize_common:Nnn #1 - { \l_coffin_scaled_width_dim } { \l_coffin_scaled_total_height_dim } -} -\cs_generate_variant:Nn \coffin_scale:Nnn { c } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_scale_vector:nnNN} -% This functions scales a vector from the origin using the pre-set scale -% factors in \( x \) and \( y \). This is a much less complex operation -% than rotation, and as a result the code is a lot clearer. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_scale_vector:nnNN #1#2#3#4 { - \fp_set_from_dim:Nn \l_coffin_tmp_fp {#1} - \fp_mul:Nn \l_coffin_tmp_fp { \l_coffin_scale_x_fp } - \dim_set:Nn #3 { \fp_to_dim:N \l_coffin_tmp_fp } - \fp_set_from_dim:Nn \l_coffin_tmp_fp {#2} - \fp_mul:Nn \l_coffin_tmp_fp { \l_coffin_scale_y_fp } - \dim_set:Nn #4 { \fp_to_dim:N \l_coffin_tmp_fp } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\coffin_scale_corner:Nnnn} -%\begin{macro}{\coffin_scale_pole:Nnnnnn} -% Scaling both corners and poles is a simple calculation using the -% preceding vector scaling. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_scale_corner:Nnnn #1#2#3#4 { - \coffin_scale_vector:nnNN {#3} {#4} \l_coffin_x_dim \l_coffin_y_dim - \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } {#2} - { { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim } } -} -\cs_new_protected_nopar:Npn \coffin_scale_pole:Nnnnnn #1#2#3#4#5#6 { - \coffin_scale_vector:nnNN {#3} {#4} \l_coffin_x_dim \l_coffin_y_dim - \coffin_set_pole:Nnx #1 {#2} - { - { \dim_use:N \l_coffin_x_dim } { \dim_use:N \l_coffin_y_dim } - {#5} {#6} - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\coffin_x_shift_corner:Nnnn} -%\begin{macro}{\coffin_x_shift_pole:Nnnnnn} -% These functions correct for the \( x \) displacement that takes -% place with a negative horizontal scaling. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_x_shift_corner:Nnnn #1#2#3#4 { - \prop_put:cnx { l_coffin_corners_ \tex_number:D #1 _prop } {#2} - { - { \the_tex:D \etex_dimexpr:D #3 + \box_wd:N #1 \scan_stop: } {#4} - } -} -\cs_new_protected_nopar:Npn \coffin_x_shift_pole:Nnnnnn #1#2#3#4#5#6 { - \prop_put:cnx { l_coffin_poles_ \tex_number:D #1 _prop } {#2} - { - { \the_tex:D \etex_dimexpr:D #3 + \box_wd:N #1 \scan_stop: } {#4} - {#5} {#6} - } -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\subsection{Coffin diagnostics} -% -%\begin{macro}{\l_coffin_display_coffin} -%\begin{macro}{\l_coffin_display_coord_coffin} -%\begin{macro}{\l_coffin_display_pole_coffin} -% Used for printing coffins with data structures attached. -% \begin{macrocode} -\coffin_new:N \l_coffin_display_coffin -\coffin_new:N \l_coffin_display_coord_coffin -\coffin_new:N \l_coffin_display_pole_coffin -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_coffin_display_handles_prop} -% This property list is used to print coffin handles at suitable -% positions. The offsets are expressed as multiples of the basic offset -% value, which therefore acts as a scale-factor. -% \begin{macrocode} -\prop_new:N \l_coffin_display_handles_prop -\prop_put:Nnn \l_coffin_display_handles_prop { tl } - { { b } { r } { -1 } { 1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { thc } - { { b } { hc } { 0 } { 1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { tr } - { { b } { l } { 1 } { 1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { vcl } - { { vc } { r } { -1 } { 0 } } -\prop_put:Nnn \l_coffin_display_handles_prop { vchc } - { { vc } { hc } { 0 } { 0 } } -\prop_put:Nnn \l_coffin_display_handles_prop { vcr } - { { vc } { l } { 1 } { 0 } } -\prop_put:Nnn \l_coffin_display_handles_prop { bl } - { { t } { r } { -1 } { -1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { bhc } - { { t } { hc } { 0 } { -1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { br } - { { t } { l } { 1 } { -1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { Tl } - { { t } { r } { -1 } { -1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { Thc } - { { t } { hc } { 0 } { -1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { Tr } - { { t } { l } { 1 } { -1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { Hl } - { { vc } { r } { -1 } { 1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { Hhc } - { { vc } { hc } { 0 } { 1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { Hr } - { { vc } { l } { 1 } { 1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { Bl } - { { b } { r } { -1 } { -1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { Bhc } - { { b } { hc } { 0 } { -1 } } -\prop_put:Nnn \l_coffin_display_handles_prop { Br } - { { b } { l } { 1 } { -1 } } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_coffin_display_offset_dim} -% The standard offset for the label from the handle position when -% displaying handles. -% \begin{macrocode} -\dim_new:N \l_coffin_display_offset_dim -\dim_set:Nn \l_coffin_display_offset_dim { 2 pt } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_coffin_display_x_dim} -%\begin{macro}{\l_coffin_display_y_dim} -% As the intersections of poles have to be calculated to find which -% ones to print, there is a need to avoid repetition. This is done -% by saving the intersection into two dedicated values. -% \begin{macrocode} -\dim_new:N \l_coffin_display_x_dim -\dim_new:N \l_coffin_display_y_dim -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\l_coffin_display_poles_prop} -% A property list for printing poles: various things need to be deleted -% from this to get a `nice' output. -% \begin{macrocode} -\prop_new:N \l_coffin_display_poles_prop -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_coffin_display_font_tl} -% Stores the settings used to print coffin data: this keeps things -% flexible. -% \begin{macrocode} -\tl_new:N \l_coffin_display_font_tl -\tl_set:Nn \l_coffin_display_font_tl { \sffamily \tiny } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_coffin_show_toks} -% For the package the \LaTeXe\ code can be used. -% \begin{macrocode} -\cs_new_eq:NN \l_coffin_show_toks \toks@ -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\l_coffin_handles_tmp_prop} -% Used for displaying coffins, as the handles need to be stored in this -% case, at least temporarily. -% \begin{macrocode} -\prop_new:N \l_coffin_handles_tmp_prop -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{ -% \coffin_mark_handle:Nnnn , -% \coffin_mark_handle:cnnn , -%} -%\begin{macro}[aux]{\coffin_mark_handle_aux:nnnnNnn} -% Marking a single handle is relatively easy. The standard attachment -% function is used, meaning that there are two calculations for the -% location. However, this is likely to be okay given the load expected. -% Contrast with the more optimised version for showing all handles which -% comes next. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_mark_handle:Nnnn #1#2#3#4 { - \hcoffin_set:Nn \l_coffin_display_pole_coffin - { - \color {#4} - \rule { 1 pt } { 1 pt } - \hbox:n { \tex_vrule:D width 1 pt height 1 pt \scan_stop: } % TEMP - } - \coffin_attach_mark:NnnNnnnn #1 {#2} {#3} - \l_coffin_display_pole_coffin { hc } { vc } { 0 pt } { 0 pt } - \hcoffin_set:Nn \l_coffin_display_coord_coffin - { - \color {#4} - \l_coffin_display_font_tl - ( \tl_to_str:n { #2 , #3 } ) - } - \prop_get:NnN \l_coffin_display_handles_prop - { #2 #3 } \l_coffin_tmp_tl - \quark_if_no_value:NTF \l_coffin_tmp_tl - { - \prop_get:NnN \l_coffin_display_handles_prop - { #3 #2 } \l_coffin_tmp_tl - \quark_if_no_value:NTF \l_coffin_tmp_tl - { - \coffin_attach_mark:NnnNnnnn #1 {#2} {#3} - \l_coffin_display_coord_coffin { l } { vc } - { 1 pt } { 0 pt } - } - { - \exp_last_unbraced:No \coffin_mark_handle_aux:nnnnNnn - \l_coffin_tmp_tl #1 {#2} {#3} - } - } - { - \exp_last_unbraced:No \coffin_mark_handle_aux:nnnnNnn - \l_coffin_tmp_tl #1 {#2} {#3} - } -} -\cs_new_protected_nopar:Npn - \coffin_mark_handle_aux:nnnnNnn #1#2#3#4#5#6#7 { - \coffin_attach_mark:NnnNnnnn #5 {#6} {#7} - \l_coffin_display_coord_coffin {#1} {#2} - { #3 \l_coffin_display_offset_dim } - { #4 \l_coffin_display_offset_dim } -} -\cs_generate_variant:Nn \coffin_mark_handle:Nnnn { c } -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{ -% \coffin_display_handles:Nn , -% \coffin_display_handles:cn , -%} -%\begin{macro}[aux]{\coffin_display_handles_aux:nnnnnn} -%\begin{macro}[aux]{\coffin_display_handles_aux:nnnn} -%\begin{macro}[aux]{\coffin_display_attach:Nnnnn} -% Printing the poles starts by removing any duplicates, for which the -% \texttt{H} poles is used as the definitive version for the baseline -% and bottom. Two loops are then used to find the combinations of -% handles for all of these poles. This is done such that poles are -% removed during the loops to avoid duplication. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_display_handles:Nn #1#2 { - \hcoffin_set:Nn \l_coffin_display_pole_coffin - { - \color {#2} - \rule { 1 pt } { 1 pt } - } - \prop_set_eq:Nc \l_coffin_display_poles_prop - { l_coffin_poles_ \tex_number:D #1 _prop } - \coffin_get_pole:NnN #1 { H } \l_coffin_pole_a_tl - \coffin_get_pole:NnN #1 { T } \l_coffin_pole_b_tl - \tl_if_eq:NNT \l_coffin_pole_a_tl \l_coffin_pole_b_tl - { \prop_del:Nn \l_coffin_display_poles_prop { T } } - \coffin_get_pole:NnN #1 { B } \l_coffin_pole_b_tl - \tl_if_eq:NNT \l_coffin_pole_a_tl \l_coffin_pole_b_tl - { \prop_del:Nn \l_coffin_display_poles_prop { B } } - \coffin_set_eq:NN \l_coffin_display_coffin #1 - \prop_clear:N \l_coffin_handles_tmp_prop - \prop_map_inline:Nn \l_coffin_display_poles_prop - { - \prop_del:Nn \l_coffin_display_poles_prop {##1} - \coffin_display_handles_aux:nnnnnn {##1} ##2 {#2} - } - \box_use:N \l_coffin_display_coffin -} -% \end{macrocode} -% For each pole there is a check for an intersection, which here does -% not give an error if none is found. The successful values are stored -% and used to align the pole coffin with the main coffin for output. -% The positions are recovered from the preset list if available. -% \begin{macrocode} -\cs_new_protected_nopar:Npn - \coffin_display_handles_aux:nnnnnn #1#2#3#4#5#6 { - \prop_map_inline:Nn \l_coffin_display_poles_prop - { - \bool_set_false:N \l_coffin_error_bool - \coffin_calculate_intersection:nnnnnnnn {#2} {#3} {#4} {#5} ##2 - \bool_if:NF \l_coffin_error_bool - { - \dim_set:Nn \l_coffin_display_x_dim { \l_coffin_x_dim } - \dim_set:Nn \l_coffin_display_y_dim { \l_coffin_y_dim } - \coffin_display_attach:Nnnnn - \l_coffin_display_pole_coffin { hc } { vc } - { 0 pt } { 0 pt } - \hcoffin_set:Nn \l_coffin_display_coord_coffin - { - \color {#6} - \l_coffin_display_font_tl - ( \tl_to_str:n { #1 , ##1 } ) - } - \prop_get:NnN \l_coffin_display_handles_prop - { #1 ##1 } \l_coffin_tmp_tl - \quark_if_no_value:NTF \l_coffin_tmp_tl - { - \prop_get:NnN \l_coffin_display_handles_prop - { ##1 #1 } \l_coffin_tmp_tl - \quark_if_no_value:NTF \l_coffin_tmp_tl - { - \coffin_display_attach:Nnnnn - \l_coffin_display_coord_coffin { l } { vc } - { 1 pt } { 0 pt } - } - { - \exp_last_unbraced:No - \coffin_display_handles_aux:nnnn - \l_coffin_tmp_tl - } - } - { - \exp_last_unbraced:No \coffin_display_handles_aux:nnnn - \l_coffin_tmp_tl - } - } - } -} -\cs_new_protected_nopar:Npn \coffin_display_handles_aux:nnnn #1#2#3#4 { - \coffin_display_attach:Nnnnn - \l_coffin_display_coord_coffin {#1} {#2} - { #3 \l_coffin_display_offset_dim } - { #4 \l_coffin_display_offset_dim } -} -\cs_generate_variant:Nn \coffin_display_handles:Nn { c } -% \end{macrocode} -% This is a dedicated version of \cs{coffin_attach:NnnNnnnn} with -% a hard-wired first coffin. As the intersection is already known -% and stored for the display coffin the code simply uses it directly, -% with no calculation. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_display_attach:Nnnnn #1#2#3#4#5 { - \coffin_calculate_intersection:Nnn #1 {#2} {#3} - \dim_set:Nn \l_coffin_x_prime_dim { \l_coffin_x_dim } - \dim_set:Nn \l_coffin_y_prime_dim { \l_coffin_y_dim } - \dim_set:Nn \l_coffin_offset_x_dim - { \l_coffin_display_x_dim - \l_coffin_x_prime_dim + #4 } - \dim_set:Nn \l_coffin_offset_y_dim - { \l_coffin_display_y_dim - \l_coffin_y_prime_dim + #5 } - \hbox_set:Nn \l_coffin_aligned_coffin - { - \box_use:N \l_coffin_display_coffin - \tex_kern:D -\box_wd:N \l_coffin_display_coffin - \tex_kern:D \l_coffin_offset_x_dim - \box_move_up:nn { \l_coffin_offset_y_dim } { \box_use:N #1 } - } - \box_set_ht:Nn \l_coffin_aligned_coffin - { \box_ht:N \l_coffin_display_coffin } - \box_set_dp:Nn \l_coffin_aligned_coffin - { \box_dp:N \l_coffin_display_coffin } - \box_set_wd:Nn \l_coffin_aligned_coffin - { \box_wd:N \l_coffin_display_coffin } - \box_set_eq:NN \l_coffin_display_coffin \l_coffin_aligned_coffin -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\coffin_show_structure:N} -%\begin{macro}{\coffin_show_structure:c} -% For showing the various internal structures attached to a coffin in -% a way that keeps things relatively readable. If there is no apparent -% structure then the code complains. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \coffin_show_structure:N #1 { - \toks_clear:N \l_coffin_show_toks - \cs_if_exist:cTF { l_coffin_poles_ \tex_number:D #1 _prop } - { - \iow_term:x - { - \iow_newline: - Size~of~coffin~\token_to_str:N #1 : \iow_newline: - > ~ ht~=~\dim_use:N \box_ht:N #1 \iow_newline: - > ~ dp~=~\dim_use:N \box_dp:N #1 \iow_newline: - > ~ wd~=~\dim_use:N \box_wd:N #1 \iow_newline: - } - \iow_term:x { Poles~of~coffin~\token_to_str:N #1 : } - \prop_map_inline:cn { l_coffin_poles_ \tex_number:D #1 _prop } - { - \toks_if_empty:NF \l_coffin_show_toks - { - \toks_put_right:Nx \l_coffin_show_toks - { \iow_newline: > ~ } - } - \toks_put_right:Nx \l_coffin_show_toks - { ~ \exp_not:n {##1} \c_space_tl => ~ \exp_not:n {##2} } - } - } - { - \iow_term:x { ---~No~poles~found~--- } - \toks_put_right:Nn \l_coffin_show_toks - { Is~this~really~a~coffin? } - } - \toks_show:N \l_coffin_show_toks -} -\cs_generate_variant:Nn \coffin_show_structure:N { c } -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\subsection{Messages} -% -% \begin{macrocode} -\msg_kernel_new:nnnn { coffin } { no-pole-intersection } - { No~intersection~between~coffin~poles. } - { - \l_msg_coding_error_text_tl - LaTeX~was~asked~to~find~the~intersection~between~two~poles,~ - but~they~do~not~have~a~unique~meeting~point:~ - the~value~(0~pt,~0~pt)~will~be~used. - } -\msg_kernel_new:nnnn { coffin } { unknown-coffin } - { Unknown~coffin~'#1'. } - { The~coffin~'#1'~was~never~defined. } -\msg_kernel_new:nnnn { coffin } { unknown-coffin-pole } - { Pole~'#1'~unknown~for~coffin~'#2'. } - { - \l_msg_coding_error_text_tl - LaTeX~was~asked~to~find~a~typesetting~pole~for~a~coffin,~ - but~either~the~coffin~does~not~exist~or~the~pole~name~is~wrong. - } -% \end{macrocode} -% -% \begin{macro}{\exp_two_last_unbraced:Noo} -% \begin{macrocode} -\cs_new:Npn \exp_last_two_unbraced:Noo #1 #2 #3{ - \exp_after:wN \exp_after:wN \exp_after:wN #1 \exp_after:wN #2 #3 -} -% \end{macrocode} -% \end{macro} -% -% \begin{macrocode} -%</package> -% \end{macrocode} -% -%\end{implementation} -% -%\PrintChanges -% -%\PrintIndex
\ No newline at end of file diff --git a/Master/texmf-dist/source/latex/xpackages/xcoffins/xcoffins.dtx b/Master/texmf-dist/source/latex/xpackages/xcoffins/xcoffins.dtx deleted file mode 100644 index d59da40913b..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xcoffins/xcoffins.dtx +++ /dev/null @@ -1,869 +0,0 @@ -% \iffalse -%% File xcoffins.dtx (C) Copyright 2010 LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%% -%% This file is part of the ``xcoffins bundle'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -%<*driver|package> -\RequirePackage{expl3} -\RequirePackage{graphicx,xcolor} -\GetIdInfo$Id: xcoffins.dtx 2097 2010-12-05 21:59:21Z mittelba $ - {Coffins} -%</driver|package> -%<*driver> -%\fi -\ProvidesFile{\filename.\filenameext} - [\filedate\space v\fileversion\space\filedescription] -%\iffalse -\documentclass{l3doc} -\usepackage{\jobname} % This file uses coffins! -\NewCoffin \ExampleCoffin -\NewCoffin \SmallCoffin -\NewCoffin \OutputCoffin -\NewCoffin \RedCoffin -\NewCoffin \BlueCoffin -\NewCoffin \GreenCoffin -\NewCoffin \YellowCoffin -\NewCoffin \OrangeCoffin -\begin{document} - \DocInput{\jobname.dtx} -\end{document} -%</driver> -%\fi -% -%\title{^^A -% The \LaTeX3 kernel: design-level coffins\thanks{^^A -% This file describes v\fileversion, last revised \filedate.^^A -% }^^A -%} -%\author{\Team}^^A -% -%\date{Released \filedate} -% -%\maketitle -% -%\begin{abstract} -% A \LaTeX3 `coffin' is a design-level method for typesetting -% boxed material. The structure of coffins contains not only the -% boxed material itself but also information about the size of the -% box and potential alignment positions. This structure makes it is -% possible to build complex layouts rapidly by assembling coffins. -% This module contains the design-level code to implement this scheme. -%\end{abstract} -% -%\tableofcontents -% -%\begin{documentation} -% -%\section{Introduction: the coffin concept} -% -% In \LaTeX3 terminology, a `coffin' is a box containing -% typeset material. Along with the box itself, the coffin structure -% includes information on the size and shape of the box, which makes -% it possible to align two or more coffins easily. This is achieved -% by providing a series of `poles' for each coffin. These -% are horizontal and vertical lines through the coffin at defined -% positions, for example the top or horizontal centre. The points -% where these poles intersect are called `handles'. Two -% coffins can then be aligned by describing the relationship between -% a handle on one coffin with a handle on the second. In words, an -% example might then read -%\begin{quote} -% Align the top-left handle of coffin A with the bottom-right -% handle of coffin B. -%\end{quote} -% -% The locations of coffin handles are much easier to understand -% visually. Figure~\ref{fgr:handles} shows the standard handle -% positions for a coffin typeset in horizontal mode (left) and in -% vertical mode (right). Notice that the later case results in a greater -% number of handles being available. As illustrated, each handle -% results from the intersection of two poles. For example, the centre -% of the coffin is marked `(hc,vc), \emph{i.e.}~it is the -% point of intersection of the horizontal centre pole with the -% vertical centre pole. New handles are generated automatically when -% poles are added to a coffin: handles are `dynamic' -% entities. -%\begin{figure} -% \hfil -% \begin{minipage}{0.4\textwidth} -% \SetHorizontalCoffin\ExampleCoffin -% {\color{black!10!white}\rule{1 in}{1 in}} -% \DisplayCoffinHandles\ExampleCoffin{blue} -% \end{minipage} -% \hfil -% \begin{minipage}{0.4\textwidth} -% \SetVerticalCoffin\ExampleCoffin{1 in} -% {\color{black!10!white}\rule{1 in}{1 in}} -% \DisplayCoffinHandles\ExampleCoffin{blue} -% \end{minipage} -% \hfil -% \caption{Standard coffin handles: left, horizontal coffin; right, -% vertical coffin} -% \label{fgr:handles} -%\end{figure} -% -%\section{Creating and setting coffins} -% -% Before any alignment can take place, coffins must be created and -% their contents must be created. All coffin operations are local -% to the current \TeX\ group with the exception of coffin creation. -% Coffins are also `colour safe': in contrast to the code-level -% \cs{box_\ldots} functions there is no need to add additional grouping -% to coffins when dealing with colour. -% -%\begin{function}{ \NewCoffin } -% \begin{syntax} -% \cs{NewCoffin} \meta{coffin} -% \end{syntax} -% Before a \meta{coffin} can be used, it must be allocated using -% \cs{NewCoffin}. The name of the \meta{coffin} should be a -% control sequence (starting with the escape character, usually -% "\"), for example -% \begin{verbatim} -% \NewCoffin\MyCoffin -% \end{verbatim} -% Coffins are allocated globally, and an error will be raised if the -% name of the \meta{coffin} is not globally-unique. -%\end{function} -% -%\begin{function}{\SetHorizontalCoffin} -% \begin{syntax} -% \cs{SetHorizontalCoffin} \meta{coffin} \Arg{material} -% \end{syntax} -% Typesets the \meta{material} in horizontal mode, storing the result -% in the \meta{coffin}. The standard poles for the \meta{coffin} are -% then set up based on the size of the typeset material. -%\end{function} -% -%\begin{function}{\SetVerticalCoffin} -% \begin{syntax} -% \cs{SetVerticalCoffin} \meta{coffin} \Arg{width} \Arg{material} -% \end{syntax} -% Typesets the \meta{material} in vertical mode constrained to the -% given \meta{width} and stores the result in the \meta{coffin}. The -% standard poles for the \meta{coffin} are then set up based on the -% size of the typeset material. -%\end{function} -% -%\section{Controlling coffin poles} -% -% A number of standard poles are automatically generated when the coffin -% is set or an alignment takes place. The standard poles for all coffins -% are: -%\begin{itemize}[font = \ttfamily] -% \item[l] a pole running along the left-hand edge of the bounding -% box of the coffin; -% \item[hc] a pole running vertically through the centre of the coffin -% half-way between the left- and right-hand edges of the bounding -% box (\emph{i.e}~the `horizontal centre'); -% \item[r] a pole running along the right-hand edge of the bounding -% box of the coffin; -% \item[b] a pole running along the bottom edge of the bounding -% box of the coffin; -% \item[vc] a pole running horizontally through the centre of the -% coffin half-way between the bottom and top edges of the bounding -% box (\emph{i.e}~the `vertical centre'); -% \item[t] a pole running along the top edge of the bounding -% box of the coffin; -% \item[H] a pole running along the baseline of the typeset material -% contained in the coffin. -%\end{itemize} -% In addition, coffins containing vertical-mode material also -% feature poles which reflect the richer nature of these systems: -%\begin{itemize} -% \item[B] a pole running along the baseline of the material at the -% bottom of the coffin. -% \item[T] a pole running along the baseline of the material at the top -% of the coffin. -%\end{itemize} -% -%\begin{function}{\SetHorizontalPole} -% \begin{syntax} -% \cs{SetHorizontalPole} \meta{coffin} \Arg{pole} \Arg{offset} -% \end{syntax} -% Sets the \meta{pole} to run horizontally through the \meta{coffin}. -% The \meta{pole} will be located at the \meta{offset} from the -% bottom edge of the bounding box of the \meta{coffin}. The -% \meta{offset} should be given as a dimension expression; this may -% include the terms \cs{TotalHeight}, \cs{Height}, \cs{Depth} and -% \cs{Width}, which will evaluate to the appropriate dimensions of -% the \meta{coffin}. For example, to create a pole running -% horizontally through the coffin at one third of the distance from -% the base of the coffin to the top, the appropriate instruction would -% be \begin{verbatim} -% \SetHorizontalPole \MyCoffin {height/3} {\TotalHeight/3} -% \end{verbatim} -% Note that poles which run \emph{horizontally} are described in terms -% of their \emph{vertical} location in the coffin. Also notice that -% the total height of the coffin is described by the sum of -% \cs{Height} and \cs{Depth}: these are both measured from the -% horizontal baseline of the material in the coffin. -%\end{function} -% -%\begin{function}{\SetVerticalPole} -% \begin{syntax} -% \cs{SetVerticalPole} \meta{coffin} \Arg{pole} \Arg{offset} -% \end{syntax} -% Sets the \meta{pole} to run vertically through the \meta{coffin}. -% The \meta{pole} will be located at the \meta{offset} from the -% left-hand edge of the bounding box of the \meta{coffin}. The -% \meta{offset} should be given as a dimension expression; this may -% include the terms \cs{TotalHeight}, \cs{Height}, \cs{Depth} and -% \cs{Width}, which will evaluate to the appropriate dimensions of -% the \meta{coffin}. For example, to create a pole running vertically -% through the coffin at one third of the distance from the left-hand -% edge, the appropriate instruction would be -% \begin{verbatim} -% \SetVerticalPole \MyCoffin {width/3} {\Width/3} -% \end{verbatim} -% Note that poles which run \emph{vertically} are described in terms -% of their \emph{horizontal} location in the coffin. -%\end{function} -% -%\begin{function}{\TotalHeight} -% \begin{syntax} -% \cs{TotalHeight} -% \end{syntax} -% Within the \meta{offset} argument of \cs{SetHorizontalPole} and -% \cs{SetVerticalPole}, \cs{TotalHeight} will give the distance from -% the base to the top of the bounding box of the relevant coffin. -%\end{function} -% -%\begin{function}{\Height} -% \begin{syntax} -% \cs{Height} -% \end{syntax} -% Within the \meta{offset} argument of \cs{SetHorizontalPole} and -% \cs{SetVerticalPole}, \cs{Height} will give the distance from the -% baseline to the top of the bounding box of the relevant coffin. -%\end{function} -% -%\begin{function}{\Depth} -% \begin{syntax} -% \cs{Depth} -% \end{syntax} -% Within the \meta{offset} argument of \cs{SetHorizontalPole} and -% \cs{SetVerticalPole}, \cs{Depth} will give the distance from the -% baseline to the bottom of the bounding box of the relevant coffin. -%\end{function} -% -%\begin{function}{\Width} -% \begin{syntax} -% \cs{Width} -% \end{syntax} -% Within the \meta{offset} argument of \cs{SetHorizontalPole} and -% \cs{SetVerticalPole}, \cs{Width} will give the distance from the -% right edge to the left edge of the bounding box of the relevant -% coffin. -%\end{function} -% -%\section{Rotating coffins} -% -%\begin{function}{\RotateCoffin} -% \begin{syntax} -% \cs{RotateCoffin} \meta{coffin} \Arg{angle} -% \end{syntax} -% Rotates the \meta{coffin} by the given \meta{angle} (given in -% degrees counter-clockwise). This process will rotate both the -% coffin content and poles. Multiple rotations will not result in -% the bounding box of the coffin growing unnecessarily. -% -% The effect of rotation on a coffin is illustrated in -% Figure~\ref{fgr:rotation}. As is shown, the coffin handles will -% remain correctly positioned relative to the content of the coffin. -% The `top' of a rotated coffin may of course no longer be the -% edge closest to the top of the physical page. -% \begin{figure} -% \hfil -% \SetHorizontalCoffin\ExampleCoffin -% {^^A -% \color{black!10!white}\rule{0.5 in}{1 in}^^A -% \color{black!20!white}\rule{0.5 in}{1 in}^^A -% } -% \begin{minipage}{0.4\textwidth} -% \DisplayCoffinHandles\ExampleCoffin{blue} -% \end{minipage} -% \hfil -% \begin{minipage}{0.4\textwidth} -% \RotateCoffin\ExampleCoffin{45} -% \DisplayCoffinHandles\ExampleCoffin{blue} -% \end{minipage} -% \hfil -% \caption{Coffin rotation: left, unrotated; right, rotated by -% \( 45 \)\textdegree.} -% \label{fgr:rotation} -% \end{figure} -%\end{function} -% -%\section{Resizing coffins} -% -%\begin{function}{ \ResizeCoffin } -% \begin{syntax} -% \cs{RotateCoffin} \meta{coffin} \Arg{width} \Arg{total-height} -% \end{syntax} -% Resized the \meta{coffin} to \meta{width} and \meta{total-height}, -% both of which should be given as dimension expressions. These may -% include the terms \cs{TotalHeight}, \cs{Height}, \cs{Depth} and -% \cs{Width}, which will evaluate to the appropriate dimensions of -% the \meta{coffin}. -%\end{function} -% -%\begin{function}{\ScaleCoffin} -% \begin{syntax} -% \cs{ScaleCoffin} \meta{coffin} \Arg{x-scale} \Arg{y-scale} -% \end{syntax} -% Scales the \meta{coffin} by a factors \meta{x-scale} and -% \meta{y-scale} in the horizontal and vertical directions, -% respectively. The two scale factors should be given as real numbers. -%\end{function} -% -% \cs{ResizeCoffin} and \cs{ScaleCoffin} can be used interchangeably: -% whether scale factors or absolute values are the best form for the -% resizing will depend upon the context (Figure~\ref{fgr:resizing}). -%\begin{figure} -% \hfil -% \SetHorizontalCoffin\ExampleCoffin -% {^^A -% \color{black!10!white}\rule{0.5 in}{1 in}^^A -% \color{black!20!white}\rule{0.5 in}{1 in}^^A -% } -% \begin{minipage}{0.4\textwidth} -% \ResizeCoffin \ExampleCoffin {4 cm} {3 cm} -% \DisplayCoffinHandles \ExampleCoffin {blue} -% \end{minipage} -% \hfil -% \begin{minipage}{0.4\textwidth} -% \ScaleCoffin \ExampleCoffin {2.0} {0.5} -% \DisplayCoffinHandles \ExampleCoffin {blue} -% \end{minipage} -% \hfil -% \caption{Coffin resizing: left, resized to exactly \( 4 \)\,cm by -% \( 6 \)\,cm; right, scaled a factors of \( 2 \) and \( 0.5 \) in -% \( x \) and \( y \), respectively (example coffin as in -% Figure~\ref{fgr:rotation}).} -% \label{fgr:resizing} -%\end{figure} -% -%\section{Joining coffins} -% -% The key operation for coffins is joining coffins to each other. This -% is always carried out such that the first coffin is the -% `parent', and is updated by the alignment. The second -% `child' coffin is not altered by the alignment process. -% -%\begin{function}{\JoinCoffins} -% \begin{syntax} -% \cs{JoinCoffins} * -% ~~\meta{coffin1} [ \meta{coffin1-pole1} , \meta{coffin1-pole2} ] -% ~~\meta{coffin2} [ \meta{coffin2-pole1} , \meta{coffin2-pole2} ] -% ~~( \meta{x-offset} , \meta{y-offset} ) -% \end{syntax} -% Joining of two coffins is carried out by the \cs{JoinCoffins} -% function, which takes two mandatory arguments: the `parent' -% \meta{coffin1} and the `child' \meta{coffin2}. All of the -% other arguments shown are optional. -% -% The standard \cs{JoinCoffins} functions joins \meta{coffin2} to -% \meta{coffin1} such that the bounding box of \meta{coffin1} after the -% process will expand. The new bounding box will be the smallest -% rectangle covering the bounding boxes of the two input coffins. -% When the starred variant of \cs{JoinCoffins} is used, the bounding -% box of \meta{coffin1} is not altered, \emph{i.e.}~\meta{coffin2} may -% protrude outside of the bounding box of the updated \meta{coffin1}. -% The difference between the two forms of alignment is best illustrated -% using a visual example. In Figure~\ref{fgr:alignment}, the two -% processes are contrasted. In both cases, the small red coffin has been -% aligned with the large grey coffin. In the left-hand illustration, -% the \cs{JoinCoffins} function was used, resulting in an expanded -% bounding box. In contrast, on the right \cs{AttachCoffin} was used, -% meaning that the bounding box does not include the area of the -% smaller coffin. -% \begin{figure} -% \fboxsep 0 pt\relax -% \SetHorizontalCoffin\ExampleCoffin -% {\color{black!20!white}\rule{1 in}{1 in}} -% \SetHorizontalCoffin \SmallCoffin -% {\color{red!20!white}\rule{0.1 in}{0.1 in}} -% \hfil -% \begin{minipage}{0.4\textwidth} -% \centering -% \JoinCoffins\ExampleCoffin[vc,r]\SmallCoffin[vc,l] -% \fbox{\TypesetCoffin\ExampleCoffin} -% \end{minipage} -% \hfil -% \begin{minipage}{0.4\textwidth} -% \centering -% \JoinCoffins*\ExampleCoffin[vc,r]\SmallCoffin[vc,l] -% \fbox{\TypesetCoffin\ExampleCoffin}% -% \end{minipage} -% \hfil -% \caption{Contrast between \cs{JoinCoffins} (left) and -% \cs{JoinCoffins*} (right); the bounding box of the coffin is show -% in black.} -% \label{fgr:alignment} -% \end{figure} -% -% The alignment is carried out by first calculating \meta{handle1}, the -% point of intersection of \meta{coffin1-pole1} and -% \meta{coffin1-pole2}, and \meta{handle2}, the point of intersection -% of \meta{coffin2-pole1} and \meta{coffin2-pole2}. If the two -% \meta{poles} are not specified, \cs{JoinCoffins} will use the -% default value "(H,l)", \emph{i.e.}~the reference point used by \TeX\ -% for the underlying box. Once the two \meta{handles} have been -% located, \meta{coffin2} is then attached to \meta{coffin1} such that -% the relationship between \meta{handle1} and \meta{handle2} is -% described by the \meta{x-offset} and \meta{y-offset}. This -% \meta{offset} is an optional argument, and if it is not given then -% "(0 pt, 0 pt)" is used. -%\end{function} -% -% Notice that when \cs{JoinCoffins} is used the new bounding box is -% the smallest rectangle containing the bounding boxes of the two input -% coffins. As a result, it will include additional white space unless -% one coffin entirely overlaps the other (Figure~\ref{fgr:bounding}, -% left). Rotation of coffins will take account of the extent of the -% material after rotation when re-calculating the bounding box. This -% means that no \emph{unnecessary} white space will be added on -% rotation (Figure~\ref{fgr:bounding}, right). -%\begin{figure} -% \fboxsep 0 pt\relax -% \SetHorizontalCoffin\ExampleCoffin -% {\color{black!20!white}\rule{1 in}{1 in}} -% \SetHorizontalCoffin\SmallCoffin -% {\color{red!20!white}\rule{0.1 in}{0.1 in}} -% \JoinCoffins\ExampleCoffin[vc,r]\SmallCoffin[vc,l] -% \hfil -% \begin{minipage}{0.4\textwidth} -% \centering -% \fbox{\TypesetCoffin\ExampleCoffin} -% \end{minipage} -% \hfil -% \begin{minipage}{0.4\textwidth} -% \centering -% \RotateCoffin\ExampleCoffin{135} -% \fbox{\TypesetCoffin\ExampleCoffin} -% \end{minipage} -% \hfil -% \caption{The effect of rotation of a joined coffin: the black line -% shows the coffin bounding box.} -% \label{fgr:bounding} -%\end{figure} -% -% As part of the joining procedure, the poles of the two input coffins -% are preserved within the structure of the updated coffin. In this way -% it is possible to carry out complex alignment procedures. The poles of -% a coffin after alignment may therefore be divided into three groups: -%\begin{enumerate} -% \item The `native' poles of the updated coffin, such as -% \texttt{l}, \texttt{r}, \texttt{hc}, \emph{etc}. -% \item Poles derived from \meta{coffin1}, such as -% \texttt{\meta{coffin1}-l}, \texttt{\meta{coffin1}-r}, -% \texttt{\meta{coffin1}-hc}, \emph{etc.} -% \item Poles derived from \meta{coffin2}, such as -% \texttt{\meta{coffin2}-l}, \texttt{\meta{coffin2}-r}, -% \texttt{\meta{coffin2}-hc}, \emph{etc.} -%\end{enumerate} -% -% Applying this ability allows a series of joining operations to -% take place, as illustrated in Figure~\ref{fgr:nested}. In this -% example, the scheme used for alignment was as follows: -%\begin{verbatim} -% \SetHorizontalCoffin\OutputCoffin{} -% \SetHorizontalCoffin\RedCoffin -% {\color{red!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[vc,hc]\RedCoffin[vc,hc] -% \SetHorizontalCoffin\BlueCoffin -% {\color{blue!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[\RedCoffin-vc,\RedCoffin-hc] -% \BlueCoffin[b,l] -% \SetHorizontalCoffin\GreenCoffin -% {\color{green!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[\BlueCoffin-vc,\BlueCoffin-hc] -% \GreenCoffin[b,l] -% \SetHorizontalCoffin\YellowCoffin -% {\color{yellow!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[\GreenCoffin-vc,\GreenCoffin-hc] -% \YellowCoffin[b,l] -% \SetHorizontalCoffin \OrangeCoffin -% {\color{orange!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[\BlueCoffin-t,\BlueCoffin-l] -% \OrangeCoffin[b,r] -% \TypesetCoffin\OutputCoffin -%\end{verbatim} -% This process begins by setting up \cs{OutputCoffin} to hold the joined -% output. Each join then takes place placing the new addition relative -% to the previous one. As each coffin joined has a unique name it is -% possible to align relative to each one of the component parts of the -% assembly. This is illustrated by the addition of the final -% \cs{OrangeCoffin} based on the earlier placement of the -% \cs{BlueCoffin}. -%\begin{figure} -% \centering -% \SetHorizontalCoffin\OutputCoffin{} -% \SetHorizontalCoffin\RedCoffin -% {\color{red!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[vc,hc]\RedCoffin[vc,hc] -% \SetHorizontalCoffin\BlueCoffin -% {\color{blue!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[\RedCoffin-vc,\RedCoffin-hc] -% \BlueCoffin[b,l] -% \SetHorizontalCoffin\GreenCoffin -% {\color{green!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[\BlueCoffin-vc,\BlueCoffin-hc] -% \GreenCoffin[b,l] -% \SetHorizontalCoffin\YellowCoffin -% {\color{yellow!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[\GreenCoffin-vc,\GreenCoffin-hc] -% \YellowCoffin[b,l] -% \SetHorizontalCoffin \OrangeCoffin -% {\color{orange!20!white}\rule{0.2 in}{0.2 in}} -% \JoinCoffins\OutputCoffin[\BlueCoffin-t,\BlueCoffin-l] -% \OrangeCoffin[b,r] -% \TypesetCoffin\OutputCoffin -% \caption{Aligning coffins using poles from previous operations.} -% \label{fgr:nested} -%\end{figure} -% -%\section{Typesetting coffins} -% -%\begin{function}{ \TypesetCoffin } -% \begin{syntax} -% \cs{TypesetCoffin} -% ~~\meta{coffin} [ \meta{pole1} , \meta{pole2} ] -% ~~( \meta{x-offset} , \meta{y-offset} ) -% \end{syntax} -% Typesetting is carried out by first calculating \meta{handle}, the -% point of intersection of \meta{pole1} and \meta{pole2}. This is an -% optional argument, and if not given then "(H, l)", the \TeX\ -% reference point of the underlying box, is used. The coffin -% is then typeset such that the relationship between the current -% reference point in the document and the \meta{handle} is described -% by the \meta{x-offset} and \meta{y-offset}. This \meta{offset} is -% optional, and if not given "(0 pt, 0 pt)" is used. Typesetting a -% coffin is therefore analogous to carrying out an alignment where the -% `parent' coffin is the current insertion point. -%\end{function} -% -%\section{Diagnostic functions} -% -% Diagnostic data for following the coffin-building process is -% available both graphically and at the terminal. This reflects the -% fact that coffins are visual constructs. -% -%\begin{function}{ \DisplayCoffinHandles } -% \begin{syntax} -% \cs{DisplayCoffinHandles} \meta{coffin} \Arg{colour} -% \end{syntax} -% This function first calculates the intersections between all of -% the \meta{poles} of the \meta{coffin} to give a set of -% \meta{handles}. It then prints the \meta{coffin} at the current -% location in the source, with the position of the \meta{handles} -% marked on the coffin. The \meta{handles} will be labelled as part -% of this process: the locations of the \meta{handles} and the labels -% are both printed in the \meta{colour} specified. -%\end{function} -% -%\begin{function}{ \MarkCoffinHandle } -% \begin{syntax} -% \cs{MarkCoffinHandle} \meta{coffin} -% ~~[ \meta{pole1} , \meta{pole2} ] \Arg{colour} -% \end{syntax} -% This function first calculates the \meta{handle} for the -% \meta{coffin} as defined by the intersection of \meta{pole1} and -% \meta{pole2}. It then marks the position of the \meta{handle} -% on the \meta{coffin}. The \meta{handle} will be labelled as part of -% this process: the location of the \meta{handle} and the label are -% both printed in the \meta{colour} specified. If no \meta{poles} are -% give, the default "(H,l)" is used. -%\end{function} -% -%\begin{function}{ \ShowCoffinStructure } -% \begin{syntax} -% \cs{ShowCoffinStructure} \meta{coffin} -% \end{syntax} -% This function shows the structural information about the -% \meta{coffin} in the terminal. The width, height and depth of the -% typeset material are given, along with the location of all of the -% poles of the coffin. For example, for the rotated coffin in -% Figure~\ref{fgr:rotation}, the output of \cs{ShowCoffinStructure} -% is: -% \begin{verbatim} -% Size of coffin \ExampleCoffin: -% > ht = 102.2052pt -% > dp = 0.0pt -% > wd = 102.2052pt -% -% Poles of coffin \ExampleCoffin: -% > b => {51.1026pt}{0.0pt}{707.10678pt}{707.10678pt} -% > t => {0.0pt}{51.1026pt}{707.10678pt}{707.10678pt} -% > vc => {25.5513pt}{25.5513pt}{707.10678pt}{707.10678pt} -% > r => {102.2052pt}{51.1026pt}{-707.10678pt}{707.10678pt} -% > hc => {76.6539pt}{25.5513pt}{-707.10678pt}{707.10678pt} -% > T => {51.1026pt}{0.0pt}{707.10678pt}{707.10678pt} -% > H => {51.1026pt}{0.0pt}{707.10678pt}{707.10678pt} -% > B => {51.1026pt}{0.0pt}{707.10678pt}{707.10678pt} -% > l => {51.1026pt}{0.0pt}{-707.10678pt}{707.10678pt}. -% \coffin_show_structure:N ...N \l_coffin_show_toks -% \end{verbatim} -% Notice that the poles of a coffin are defined by four values: -% the \( x \) and \( y \) co-ordinates of a point that the pole -% passes through and the \( x \)- and \( y \)-components of a -% vector denoting the direction of the pole. It is the ratio between -% the later, rather than the absolute values, which determines the -% direction of the pole. -%\end{function} -% -%\end{documentation} -% -%\begin{implementation} -% -%\section{Implementation} -% -% \begin{macrocode} -%<*package> -% \end{macrocode} -% -% \begin{macrocode} -\ProvidesExplPackage - {\filename}{\filedate}{\fileversion}{\filedescription} -\RequirePackage{l3coffins,xparse} -% \end{macrocode} -% -% -%\begin{macro}{ -% \l_coffin_A_hpole_tl , -% \l_coffin_A_vpole_tl , -% \l_coffin_B_hpole_tl , -% \l_coffin_B_vpole_tl , -% \l_coffin_bound_box_grow_bool , -% \l_coffin_hoffset_dim , -% \l_coffin_voffset_dim , -%} -% Key--value definitions for the alignment system. With the exception -% of \texttt{grow-bounding-box}, all of these have to be given with a -% value. -% \begin{macrocode} -\keys_define:nn { coffin } { - coffin1-hpole .tl_set:N = \l_coffin_A_hpole_tl , - coffin1-hpole .value_required: , - coffin1-vpole .tl_set:N = \l_coffin_A_vpole_tl , - coffin1-vpole .value_required: , - coffin2-hpole .tl_set:N = \l_coffin_B_hpole_tl , - coffin2-hpole .value_required: , - coffin2-vpole .tl_set:N = \l_coffin_B_vpole_tl , - coffin2-vpole .value_required: , - grow-bounding-box .bool_set:N = \l_coffin_bound_box_grow_bool , - grow-bounding-box .default:n = true , - hoffset .dim_set:N = \l_coffin_hoffset_dim , - hoffset .value_required: , - voffset .dim_set:N = \l_coffin_voffset_dim , - voffset .value_required: , -} -\keys_set:nn { coffin } { - coffin1-hpole = H , - coffin1-vpole = l , - coffin2-hpole = H , - coffin2-vpole = l , - grow-bounding-box = true , - hoffset = 0 pt , - voffset = 0 pt , -} -% \end{macrocode} -%\end{macro} -% -% A lot of this is more-or-less just passing data straight through. -% -%\begin{macro}{\NewCoffin} -% This is a very easy conversion. -% \begin{macrocode} -\NewDocumentCommand \NewCoffin { m } { - \coffin_new:N #1 -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\SetHorizontalCoffin} -%\begin{macro}{\SetVerticalCoffin} -% These are again straight-forward translations. -% \begin{macrocode} -\NewDocumentCommand \SetHorizontalCoffin { m +m } { - \hcoffin_set:Nn #1 {#2} -} -\NewDocumentCommand \SetVerticalCoffin { m m +m } { - \vcoffin_set:Nnn #1 {#2} {#3} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\SetHorizontalPole} -%\begin{macro}{\SetVerticalPole} -% Again straight-forward -% \begin{macrocode} -\NewDocumentCommand \SetHorizontalPole { m m m } { - \coffin_set_horizontal_pole:Nnn #1 {#2} {#3} -} -\NewDocumentCommand \SetVerticalPole { m m m } { - \coffin_set_vertical_pole:Nnn #1 {#2} {#3} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\JoinCoffins} -% The \cs{JoinCoffins} function needs to do a bit of work on the input -% syntax, as there are a number of optional arguments to worry about. -% The idea here is that \cs{JoinCoffins} can be used to either expand -% the bounding box of \meta{coffin1} or add \meta{coffin2} without any -% expansion of the bounding box. There are also the two handle positions -% and the offset to sort out. -% \begin{macrocode} -\NewDocumentCommand \JoinCoffins - { - o - s - m - > { \SplitArgument { 1 } { , } } O { H , l } - m - > { \SplitArgument { 1 } { , } } O { H , l } - > { \SplitArgument { 1 } { , } } D ( ) { 0 pt , 0 pt } - } - { - \IfNoValueTF {#1} - { - \IfBooleanTF #2 - { \coffin_attach:NnnNnnnn #3 #4 #5 #6 #7 } - { \coffin_join:NnnNnnnn #3 #4 #5 #6 #7 } - } - { - \group_begin: - \keys_set:nn { coffin } {#1} - \tl_set:Nx \l_coffin_tmp_tl - { - \group_end: - \bool_if:NTF \l_coffin_bound_box_grow_bool - { \coffin_join:NnnNnnnn } - { \coffin_attach:NnnNnnnn } - \exp_not:N #3 - { \exp_not:o { \l_coffin_A_hpole_tl } } - { \exp_not:o { \l_coffin_A_vpole_tl } } - \exp_not:N #5 - { \exp_not:o { \l_coffin_B_hpole_tl } } - { \exp_not:o { \l_coffin_B_vpole_tl } } - { \dim_use:N \l_coffin_hoffset_dim } - { \dim_use:N \l_coffin_voffset_dim } - } - \l_coffin_tmp_tl - } - } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\TypesetCoffin} -% For typesetting coffins there are two optional arguments, both of -% which need to be split. This is a simpler case of the code needed for -% \cs{JoinCoffins}. -% \begin{macrocode} -\NewDocumentCommand \TypesetCoffin - { - m - > { \SplitArgument { 1 } { , } } O { H , l } - > { \SplitArgument { 1 } { , } } D ( ) { 0 pt , 0 pt } - } - { \coffin_typeset:Nnnnn #1 #2 #3 } -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\RotateCoffin} -%\begin{macro}{\ResizeCoffin} -%\begin{macro}{\ScaleCoffin} -% Mores straight-forward copies. -% \begin{macrocode} -\NewDocumentCommand \RotateCoffin { m m } { - \coffin_rotate:Nn #1 {#2} -} -\NewDocumentCommand \ResizeCoffin { m m m } { - \coffin_resize:Nnn #1 {#2} {#3} -} -\NewDocumentCommand \ScaleCoffin { m m m } { - \coffin_scale:Nnn #1 {#2} {#3} -} -% \end{macrocode} -%\end{macro} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\DisplayCoffinHandles} -% Displaying all of the handles is a bit easier, as there is no need -% to worry about the handle. -% \begin{macrocode} -\NewDocumentCommand \DisplayCoffinHandles { m m } { - \cs_if_exist:cTF { l_coffin_poles_ \tex_number:D #1 _prop } - { \coffin_display_handles:Nn #1 {#2} } - { \msg_kernel_error:nx { unknown-coffin } { \token_to_str:N #1 } } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\MarkCoffinHandle} -% Marking a handle requires a bit of work with the input, so that -% the design-level interface is `nice'. -% \begin{macrocode} -\NewDocumentCommand \MarkCoffinHandle - { m > { \SplitArgument { 1 } { , } } O { H , l } m } - { - \cs_if_exist:cTF { l_coffin_poles_ \tex_number:D #1 _prop } - { \coffin_mark_handle:Nnnn #1 #2 {#3} } - { \msg_kernel_error:nx { unknown-coffin } { \token_to_str:N #1 } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\ShowCoffinStructure} -% Back again to easy-to-implement functions. -% \begin{macrocode} -\NewDocumentCommand \ShowCoffinStructure { m } { - \coffin_show_structure:N #1 -} -% \end{macrocode} -%\end{macro} -% -% \begin{macrocode} -%</package> -% \end{macrocode} -% -%\end{implementation} -% -%\PrintChanges -% -%\PrintIndex
\ No newline at end of file diff --git a/Master/texmf-dist/source/latex/xpackages/xcoffins/xcoffins.ins b/Master/texmf-dist/source/latex/xpackages/xcoffins/xcoffins.ins deleted file mode 100644 index 6f525a3e2f0..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xcoffins/xcoffins.ins +++ /dev/null @@ -1,30 +0,0 @@ - -\input docstrip -\keepsilent -\askforoverwritefalse - -\preamble - -(C) Copyright The LaTeX3 Project and any individual authors -listed elsewhere in this file. - -This is a generated file. - -This file was generated from file(s) of the xcoffins bundle. ------------------------------------------------------------ - -This file may only be distributed together with a copy of this bundle. -You may however distribute the bundle without such generated files. - -====================================================================== - -\endpreamble - - -\generate{% - \file{l3coffins.sty}{\from{l3coffins.dtx}{package}} - \file{xcoffins.sty}{\from{xcoffins.dtx}{package}} -} - -\endbatchfile - diff --git a/Master/texmf-dist/source/latex/xpackages/xhead/xhead.dtx b/Master/texmf-dist/source/latex/xpackages/xhead/xhead.dtx deleted file mode 100644 index 11f23376a6e..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xhead/xhead.dtx +++ /dev/null @@ -1,986 +0,0 @@ -% \iffalse -%% File xhead.dtx (C) Copyright 2010 Frank Mittelbach, LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%% -%% This file is part of the ``xhead bundle'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -%<*driver|package> -\RequirePackage{expl3} -\GetIdInfo$Id: xhead.dtx 1914 2010-05-21 16:18:46Z schoepf $ - {Templates heading commands} -%</driver|package> -%<*driver> -%\fi -\ProvidesFile{\filename.\filenameext} - [\filedate\space v\fileversion\space\filedescription] -%\iffalse -\documentclass{l3doc} - - -% next three definitions are big hacks to run the file -% without the above packages -% -\makeatother - -\newcommand\key[1]{\textbf{#1}} - - \begin{document} - \DocInput{xhead.dtx} - \end{document} -%</driver> -% \fi -% -% ^^A\CheckSum{343} -% -% -% \title{The \textsf{xhead} package\thanks{This file -% has version number \fileversion, last -% revised \filedate.}} -% \author{FMi} -% \date{\filedate} -% \maketitle -% -% \tableofcontents -% -% \bigskip -% -% \begin{abstract} -% This module contains basic templates generating typical headings for -% various levels. This is very much work in progress and none of its content -% should be considered stable. Concepts and implementation are still under -% development. -% \end{abstract} -% -% -% \newcommand\NOVALUE{\texttt{\string\NoValue}} -% \newcommand\EMPTY{\textit{<empty>}} -% \newcommand\STRING{\textit{<string>}} -% \newcommand\TRUE{\texttt{true}} -% \newcommand\FALSE{\texttt{false}} -% \newcommand\KEYVALS{\textit{<key/value list>}} -% \newcommand\HASH[1]{\texttt{\##1}} -% -% \makeatletter -% \renewenvironment{TemplateInterfaceDescription}[1] -% {\subsection{The~object~type~`#1'}% -% \begingroup -% \@beginparpenalty\@M -% \description -% \def\TemplateArgument##1##2{\item[Arg:~##1 (##2)]}^^A -% \def\TemplateSemantics{\enddescription\endgroup -% \subsubsection*{Semantics:}}^^A -% } -% {\par\bigskip} -% \makeatother -% -% \section{Introduction} -% -% -% \section{Interfaces} -% -% \begin{TemplateInterfaceDescription}{heading} -% -% -% \TemplateArgument{1}{boolean} -% If \TRUE{} generate an unnumbered heading, otherwise a number is -% generated up to a certain heading level. If \TRUE{} TOC entries and -% running headers are suppressed unless explicitly forced by other -% arguments below. -% -% \TemplateArgument{2} -% {\STRING/\NOVALUE/\EMPTY} -% Specifies an alternate heading text for the TOC if one is produced. If -% \NOVALUE{} or \EMPTY{} the TOC receives the the main title text. -% -% \TemplateArgument{3} -% {boolean} -% If \TRUE{} a TOC entry is forced (i.e., generated even if normally supressed). -% -% \TemplateArgument{4} -% {\STRING/\NOVALUE/\EMPTY} -% Specifies an alternate heading text for the running header if one is -% produced. If \NOVALUE{} or \EMPTY{} the running header receives the the -% main title text. -% -% \TemplateArgument{5} -% {boolean} -% If \TRUE{} a running header is forced (i.e., generated even if normally -% supressed). -% -% \TemplateArgument{6} -% {\STRING} -% The title of the heading in the document. Also used for the TOC entry and -% running header (if produced) unless overwritten by other arguments. -% -% \TemplateArgument{7} -% {\KEYVALS} -% Extension argument to receive less use key value pairs to manipulate the -% heading. Exact syntax and semantics still need to be defined. -% -% \TemplateSemantics -% This template type defines the basic interface for headings both display -% headings as well as run-in headings. -% -% A TOC entry is generated if \HASH{1} is \FALSE{} or \HASH{3} being -% \TRUE{}. The heading title for the TOC entry is \HASH{6} unless -% overwritten by a non-empty HASH{2}. Whether or not this TOC entry -% actually appears in the TOC depends on settings for the TOC -% generation. (However, if not generated if will obviously not appear.) -% -% A running header is generated if \HASH{1} is \FALSE{} or \HASH{5} or -% \TRUE{}. The heading title for the determined as follows: if \HASH{4} is -% non-empty it will be used, otherwise if \HASH{2} is non-empty it will be -% used, otherwise HASH{6} will be used. -% -% \HASH{7} will hold additional key/value pairs that define more specific -% semantics. This isn't implemented yet. -% -% The above describes my current thinking about how those arguments should -% interact. In simpler templates (based on 2e semantics) the arguments -% \HASH{3} to \HASH{5} and \HASH{7} will get ignored. -% -% -% \end{TemplateInterfaceDescription} -% -% -% \begin{TemplateDescription}{heading}{2e-vertical} -% -% -% \TemplateKey{name}{tokenlist} -% {Name of the heading. Used to refer to parts of its data structure, -% e.g., the counter associated with the heading will have this name. Must -% be set to a suitable string like ``section''} -% {none} -% -% \TemplateKey{level}{integer} -% {The level of the heading in the hierarchy. Required.} -% {none} -% -% \TemplateKey{break-penalty}{penalty} -% {Penlty to break in front of the heading unless it is immediately -% preceeded a higher-level heading in which case breaking is prohibited.} -% {-300} -% -% \TemplateKey{indent}{length} -% {Indentation of the heading from the left margin.} -% {0pt} -% -% \TemplateKey{above-skip}{skip} -% {Vertical space above the heading.} -% {0pt} -% -% \TemplateKey{below-skip}{skip} -% {Vertical space below the heading.} -% {0pt} -% -% \TemplateKey{title-decl}{function 0} -% {Declarations to format the heading, e.g., font changes.} -% {\EMPTY} -% -% \TemplateKey{number-format}{function 1} -% {Formatting instruction for the heading number (if present), receiving -% the heading counter representation as an argument.} -% {\cs{xhead_default_number_format:n}} -% -% \TemplateKey{indent-after}{boolean} -% {Should the first paragraph after the heading be indented?} -% {\FALSE} -% -% \TemplateSemantics -% -% This is, or should be, a reimplementation of the 2e |\@startsection| -% command for generating vertical headings. |\@startsection| is also able -% to produce run-in headings, but this is not covered by the current -% template. -% -% \end{TemplateDescription} -% -% -% -% -% -% \StopEventually{} -% -% \section{Implementation} -% -% \begin{macrocode} -%<*package> -\RequirePackage{expl3,xtemplate} -% \end{macrocode} -% -% \begin{macrocode} -\GetIdInfo$Id: xhead.dtx 1914 2010-05-21 16:18:46Z schoepf $ - {heading module} -\ProvidesExplPackage - {\filename}{\filedate}{\fileversion}{\filedescription} -% \end{macrocode} -% -% -% \subsection{The heading object type} -% -% Arguments: -%\begin{verbatim} -% #1 (boolean) : produce no number -% #2 (string/\NoValue/empty) : toc-title if different from title -% #3 (boolean) : force toc entry -% #4 (string/\NoValue/empty) : mark-title if different from toc-title -% #5 (Boolean) : force mark entry -% #6 (string) : title -% #7 (extra key vals) -%\end{verbatim} -% -% \begin{macrocode} -\DeclareObjectType {heading} {7} -% \end{macrocode} -% -% -% \subsection{Interfaces to other components} -% -% This section holds code that is (or should be) common between different -% heading templates, for example, code for passing a title to the TOC system -% will always use the same TOC interface so it is encapsulated -% here. Effectively this means that this section should be the only part that -% needs modification if we update these other components and intorduce new -% interfaces for them. -% -% At the moment everything is set up to use the old 2e interfaces, but this -% will change over time. -% -% -% -% \subsubsection{Generating TOC and mark entries} -% -% -% \begin{macro}{\xhead_generate_toc:NNNNN} -% \begin{macro}{\xhead_generate_toc:NNNNo} -% This command provides the interface to the TOC system (currently the 2e -% one). It uses its first two arguments to decide if a TOC entry should be produced -% and if so generates the entry from the remaining arguments. -% -% Arguments: -%\begin{verbatim} -% #1 (boolean) : produce no number -% #2 (boolean) : force toc entry -% #3 (string) : heading name (\l_xhead_name_tl) -% #4 (string) : heading number if any (\l_xhead_number_tl) -% #5 (string) : toc-title (\l_xhead_toc_title_tl) -%\end{verbatim} -% -% \begin{macrocode} -\cs_new:Npn \xhead_generate_toc:NNNNN #1#2#3#4#5 { -%<*trace> - \typeout{xhead_generate_toc:NNNNN=#1:#2:#3:#4:#5} -%</trace> -% \end{macrocode} -% A TOC entry is produced if the heading number was not suppressed (|!#1|) -% or it is forced (|#2|). -% \begin{macrocode} - \bool_if:nT - { #2 || ! #1 } - { - \group_begin: -% \end{macrocode} -% Guard against use of mark commands in the heading title (from old sources). -% \begin{macrocode} - \cs_set_eq:NN \@mkboth \use_none:nn - \cs_set_eq:NN \markboth \use_none:nn - \cs_set_eq:NN \markright \use_none:n -% \end{macrocode} -% Use the old 2e |\addcontentsline| interface: -% \begin{macrocode} - \addcontentsline{toc}{#3} - { - \tl_if_empty:NF #4 - { \protect\numberline{ #4 } } - #5 - } - \group_end: - } -} -% \end{macrocode} -% In the templates we really want to make sure that the title in the last -% argument is passed and not a tokenlist in which it is saved. After all, -% this text will get passed around over long distances. We therefore -% provide the following variant for use in templates: -% \begin{macrocode} -\cs_generate_variant:Nn \xhead_generate_toc:NNNNN {NNNNo} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% -% -% -% \begin{macro}{\xhead_generate_mark:NNNNN} -% \begin{macro}{\xhead_generate_mark:NNNNo} -% This command provides the interface to the mark system for running -% headers(currently the 2e one). It uses its first two arguments to decide -% if a mark entry should be produced and if so generates the entry from the -% remaining arguments. -% -% Arguments: -%\begin{verbatim} -% #1 (boolean) : produce no number -% #2 (boolean) : force running header entry -% #3 (string) : heading name (\l_xhead_name_tl) -% #4 (string) : heading number if any (\l_xhead_number_tl) -% #5 (string) : mark-title (\l_xhead_mark_title_tl) -%\end{verbatim} -% -% \begin{macrocode} -\cs_new:Npn \xhead_generate_mark:NNNNN #1#2#3#4#5 { -%<*trace> - \typeout{xhead_generate_mark:NNNNN=#1:#2:#3:#4:#5} -%</trace> -% \end{macrocode} -% A running header entry is produced if the heading number was not -% suppressed (|!#1|) or it is forced (|#2|). -% \begin{macrocode} - \bool_if:nT - { #2 || ! #1 } - { - \group_begin: -% \end{macrocode} -% Guard against use of mark command in heading titles (from old -% sources)\footnote{This is wrong here, needs thought.} -% \begin{macrocode} - \cs_set_eq:NN \@mkboth \use_none:nn -% \end{macrocode} -% Again we use the original 2e interface. |\markright|, etc.\ currently adds -% the section number so we do not add it here---for now. -% \begin{macrocode} - \use:c {#3 mark} {#5} - \group_end: - } -} -% \end{macrocode} -% In the templates we really want to make sure that the title in the last -% argument is passed and not a tokenlist in which it is saved. After all, -% this text will get passed around over long distances. We therefore -% provide the following variant for use in templates: -% \begin{macrocode} -\cs_generate_variant:Nn \xhead_generate_mark:NNNNN {NNNNo} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% -% -% -% \begin{macro}{\xhead_generate_toc_and_mark:NNNNNNN} -% -% This is just putting it all together, may not be worth having. -% -% Arguments: -%\begin{verbatim} -% #1 (boolean) : produce no number -% #2 (boolean) : force toc entry -% #3 (boolean) : force running header entry -% #4 (string) : heading name (\l_xhead_name_tl) -% #5 (string) : heading number or empty (\l_xhead_number_tl) -% #6 (string) : toc-title (\l_xhead_toc_title_tl) -% #7 (string) : mark-title (\l_xhead_mark_title_tl) -%\end{verbatim} -% -% \begin{macrocode} -\cs_new:Npn \xhead_generate_toc_and_mark:NNNNNNN #1#2#3#4#5#6#7 { - \xhead_generate_toc:NNNNo - #1 #2 #4 #5 #6 - \xhead_generate_mark:NNNNo - #1 #3 #4 #5 #7 -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% \subsubsection{Prepare heading number} -% -% -% -% \begin{macro}{\xhead_update_prepare_number:N} -% -% This command checks if a number should be produced and if so increments -% the corresponding counter and stores the number in -% |\l_xhead_number_tl|. Otherwise |\l_xhead_number_tl| will be set to empty -% to indicate that no number should be displayed. -% -% Arguments: -%\begin{verbatim} -% #1 (boolean) : produce no number -%\end{verbatim} - -% Assumptions: -%\begin{verbatim} -% \l_xhead_name_tl : holds heading name -% \l_xhead_level_int : holds heading level -%\end{verbatim} -% -% Outputs: -%\begin{verbatim} -% \l_xhead_number_tl : holds heading number or returns empty -%\end{verbatim} -% -% \begin{macrocode} -\cs_new:Npn \xhead_update_prepare_number:N #1 { - \bool_if:nTF - { #1 || \intexpr_compare_p:n { \l_xhead_level_int > \c@secnumdepth } } - { \tl_clear:N \l_xhead_number_tl } - { - \refstepcounter \l_xhead_name_tl - \tl_set:Nx \l_xhead_number_tl { \use:c {the \l_xhead_name_tl} } - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% \subsubsection{Prepare indentation after heading} -% -% To set the paragraph indentation after a heading we need to interact with -% the galley mechanism, which at one point will be \texttt{xgalley}. Right -% now we use the 2e interface. -% -% \begin{macro}{\xhead_set_after_indention:N} -% Here we set the 2e flag depending -% \begin{macrocode} -\cs_new:Npn \xhead_set_after_indention:N #1 { - \bool_if:NTF #1 \@afterindenttrue \@afterindentfalse -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% -% \subsubsection{Evaluating the title arguments} -% -% According to the heading object type spec the title text for the toc and -% running header may differ from the main title in dependence of the -% arguments passed to the template. -% The code below implements the documented logic. -% -% \begin{macro}{\xhead_set_titles:nnn} -% -% Arguments: -%\begin{verbatim} -% #1 (string/\NoValue/empty) : toc-title if different from title -% #2 (string/\NoValue/empty) : mark-title if different from toc-title -% #3 (string) : title -%\end{verbatim} -% -% \begin{macrocode} -\cs_new:Npn \xhead_set_titles:nnn #1#2#3 { -% \end{macrocode} -% Determine title for toc: -% If \HASH{1} is \NOVALUE{} or \EMPTY{} use \HASH{3} for the toc-title. -% Otherwise use \HASH{1}. -% \begin{macrocode} - \IfNoValueTF{#1} - { \tl_set:Nn \l_xhead_toc_title_tl {#3} } - { \tl_if_empty:nTF {#1} - { \tl_set:Nn \l_xhead_toc_title_tl {#3} } - { \tl_set:Nn \l_xhead_toc_title_tl {#1} } - } -% \end{macrocode} -% Determine title for mark: If \HASH{2} is \NOVALUE{} then use whatever was -% determined for the toc-title as value (i.e., if a special toc-title was -% used this will be also used for the running header, if not the main title -% is used). Otherwise, if \HASH{2} is \EMPTY{} use \HASH{3}. Otherwise use -% \HASH{2} (i.e., a special title was passed for the running header). -% \begin{macrocode} - \IfNoValueTF{#2} - { \tl_set_eq:NN \l_xhead_mark_title_tl \l_xhead_toc_title_tl } - { \tl_if_empty:nTF {#2} - { \tl_set:Nn \l_xhead_mark_title_tl {#3} } - { \tl_set:Nn \l_xhead_mark_title_tl {#2} } - } -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% \subsection{Support variables for template code} -% -% -% \begin{macrocode} -\dim_new:N \l_xhead_indent_dim -% \end{macrocode} -% -% -% -% \begin{macrocode} -\skip_new:N \l_xhead_above_skip -\skip_new:N \l_xhead_below_skip -% \end{macrocode} -% -% -% -% \begin{macrocode} -\int_new:N \l_xhead_level_int -\int_new:N \l_xhead_break_penalty_int -% \end{macrocode} -% -% \begin{macrocode} -\tl_new:N \l_xhead_name_tl -\tl_new:N \l_xhead_number_tl -\tl_new:N \l_xhead_toc_title_tl -\tl_new:N \l_xhead_mark_title_tl -% \end{macrocode} -% -% \begin{macrocode} -\bool_new:N \l_xhead_indent_after_bool - -\cs_new:Npn \xhead_title_decl: {} - -\cs_new:Npn \xhead_number_format:n #1 {} - -\cs_new:Npn \xhead_default_number_format:n #1 { #1 \quad} -% \end{macrocode} -% -% -% -% -% \subsection{The template \texttt{2e-vertical}} -% -% \begin{macrocode} -\DeclareTemplateInterface {heading} {2e-vertical} {7} - { - name : tokenlist = ??? , - level : integer = 0 , - break-penalty: integer = -300 , - indent : length = 0pt , - above-skip : skip = 0pt , - below-skip : skip = 0pt , - title-decl : function {0} = , - number-format: function {1} = \xhead_default_number_format:n {#1} , - indent-after : boolean = false , - } -% \end{macrocode} -% -% \begin{macrocode} -\DeclareTemplateCode {heading} {2e-vertical} {7} - { - name = \l_xhead_name_tl , - level = \l_xhead_level_int , - break-penalty = \l_xhead_break_penalty_int , - indent = \l_xhead_indent_dim , - above-skip = \l_xhead_above_skip , - below-skip = \l_xhead_below_skip , - title-decl = \xhead_title_decl: , - number-format = \xhead_number_format:n , - indent-after = \l_xhead_indent_after_bool , - } - { - \AssignTemplateKeys -% \end{macrocode} -% Determine title for toc and mark using the 2e logic: Do not generate -% them if the star-form of the heading is used and always use the same text -% for TOC and mark: -% \begin{macrocode} - \bool_if:NF #1 - { - \IfNoValueTF{#2} - { \tl_set:Nn \l_xhead_toc_title_tl {#6} } - { \tl_set:Nn \l_xhead_toc_title_tl {#2} } - \tl_set_eq:NN \l_xhead_mark_title_tl \l_xhead_toc_title_tl - } -% \end{macrocode} -% If heading number increment counter and set |\l_xhead_number_tl| -% \begin{macrocode} - \xhead_update_prepare_number:N #1 -% \end{macrocode} -% Indent after heading if requested (use old mechanism): -% \begin{macrocode} - \xhead_set_after_indention:N \l_xhead_indent_after_bool -% \end{macrocode} -% Produce the space above the heading (using old 2e methods): -% \begin{macrocode} - \if@noskipsec \leavevmode \fi - \par - \if@nobreak - \everypar{} - \else: - \addpenalty \l_xhead_break_penalty_int - \addvspace \l_xhead_above_skip - \fi: -% \end{macrocode} -% Produce the title of the heading (using old 2e methods) -% \begin{macrocode} - \group_begin: - \xhead_title_decl: - { - \@hangfrom{\hskip \l_xhead_indent_dim \scan_stop: - \tl_if_empty:NF \l_xhead_number_tl - { \xhead_number_format:n \l_xhead_number_tl } - } - \interlinepenalty \@M #6\@@par - } - \group_end: -% \end{macrocode} -% Generate toc entry and mark if required: -% \begin{macrocode} - \xhead_generate_toc_and_mark:NNNNNNN - #1 \BooleanFalse \BooleanFalse % no forcing in 2e - \l_xhead_name_tl - \l_xhead_number_tl - \l_xhead_toc_title_tl - \l_xhead_mark_title_tl -% \end{macrocode} -% Produce the space below the heading and the handling of following -% paragraph (using old 2e methods): -% \begin{macrocode} - \par \nobreak - \vspace \l_xhead_below_skip - \@afterheading - \ignorespaces - } -% \end{macrocode} -% -% -% -% -% \subsection{The template \texttt{3a-vertical}} -% -% Right now this template is more or less equal to \texttt{2e-vertical} -% except that it supports the extended heading arguments with the exception -% of \HASH{7}. -% -% \begin{macrocode} -\DeclareTemplateInterface {heading} {3a-vertical} {7} - { - name : tokenlist = ??? , - level : integer = 0 , - break-penalty : integer = -300 , - indent : length = 0pt , - above-skip : skip = 0pt , - below-skip : skip = 0pt , - format : tokenlist = indent-by-number , - parshape : instance {parshape} = plain , - justification : instance {justification} = flush-left , - font : tokenlist = , - number-format : function {1} = \xhead_default_number_format:n {#1} , - indent-after : boolean = false , - } -% \end{macrocode} -% - -% \begin{macro}{\l_xhead_title_format_tl} -% -% \begin{macrocode} -\tl_new:N \l_xhead_title_format_tl -\tl_new:N \l_xhead_title_font_tl - -\cs_new:Npn \xhead_title_parshape: {} -\cs_new:Npn \xhead_title_justification: {} - -% \end{macrocode} -% \end{macro} -% -% -% \begin{macrocode} -\DeclareTemplateCode {heading} {3a-vertical} {7} - { - name = \l_xhead_name_tl , - level = \l_xhead_level_int , - break-penalty = \l_xhead_break_penalty_int , - indent = \l_xhead_indent_dim , - above-skip = \l_xhead_above_skip , - below-skip = \l_xhead_below_skip , - format = \l_xhead_title_format_tl , - parshape = \xhead_title_parshape: , - justification = \xhead_title_justification: , - font = \l_xhead_title_font_tl , - number-format = \xhead_number_format:n , - indent-after = \l_xhead_indent_after_bool , - } - { - \AssignTemplateKeys -% \end{macrocode} -% Set title text for TOC and mark entry: -% \begin{macrocode} - \xhead_set_titles:nnn {#2} {#4} {#6} -% \end{macrocode} -% If heading gets a number, increment counter and set -% |\l_xhead_number_tl|. -% \begin{macrocode} - \xhead_update_prepare_number:N #1 -% \end{macrocode} -% Indent after heading if requested (use old mechanism) -% \begin{macrocode} - \xhead_set_after_indention:N \l_xhead_indent_after_bool -% \end{macrocode} -% -% Produce the space above the heading (using old 2e methods) -% -% \begin{macrocode} - \if@noskipsec \leavevmode \fi - \par - \if@nobreak - \everypar{} - \else: - \addpenalty \l_xhead_break_penalty_int - \addvspace \l_xhead_above_skip - \fi: -% \end{macrocode} -% -% Produce the title of the heading -% -% \begin{macrocode} - \xhead_use_title_format:nn \l_xhead_title_format_tl {#6} - -% \end{macrocode} -% Generate toc entry and mark: -% \begin{macrocode} - \xhead_generate_toc_and_mark:NNNNNNN - #1 #3 #5 - \l_xhead_name_tl - \l_xhead_number_tl - \l_xhead_toc_title_tl - \l_xhead_mark_title_tl -% \end{macrocode} -% Produce the space below the heading and the handling of following -% paragraph (using old 2e methods) -% \begin{macrocode} - \par \nobreak - \vspace \l_xhead_below_skip - \@afterheading - \ignorespaces - } -% \end{macrocode} -% -% -% -% \begin{macro}{\xhead_use_title_format:nn} -% Select a formatting command (based on first arg string) and use it to -% format the title (second arg). -% -% The formatting command makes a bunch of -% assumptions with respect to the variable names used by the templates (it -% might ignore some of them): -%\begin{verbatim} -% \l_xhead_title_font_tl : font declarations for title text -% \l_xhead_indent_dim : indentation from the left of title -% \xhead_title_parshape: : parshape instance to use for title -% \xhead_title_justification: : justification instance to use for title -% \l_xhead_number_tl : raw title number or empty -% \xhead_number_format:n : formatting command for title number -%\end{verbatim} -% In addition it takes a single mandatory argument holding the title text. -% -% \begin{macrocode} -\cs_new:Npn \xhead_use_title_format:nn #1 { - \cs_if_exist:cTF {xhead_format_ #1:n} - { \use:c{xhead_format_ #1:n} } - { \ERROR xhead format not defined } -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\xhead_format_indent-by-number:n} -% Implementing vertical version of |\@startsection| \ldots -% \begin{macrocode} -\cs_new:cpn {xhead_format_indent-by-number:n} #1 { - \group_begin: - \l_xhead_title_font_tl - \hbox_set:Nn \l_tmpa_box - { - \tl_if_empty:NF \l_xhead_number_tl - { \xhead_number_format:n \l_xhead_number_tl } - } - - \UseInstance{measure}{fullwidth} - {\l_xhead_indent_dim + \box_wd:N \l_tmpa_box } - - \xhead_title_parshape: - \xhead_title_justification: - \interlinepenalty \@M - - \noindent \hbox_overlap_left:n { \box_use:N \l_tmpa_box } - #1\@@par - \group_end: -} -% \end{macrocode} -% \end{macro} -% -% -% -% -% \begin{macro}{\xhead_format_number-above-text:n} -% -% \begin{macrocode} -\cs_new:cpn {xhead_format_number-above-text:n} #1 { - \group_begin: - \l_xhead_title_font_tl - \xhead_title_parshape: - \xhead_title_justification: - \interlinepenalty \@M - - \tl_if_empty:NF \l_xhead_number_tl - { - \xhead_number_format:n \l_xhead_number_tl - } - - #1\@@par - \group_end: -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macrocode} - -\input{xtextblock.sty} - - -\DeclareTemplateInterface {heading} {3b-vertical} {7} - { - name : tokenlist = ??? , - level : integer = 0 , - break-penalty : integer = -300 , - indent : length = 0pt , - above-skip : skip = 0pt , - below-skip : skip = 0pt , - title-format : instance {textblock-2} = heading , - number-format : function {1} = \xhead_default_number_format:n {#1} , - indent-after : boolean = false , - } - -\cs_new:Npn \xhead_title_format:nn #1#2 {} - -\DeclareTemplateCode {heading} {3b-vertical} {7} - { - name = \l_xhead_name_tl , - level = \l_xhead_level_int , - break-penalty = \l_xhead_break_penalty_int , - indent = \l_xhead_indent_dim , - above-skip = \l_xhead_above_skip , - below-skip = \l_xhead_below_skip , - title-format = \xhead_title_format:nn , - number-format = \xhead_number_format:n , - indent-after = \l_xhead_indent_after_bool , - } - { - \AssignTemplateKeys - - \xhead_set_titles:nnn {#2} {#4} {#6} - - \xhead_update_prepare_number:N #1 - - \xhead_set_after_indention:N \l_xhead_indent_after_bool - - \if@noskipsec \leavevmode \fi - \par - \if@nobreak - \everypar{} - \else: - \addpenalty \l_xhead_break_penalty_int - \addvspace \l_xhead_above_skip - \fi: - - \xhead_title_format:nn \l_xhead_number_tl {#6} - - \xhead_generate_toc_and_mark:NNNNNNN - #1 #3 #5 - \l_xhead_name_tl - \l_xhead_number_tl - \l_xhead_toc_title_tl - \l_xhead_mark_title_tl - - \par \nobreak - \vspace \l_xhead_below_skip - \@afterheading - \ignorespaces - } - - -% \end{macrocode} -% -% \Finale -% -% -% \begin{macrocode} -\endinput -%</package> -% \end{macrocode} -% -% \endinput -% -% -% -% -% \begin{TemplateInterfaceDescription}{} -% -% \TemplateArgument{1} -% {} -% -% \TemplateSemantics -% -% \end{TemplateInterfaceDescription} -% -% - - - - motto/quote text to display alongside the heading title - - flag to number heading - -label name for cross-reference - -% -% \begin{InstanceDescription}[\textbf{no-page-break-boolean}xx] -% {pshape}{staggered}{cutout} -% -% \InstanceKey{no-page-break-boolean}{true} -% -% \InstanceKey{left-side-boolean}{true} -% -% \InstanceKey{normal-lines-int}{1} -% -% \InstanceKey{parshape-list}{20pt,40pt,60pt} -% -% \InstanceSemantics -% This instance will indent each line by an additional 20pt (up to -% the fourth line). A possible application would be a heading text -% (with a maximum number of four lines). -% This should then perhaps be combined with a special justification -% instance which does ragged right except for the last line which is -% set to full measure. -% -% \end{InstanceDescription} -% -% - diff --git a/Master/texmf-dist/source/latex/xpackages/xhead/xhead.ins b/Master/texmf-dist/source/latex/xpackages/xhead/xhead.ins deleted file mode 100644 index 7d4286021a7..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xhead/xhead.ins +++ /dev/null @@ -1,73 +0,0 @@ -% \iffalse -%% -%% This file will generate fast loadable files and documentation -%% driver files from the dtx files in this package when run through -%% LaTeX or TeX. -%% -%% (C) Copyright 2009-2010 LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%% -%% This file is part of the ``xhead bundle'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -%% $Id: xhead.ins 1628 2009-10-25 09:54:34Z mittelba $ -%% -% \fi -% - -\input docstrip -\keepsilent -\askforoverwritefalse - -\preamble - -(C) Copyright The LaTeX3 Project and any individual authors -listed elsewhere in this file. - -This is a generated file. - -This file was generated from file(s) of the xhead bundle. ------------------------------------------------------------ - -This file may only be distributed together with a copy of this bundle. -You may however distribute the bundle without such generated files. - -====================================================================== - -\endpreamble - - -\generate{% - \file{xhead.sty}{\from{xhead.dtx}{package,trace}} -% \file{xhead-sample.tex}{\from{xhead.dtx}{sample}} -} - -\endbatchfile - diff --git a/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx b/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx deleted file mode 100644 index 8cb3a45240b..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.dtx +++ /dev/null @@ -1,308 +0,0 @@ -% \iffalse -%% File: l3keys2e.dtx (C) Copyright 2009,2011 LaTeX3 Project -%% -%% It may be distributed and/or modified under the conditions of the -%% LaTeX Project Public License (LPPL), either version 1.3c of this -%% license or (at your option) any later version. The latest version -%% of this license is in the file -%% -%% http://www.latex-project.org/lppl.txt -%% -%% This file is part of the ``l3keys2e'' (The Work in LPPL) -%% and all files in that bundle must be distributed together. -%% -%% The released version of this bundle is available from CTAN. -%% -%% ----------------------------------------------------------------------- -%% -%% The development version of the bundle can be found at -%% -%% http://www.latex-project.org/svnroot/experimental/trunk/ -%% -%% for those people who are interested. -%% -%%%%%%%%%%% -%% NOTE: %% -%%%%%%%%%%% -%% -%% Snapshots taken from the repository represent work in progress and may -%% not work or may contain conflicting material! We therefore ask -%% people _not_ to put them into distributions, archives, etc. without -%% prior consultation with the LaTeX Project Team. -%% -%% ----------------------------------------------------------------------- -%% -% -%<*driver|package> -\RequirePackage{l3names} -%</driver|package> -%\fi -\GetIdInfo$Id: l3keys2e.dtx 2320 2011-05-06 16:56:27Z joseph $ - {Parsing LaTeX3 keyvals as LaTeX2e package options} -%\iffalse -%<*driver> -%\fi -\ProvidesFile{\filename.\filenameext} - [\filedate\space v\fileversion\space\filedescription] -%\iffalse -\documentclass{l3doc} -\begin{document} - \DocInput{l3keys2e.dtx} -\end{document} -%</driver> -% \fi -% -% \title{The \textsf{l3keys2e} package\thanks{This file -% has version number \fileversion, last revised \filedate.}\\ -% Parsing \LaTeX3 keyvals as \LaTeXe\ package options} -% \author{\Team} -% \date{\filedate} -% \maketitle -% -%\begin{documentation} -% -%\section{Key--value arguments as \LaTeXe\ class and package options} -% -% The key--value method for optional arguments is very popular, as it -% allows the class or package author to define a large number of -% options with a simple interface. The \pkg{expl3} bundle of \LaTeX3 -% base code includes the module \pkg{l3keys} for defining keys, but -% to use these when loading \LaTeXe\ packages and classes requires -% extra support. That support is provided by this small package, which -% is intended to enable \LaTeXe\ packages to benefit from the power of -% the \LaTeX3 key--value system. -% -%\subsection{Creating and using keyval options} -% -% As with any key--value input, using key--value pairs as package or -% class options has two parts. The first stage is to define one or -% more keys, using the \cs{keys_define:nn} function. For example, an -% option which simply stores a value would be created using: -%\begin{verbatim} -% \keys_define:nn { module } { -% option .set:N = \l_module_variable_tl -% } -%\end{verbatim} -% On its own, this will not make the key an option for the package or -% class containing the definition. The second stage is therefore to -% process the current options, searching for applicable keys. -% -%\begin{function}{ \ProcessKeysOptions } -% \begin{syntax} -% \cs{ProcessKeysOptions} \Arg{module} -% \end{syntax} -% The \cs{ProcessKeysOptions} function is used to check the current -% option list against the keys defined for \Arg{module}. Global (class) -% options and local (package) options are checked when this function -% is called in a package. Each option which does match a key name is -% then used to attempt to set the appropriate key using -% \cs{keys_set:nn}. For example, the option defined earlier would be -% processed by the line -% \begin{verbatim} -% \ProcessKeysOptions { module } -% \end{verbatim} -%\end{function} -% -%\begin{function}{ \ProcessKeysPackageOptions } -% \begin{syntax} -% \cs{ProcessKeysPackageOptions} \Arg{module} -% \end{syntax} -% This function works in a similar manner to \cs{ProcessKeysOptions}. -% When used in a \LaTeXe\ package, \cs{ProcessKeysPackageOptions} -% will not examine any class options available. In contrast, -% \cs{ProcessKeysOptions} does parse class options (in common with the -% \LaTeXe\ kernel function \cs{ProcessOptions}). -%\end{function} -% -%\end{documentation} -% -%\begin{implementation} -% -%\subsection{Implementation} -% -% The usual lead-off. -% \begin{macrocode} -%<*package> -\ProvidesExplPackage - {\filename}{\filedate}{\fileversion}{\filedescription} -\RequirePackage { xparse } -% \end{macrocode} -% -%\begin{macro}{\keys_latexe_options_clist} -% A single list is used for all options, into which they are collected -% before processing. -% \begin{macrocode} -\clist_new:N \keys_latexe_options_clist -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\_l_keys_process_class_bool} -% A flag to indicate that class options should be processed for -% packages. -% \begin{macrocode} -\bool_new:N \_l_keys_process_class_bool -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\keys_latexe_options:n} -% The main function calls functions to collect up the global and local -% options into \cs{keys_latexe_options_clist} before calling the -% underlying functions to actually do the processing. So that a suitable -% message is produced if the option is unknown, the special -% \texttt{unknown} key is set if it does not already exist for the -% current module. -% \begin{macrocode} -\cs_new_protected:Npn \keys_latexe_options:n #1 { - \clist_clear:N \keys_latexe_options_clist - \keys_latexe_options_global:n {#1} - \keys_latexe_options_local: - \cs_if_exist:cTF { \c_keys_root_tl {#1} / unknown .cmd:n } - { - \keys_define:nn {#1} - { - unknown .code:n = - { - \msg_kernel_error:nnxx { keyvalue } { option-unknown } - { \l_keys_key_tl } { \@currname } - } - } - } - \keys_set:nV {#1} \keys_latexe_options_clist - \AtEndOfPackage { \cs_set_eq:NN \@unprocessedoptions \scan_stop: } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\keys_latexe_options_global:n} -% Global (class) options are handled differently for \LaTeXe\ packages -% and classes. Hence this function is essentially a check on the current -% file type. The initial test is needed as \LaTeXe\ allows variables to -% be equal to \cs{scan_stop:}, which is forbidden in \LaTeX3 code. -% \begin{macrocode} -\cs_new_protected:Npn \keys_latexe_options_global:n #1 { - \cs_if_eq:NNF \@classoptionslist \scan_stop: - { - \cs_if_eq:NNTF \@currext \@clsextension - { \keys_latexe_options_class:n {#1} } - { - \bool_if:NT \_l_keys_process_class_bool - { \keys_latexe_options_package:n {#1} } - } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\keys_latexe_options_class:n} -% For classes, each option (stripped of any content after `\texttt{=}') -% is checked for existence as a key. If found, the option is added to -% the combined list for processing. On the other hand, unused options -% are stored up in \cs{@unusedoptionlist}. -% \begin{macrocode} -\cs_new_protected:Npn \keys_latexe_options_class:n #1 { - \clist_map_inline:Nn \@classoptionslist - { - \cs_if_exist:cTF - { - \c_keys_root_tl #1 / - \keys_latexe_remove_equals:n {##1} .cmd:n - } - { \clist_put_right:Nn \keys_latexe_options_clist {##1} } - { \clist_put_right:Nn \@unusedoptionlist {##1} } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\keys_latexe_options_package:n} -% For global options when processing a package, the tasks are slightly -% different from those for a class. The check is the same, but here -% there is nothing to do if the option is not applicable. Each valid -% option also needs to be removed from \cs{@unusedoptionlist}. -% \begin{macrocode} -\cs_new_protected:Npn \keys_latexe_options_package:n #1 { - \clist_map_inline:Nn \@classoptionslist - { - \cs_if_exist:cT - { - \c_keys_root_tl #1 / - \keys_latexe_remove_equals:n {##1} .cmd:n - } - { - \clist_put_right:Nn \keys_latexe_options_clist {##1} - \clist_remove_element:Nn \@unusedoptionlist {##1} - } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\keys_latexe_options_local:} -% If local options are found, the are added to the processing list. -% \LaTeXe\ stores options for each file in a macro which may or may not -% exist, hence the need to use \cs{cs_if_exist:c}. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \keys_latexe_options_local: { - \cs_if_eq:NNF \@currext \@clsextension - { - \cs_if_exist:cT { opt@ \@currname . \@currext } - { - \exp_args:NNc \clist_put_right:NV \keys_latexe_options_clist - { opt@ \@currname . \@currext } - } - } -} -% \end{macrocode} -%\end{macro} -% -%\begin{macro}{\keys_latexe_remove_equals:n} -%\begin{macro}{\keys_latexe_remove_equals:w} -% As the name suggests, this is a simple function to remove an equals -% sign from the input. This is all wrapped up in an \texttt{n} function -% so that there will always be a sign available. -% \begin{macrocode} -\cs_new:Npn \keys_latexe_remove_equals:n #1 { - \keys_latexe_remove_equals:w #1 = \q_stop -} -\cs_new:Npn \keys_latexe_remove_equals:w #1 = #2 \q_stop {#1} -% \end{macrocode} -%\end{macro} -%\end{macro} -% -%\begin{macro}{\ProcessKeysOptions} -%\begin{macro}{\ProcessKeysOptions} -% The user macro are simply wrappers around the internal process. In -% contrast to other similar packages, the module name is always required -% here. -% \begin{macrocode} -\cs_new_protected:Npn \ProcessKeysOptions #1 { - \bool_set_true:N \_l_keys_process_class_bool - \keys_latexe_options:n {#1} -} -\cs_new_protected:Npn \ProcessKeysPackageOptions #1 { - \bool_set_false:N \_l_keys_process_class_bool - \keys_latexe_options:n {#1} -} -\@onlypreamble \ProcessKeysOptions -\@onlypreamble \ProcessKeysPackageOptions -% \end{macrocode} -%\end{macro} -%\end{macro} -% -% One message to give. -% \begin{macrocode} -\msg_kernel_new:nnnn { keyvalue } { option-unknown } - { Unknown~option~'#1'~for~package~#2. } - { - LaTeX~has~been~asked~to~set~an~option~called~'#1'\\ - but~the~#2~package~has~not~created~an~option~with~this~name. - } -% \end{macrocode} -% -% \begin{macrocode} -%</package> -% \end{macrocode} -% -% \end{implementation} -% -% \PrintIndex diff --git a/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.ins b/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.ins deleted file mode 100644 index 75c72b058d4..00000000000 --- a/Master/texmf-dist/source/latex/xpackages/xtras/l3keys2e.ins +++ /dev/null @@ -1,19 +0,0 @@ -\input docstrip -\keepsilent -\askforoverwritefalse - -\preamble ----------------------------------------------------------------- -l3keys2e --- Parsing LaTeX3 keyvals as LaTeX2e package options -Copyright 2009 The LaTeX3 Project -Released under the LaTeX Project Public License v1.3c or later -See http://www.latex-project.org/lppl.txt ----------------------------------------------------------------- -\endpreamble - - -\generate{% - \file{l3keys2e.sty}{\from{l3keys2e.dtx}{package}} -} - -\endbatchfile |