% \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} % %\fi \GetIdInfo$Id: xtemplate.dtx 1896 2010-04-14 17:40:38Z 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} % % \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} % "{" % " " ":" "," % " " ":" "=" "," % " ..." % "}" % \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 define what sort of input the key accepts, such as `boolean', % `integer', and so on. The complete list of possible 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} % "{" % " " "=" "," % " " "=" "," % " ..." % "}{" % " "\meta{implementation code} % " \AssignTemplateKeys" % " "\meta{more implementation code} % "}" % \end{syntax} % After the keys have been declared with "\DeclareTemplateInterface", the % implementation binds each with an % (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 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} % " " "=" "," % " " "=" global "," % \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 % for the template design, taking arguments |#1|, |#2|, etc.\ according to the number of % arguments allowed, . \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 , with % the keyval input to set some or all of the