l3experimental 2900 (10oct11)

git-svn-id: svn://tug.org/texlive/trunk@24258 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 1602 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/l3experimental/xgalley/xgalley.dtx b/Master/texmf-dist/source/latex/l3experimental/xgalley/xgalley.dtx
new file mode 100644
index 00000000000..0dc1c85b610
--- /dev/null
+++ b/Master/texmf-dist/source/latex/l3experimental/xgalley/xgalley.dtx
@@ -0,0 +1,1602 @@
+% \iffalse
+%
+%% File: xgalley.dtx Copyright (C) 1999-2001, 2004-2009 Frank Mittelbach
+%%                             (C) 2010,2011 The 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 "l3experimental 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}
+\GetIdInfo$Id: xgalley.dtx 2895 2011-10-09 15:58:19Z joseph $
+  {L3 Experimental galley}
+%</driver|package>
+%<*driver>
+\documentclass[full]{l3doc}
+\begin{document}
+  \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \title{^^A
+%   The \textsf{xgalley} package\\ Galley^^A
+%   \thanks{This file describes v\ExplFileVersion,
+%     last revised \ExplFileDate.}^^A
+% }
+%
+% \author{^^A
+%  The \LaTeX3 Project\thanks
+%    {^^A
+%      E-mail:
+%        \href{mailto:latex-team@latex-project.org}
+%          {latex-team@latex-project.org}^^A
+%    }^^A
+% }
+%
+% \date{Released \ExplFileDate}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% \section{Introduction}
+%
+% In \LaTeX3 terminology a galley is a rectangular area which receives
+% text and other material filling it from top. The vertically extend of
+% a galley is normally not restricted: instead certain chunks are taken
+% off the top of an already partially filled galley to form columns or
+% similar areas on a page. This process is typically asynchronous but
+% there are ways to control or change its behaviour.
+%
+% Examples for galleys are \enquote{the main galley}, where the
+% continuous document data gets formatted into  and from which columns
+% and pages are constructed, and \enquote{vertical box galleys}, such
+% as the body of a minipage environment. The latter galleys are
+% typically not split after formatting, though there can be exceptions.
+%
+% \section{Formatting layers}
+%
+% The present module is mainly concerned with the formatting of text
+% in galleys. The mechanism by which this is achieved uses four
+% (somewhat) distinct layers, some of which can be addressed using the
+% templates provided here.
+%
+% \subsection{Layer one: external dimensions}
+%
+% The bottom layer of the system is the external dimensions of the
+% galley. Normally only the horizontal dimension is fixed externally,
+% while the vertical (filling) dimension is unspecified. The external
+% dimensions are fixed when starting a new galley, and are therefore
+% not modifiable within the galley.
+%
+% There are no templates for setting this layer directly, although the
+% external values are influenced by other parts of the system (for
+% example when creating minipage environments).
+%
+% \subsection{Layer two: internal dimensions}
+%
+% The second layer is the internal dimensions of the galley: the
+% \emph{measure} used for paragraph text and the position of the
+% paragraph relative to the edges of the galley.
+%
+% This layer is normally accessed by higher-level templates
+% \emph{via} the object type \texttt{measure}. Changes made using
+% level two templates will often extend for large parts of a document
+% (up to and including the entire document).
+%
+% \subsection{Layer three: paragraph shape}
+%
+% The third layer defines the paragraph shape within the measure as
+% provided by the second layer. In the absence of any specification
+% for that layer the paragraph shape used will be that of a
+% rectangular area of the width of the current measure.
+%
+% There are some restrictions imposed on the shape of a paragraph by the
+% underlying \TeX{} mechanisms. For example, cut out sections in
+% paragraphs can be specified from the top of the paragraph but not from
+% the bottom.
+%
+% \subsection{Layer four: formatting inside the paragraph}
+%
+% The forth layer deals with the paragraph formatting aspects such as
+% hyphenation and justification within the paragraph (this is sometimes
+% referred to as \enquote{\texttt{h\&j}} or \enquote{\texttt{hj}}).
+%
+% \section{Templates}
+%
+% \subsection{Layer two: internal dimensions}
+%
+% \begin{TemplateInterfaceDescription}{measure}
+%   \TemplateArgument{}{} ^^A A hack
+%   \TemplateSemantics
+%   Sets the width available to typeset material within the galley.
+%   The \meta{left margin} and \meta{right margin} values are used in the
+%   adjustment to over-ride any given in the template. Depending upon
+%   the template in use, the margins may be absolute (relative only to the
+%   edges of the galley) or relative (taking account of |measure| adjustments
+%   already made). The template applies to the galley from the point of
+%   us forward, unless over-ridden by another use of the |measure|
+%   object type.
+% \end{TemplateInterfaceDescription}
+%
+% \begin{TemplateDescription}{measure}{absolute}
+%   \TemplateKey{left-margin}{length}
+%     {^^A
+%       The distance from the left edge of the galley to the left edge of
+%       the area for typeset material. A negative value will cause the
+%       typeset material to extend beyond the edge of the galley.^^A
+%     }
+%     {0 pt}
+%   \TemplateKey{right-margin}{length}
+%     {^^A
+%       The distance from the right edge of the galley to the right edge of
+%       the area for typeset material. A negative value will cause the
+%       typeset material to extend beyond the edge of the galley.^^A
+%     }
+%     {0 pt}
+%   \TemplateSemantics
+%   This template sets up the typesetting area such that typeset material
+%   runs from |left-margin| away from the left edge of the galley to
+%   |right-margin| away from the right edge of the galley. Both of these
+%   distances are absolute, \emph{i.e.}~no account is taken of previous
+%   |measure| settings. Either on or both values may be negative, in which
+%   case the typeset material will protrude outside of the edges of the
+%   galley.
+% \end{TemplateDescription}
+%
+% \begin{TemplateDescription}{measure}{relative}
+%   \TemplateKey{left-margin}{length}
+%     {^^A
+%       The distance from the previous left margin of the typeset material
+%       within the galley to the new position of the left margin. A negative
+%       value will cause the new margin to be \enquote{outside} of the
+%       previous one, and \emph{may} cause the typeset material to
+%       protrude outside of the edge of the galley.
+%     }
+%     {0 pt}
+%   \TemplateKey{right-margin}{length}
+%     {^^A
+%       The distance from the previous right margin of the typeset material
+%       within the galley to the new position of the right margin. A negative
+%       value will cause the new margin to be \enquote{outside} of the
+%       previous one, and \emph{may} cause the typeset material to
+%       protrude outside of the edge of the galley.
+%     }
+%     {0 pt}
+%   \TemplateSemantics
+%   This template sets up the typesetting area such that it has margins
+%   |left-margin| and |right-margin| within those previously set. For a
+%   galley within no previous margins, this will result in margins relative
+%   to the edges of the galley. Within a galley in which the |measure| has
+%   already been set, using the |relative| template will indent the typeset
+%   material relative to the existing margins.
+%   Either on or both values may be negative, in which
+%   case the typeset material may protrude outside of the edges of the
+%   galley.
+% \end{TemplateDescription}
+%
+% \subsection{Layer three: paragraph shape}
+%
+% \begin{TemplateInterfaceDescription}{parshape}
+%   \TemplateArgument{}{}^^A A hack
+%   \TemplateSemantics
+%   Template of this type define any shaping of the paragraph within the
+%   current measure of the galley. Thus they are used to generate
+%   \enquote{special} paragraph shapes, for example placing a cutout
+%   in one side of the paragraph. Typically, \texttt{parshape} templates
+%   will apply in a limited sense (to a single paragraph or a defined number of
+%   lines). However, \texttt{parshape} templates may also apply in an
+%   \enquote{ongoing} manner.
+%
+%   Note that \texttt{parshape} templates do not alter any first-line
+%   indent for paragraphs (or any other \enquote{in paragraph} setting).
+%   Instead, they define a shape inside which the paragraph material will be
+%   placed.
+% \end{TemplateInterfaceDescription}
+%
+% \begin{TemplateDescription}{parshape}{hang}
+%   \TemplateKey{indent}{length}
+%     {^^A
+%       The hanging indent from either the left- or right-hand margin
+%       (as determined by \texttt{on-left-side}).^^A
+%     }
+%     {0 pt}
+%   \TemplateKey{on-left-side}{boolean}
+%     {^^A
+%       If \texttt{true}, causes the hanging indent to be on the left-hand
+%       side of the paragraph.^^A
+%     }
+%     {true}
+%   \TemplateKey{lines}{integer}
+%     {The number of lines of full width before hanging begins.}
+%     {1}
+%  \TemplateSemantics
+%  Sets the paragraph shape such that the after a number of full-width
+%  lines, specified by |lines|, the paragraph is indented by the
+%  |indent| from a margin. If |on-left-side| is |true| this indent will be
+%  from the left-hand margin, otherwise it will be from the right. In either
+%  case, the indent is relative to the edge of the current |measure| and
+%  may be negative (in which case an outdent will result).
+%  This template type applies only to a single paragraph.
+% \end{TemplateDescription}
+%
+% \begin{TemplateDescription}{parshape}{initial}
+%   \TemplateKey{indent}{length}
+%     {^^A
+%       The indent for the initial lines from either the left- or right-hand
+%       margin (as determined by \texttt{on-left-side}).^^A
+%     }
+%     {0 pt}
+%   \TemplateKey{on-left-side}{boolean}
+%     {^^A
+%       If \texttt{true}, causes the indent to be on the left-hand
+%       side of the paragraph.^^A
+%     }
+%     {true}
+%   \TemplateKey{lines}{integer}
+%     {The number of lines of indented lines before full-width line begins.}
+%     {2}
+%   \TemplateSemantics
+%   Sets the paragraph shape such that the first |lines| lines
+%   are indented by the |indent| given, before lines of full width begin.
+%   If |on-left-side| is |true| this indent will be
+%   from the left-hand margin, otherwise it will be from the right. In either
+%   case, the indent is relative to the edge of the current |measure| and
+%   may be negative (in which case an outdent will result).
+%   This template type applies only to a single paragraph.
+% \end{TemplateDescription}
+%
+% \begin{TemplateDescription}{parshape}{std}
+%   \TemplateKey{}{}{}{} ^^A hack
+%   \TemplateSemantics
+%   Sets a rectangular paragraph shape which occupies the full width
+%   specified by the |measure|. It is therefore intended as a
+%   \enquote{do nothing} template for use where a paragraph shape is required
+%   but where no special formatting is needed. This template type applies only
+%   to a single paragraph.
+% \end{TemplateDescription}
+%
+% \subsection{Layer four: formatting inside the paragraph}
+%
+% \begin{TemplateInterfaceDescription}{hyphenation}
+%   \TemplateArgument{}{} ^^A Hack
+%   \TemplateSemantics
+%   Controls whether hyphenation is attempted within the current
+%   galley. This object type may also alter the degree to which hyphenation
+%   is encouraged by manipulating the underlying \TeX{} parameters. This
+%   object type applies to the galley from the point of use forward.
+% \end{TemplateInterfaceDescription}
+%
+% \begin{TemplateDescription}{hyphenation}{std}
+%   \TemplateKey{enable}{boolean}
+%     {Switches all hyphenation on or off.}
+%     {true}
+%   \TemplateKey{enable-upper-case}
+%     {boolean}
+%     {^^A
+%       Switches hyphenation on or off for words beginning with upper case
+%       letters.^^A
+%     }
+%     {true}
+%   \TemplateKey{penalty}{choice}
+%     {^^A
+%       Sets the degree to which \TeX{} is discouraged from undertaking
+%       hyphenation, from the choices |low|, |medium| and |high|.^^A
+%     }
+%     {low}
+%   \TemplateSemantics
+%   Determines both whether hyphenation is allowed at all, and if so to
+%   what degree it is discouraged. Setting |penalty| to |high| does not
+%   prevent hyphenation: this is only done if |enable| is set |false|.
+% \end{TemplateDescription}
+%
+% \begin{TemplateInterfaceDescription}{justification}
+%   \TemplateArgument{}{} ^^A Hack
+%   \TemplateSemantics
+%   Controls the nature of justification undertaken within the galley.
+%   The template applies from the point of use forward.
+% \end{TemplateInterfaceDescription}
+%
+% \begin{TemplateDescription}{justification}{std}
+%   \TemplateKey{end-skip}{skip}
+%     {The skip inserted to fill the last line of a paragraph.}
+%     {0 pt plus 1 fil}
+%   \TemplateKey{fixed-word-spacing}{boolean}
+%     {^^A
+%       Determines whether inter-word spacing has a stretch component (for
+%       non-monospaced fonts.^^A
+%     }
+%     {false}
+%   \TemplateKey{indent-width}{length}
+%     {^^A
+%       The length of the indent inserted at the start of the first line of a
+%       new paragraph.^^A
+%     }
+%     {}
+%   \TemplateKey{left-skip}{skip}
+%     {^^A
+%       The skip between the left margin of the galley and the left edge of a
+%       paragraph.^^A
+%     }
+%     {0 pt}
+%   \TemplateKey{right-skip}{skip}
+%     {^^A
+%       The skip between the right margin of the galley and the right edge of a
+%       paragraph.^^A
+%     }
+%     {0 pt}
+%   \TemplateKey{start-skip}{skip}
+%     {^^A
+%       The skip inserted in addition to |indent-width| at the start of a
+%       paragraph.^^A
+%     }
+%     {0 pt}
+%   \TemplateSemantics
+%   The |std| template for justification provides rubber lengths
+%   at the start and end of the paragraph and at each side of the paragraph.
+%   It also allows for both flexible and fixed inter-word spacing. The
+%   interaction between the settings is demonstrated in the selection of
+%   standard instances provided.
+% \end{TemplateDescription}
+%
+% \begin{InstanceDescription}{justification}{justified}{std}
+%   \InstanceKey{indent-width}{15 pt}
+%   \InstanceSemantics
+%   Sets paragraphs fully-justified with the first line indented by
+%   |15 pt|.
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{justification}{noindent}{std}
+%   \InstanceKey{end-skip}{15 pt plus 1 fil}
+%   \InstanceKey{indent-width}{0 pt}
+%   \InstanceSemantics
+%   Sets paragraphs fully-justified with no indent for the first line. To
+%   ensure that paragraphs have some visual distinction, the |end-skip| is
+%   set to insert some space in all cases.
+% \end{InstanceDescription}
+%
+% \begin{TemplateDescription}{justification}{single}
+%   \TemplateKey{end-skip}{skip}
+%     {The skip inserted to fill the last line of a paragraph.}
+%     {0 pt plus 1 fil}
+%   \TemplateKey{fixed-word-spacing}{boolean}
+%     {^^A
+%       Determines whether inter-word spacing has a stretch component (for
+%       non-monospaced fonts.^^A
+%     }
+%     {false}
+%   \TemplateKey{indent-width}{length}
+%     {^^A
+%       The length of the indent inserted at the start of the first line of a
+%       new paragraph.^^A
+%     }
+%     {}
+%   \TemplateKey{left-skip}{skip}
+%     {^^A
+%       The skip between the left margin of the galley and the left edge of a
+%       paragraph.^^A
+%     }
+%     {0 pt}
+%   \TemplateKey{right-skip}{skip}
+%     {^^A
+%       The skip between the right margin of the galley and the right edge of a
+%       paragraph.^^A
+%     }
+%     {0 pt}
+%   \TemplateKey{start-skip}{skip}
+%     {^^A
+%       The skip inserted in addition to |indent-width| at the start of a
+%       paragraph.^^A
+%     }
+%     {0 pt}
+%   \TemplateKey{stretch-last-line}{boolean}
+%     {
+%       Determines whether inter-word spacing in the last line is stretched.
+%       If \texttt{true}, the spacing in the last line is stretched in the
+%       by the same factor as that in the penultimate line.^^A
+%     }
+%     {false}
+%   \TemplateSemantics
+%   The |single| template for justification provides rubber lengths
+%   at the start and end of the paragraph and at each side of the paragraph.
+%   It also allows for both flexible and fixed inter-word spacing. The
+%   interaction between the settings is demonstrated in the selection of
+%   standard instances provided. The template applies only to a single
+%   paragraph.
+% \end{TemplateDescription}
+%
+% \begin{InstanceDescription}{justification}{centered}{std}
+%   \InstanceKey{end-skip}{0 pt}
+%   \InstanceKey{fixed-word-spacing}{true}
+%   \InstanceKey{indent-width}{0 pt}
+%   \InstanceKey{left-skip}{0 pt plus 1 em}
+%   \InstanceKey{right-skip}{0 pt plus 1 em}
+%   \InstanceSemantics
+%   Centres typeset material such that hyphenation will still occur and
+%   such that very short lines are discouraged. This is similar to the
+%   \LaTeXe{} \pkg{ragged2e} \env{Centering} environment.
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{justification}{ragged-left}{std}
+%   \InstanceKey{end-skip}{0 pt}
+%   \InstanceKey{fixed-word-spacing}{true}
+%   \InstanceKey{indent-width}{0 pt}
+%   \InstanceKey{left-skip}{0 pt plus 2 em}
+%   \InstanceKey{right-skip}{0 pt}
+%   \InstanceSemantics
+%   Typesets material with a ragged left margin such that hyphenation will
+%   still occur and such that very short lines are discouraged. This is
+%   similar to the \LaTeXe{} \pkg{ragged2e} \env{RaggedLeft} environment.
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{justification}{ragged-right}{std}
+%   \InstanceKey{end-skip}{0 pt}
+%   \InstanceKey{fixed-word-spacing}{true}
+%   \InstanceKey{indent-width}{0 pt}
+%   \InstanceKey{left-skip}{0 pt}
+%   \InstanceKey{right-skip}{0 pt plus 2 em}
+%   \InstanceSemantics
+%   Typesets material with a ragged right margin such that hyphenation will
+%   still occur and such that very short lines are discouraged. This is
+%   similar to the \LaTeXe{} \pkg{ragged2e} \env{RaggedLeft} environment.
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{justification}{center}{std}
+%   \InstanceKey{end-skip}{0 pt}
+%   \InstanceKey{fixed-word-spacing}{true}
+%   \InstanceKey{indent-width}{0 pt}
+%   \InstanceKey{left-skip}{0 pt plus 1 fil}
+%   \InstanceKey{right-skip}{0 pt plus 1 fil}
+%   \InstanceSemantics
+%   Centres typeset material such that hyphenation is strongly discouraged
+%   and short lines are allowed. This template is suited to centring arbitrary
+%   material (such as boxes) rather than centring text. In the later case, the
+%   |centered| instance should be used.
+% \end{InstanceDescription}
+%
+% \begin{TemplateDescription}{justification}{compound}
+%   \TemplateKey{first-paragraph}{instance}
+%     {Justification for the first paragraph.}
+%     {}
+%   \TemplateKey{other-paragraphs}{instance}
+%     {Justification for the remaining paragraphs.}
+%     {}
+%   \TemplateSemantics
+%   Here, both keys should themselves be instances of the |justification|
+%   template. The |compound| template is used to set up a single
+%   \enquote{non-standard} paragraph followed by \enquote{standard} ones.
+%   For example, it can be used to ensure that one |noindent| paragraph is
+%   then followed by |std| justification.
+% \end{TemplateDescription}
+%
+% \begin{TemplateInterfaceDescription}{line-breaking}
+%   \TemplateArgument{}{} ^^A Hack
+%   \TemplateSemantics
+%   Controls the line breaking attempted by \TeX{} when typesetting
+%   material for the galley. This does not include whether words are
+%   hyphenated, which is handled separately.
+% \end{TemplateInterfaceDescription}
+%
+% \begin{TemplateDescription}{line-breaking}{std}
+%   \TemplateKey{badness}{integer}
+%      {^^A
+%        Boundary that if exceeded will cause \TeX{} to report an
+%        underfull line.^^A
+%      }
+%      {1000}
+%   \TemplateKey{binop-penalty}{integer}
+%      {^^A
+%        Penalty charged if an inline math formula is broken at a
+%        binary operator.^^A
+%      }
+%      {700}
+%   \TemplateKey{double-hyphen-demerits}{integer}
+%      {^^A
+%        Extra demerit charge of two (or more) lines in succession end
+%        in a hyphen.^^A
+%      }
+%      {10 000}
+%   \TemplateKey{emergency-stretch}{skip}
+%      {^^A
+%        Additional stretch assumed for each line if no better line breaking
+%        can be found without it. This stretch is not actually added to lines,
+%        so its use may result in underfull box warnings.^^A
+%      }
+%      {0 pt}
+%   \TemplateKey{final-hyphen-demerits}{integer}
+%      {Extra demerit charge if the second last line is hyphenated.}
+%      {5000}
+%   \TemplateKey{fuzz}{length}
+%      {Boundary below overfull lines are not reported.}
+%      {0.1 pt}
+%   \TemplateKey{mismatch-demerits}{integer}
+%      {^^A
+%        Extra demerit charge if two visually incompatible lines follow
+%        each other.^^A
+%      }
+%      {10000}
+%   \TemplateKey{line-penalty}{integer}
+%      {^^A
+%        Extra penalty charged per line in the paragraph. By making
+%        this penalty higher \TeX{} will try harder to produce compact
+%        paragraphs.^^A
+%      }
+%      {10}
+%   \TemplateKey{pretolerance}{integer}
+%      {^^A
+%        Maximum tolerance allowed for individual lines to break the
+%        paragraph without attempting hyphenation.^^A
+%      }
+%      {100}
+%   \TemplateKey{relation-penalty}{integer}
+%      {^^A
+%        Penalty charged if an inline math formula is broken at a
+%        relational symbol.^^A
+%      }
+%      {500}
+%   \TemplateKey{tolerance}{integer}
+%      {^^A
+%        Maximum tolerance allowed for individual lines when breaking a
+%        paragraph while attempting hyphenation (if this limit can't be
+%        met \texttt{emergency-stretch} comes into play).^^A
+%      }
+%      {200}
+%   \TemplateSemantics
+%   This is an interface to the underlying \TeX{} system for determining
+%   line breaking.
+% \end{TemplateDescription}
+%
+% \subsection{Between paragraphs}
+%
+% \begin{TemplateInterfaceDescription}{paragraph-breaking}
+%   \TemplateArgument{}{} ^^A Hack
+%   \TemplateSemantics
+%   This object type determines how \TeX{} determines the behaviour when
+%   the paragraph-breaking algorithm is calculating whether to break up a
+%   paragraph.  Thus for example an instance of this object type may prevent
+%   breaks within a paragraph, forbid widows or orphans, \emph{etc.}
+% \end{TemplateInterfaceDescription}
+%
+% \begin{TemplateDescription}{paragraph-breaking}{std}
+%   \TemplateKey{badness}{integer}
+%      {^^A
+%        Boundary that if exceeded will cause \TeX{} to report an
+%        underfull vertical box.^^A
+%      }
+%      {1000}
+%   \TemplateKey{broken-penalty}{integer}
+%      {Penalty for page breaking after a hyphenated line.}
+%      {100}
+%   \TemplateKey{club-penalty}{integer}
+%      {Penalty for generating a club line when page breaking.}
+%      {150}
+%   \TemplateKey{display-club-penalty}{integer}
+%      {^^A
+%        Penalty for breaking between to leave a club line after display
+%        math.^^A
+%      }
+%      {150}
+%   \TemplateKey{display-widow-penalty}{integer}
+%      {^^A
+%        Penalty for breaking between to leave a widow line before display
+%        math.^^A
+%      }
+%      {150}
+%   \TemplateKey{fuzz}{length}
+%      {Boundary below which overfull vertical boxes are not reported.}
+%      {0.1 pt}
+%   \TemplateKey{interline-penalty}{integer}
+%      {Penalty for breaking between lines in a paragraph.}
+%      {0}
+%   \TemplateKey{pre-display-penalty}{integer}
+%      {Penalty for breaking between immediately before display math material.}
+%      {10 000}
+%   \TemplateKey{post-display-penalty}{integer}
+%      {Penalty for breaking between immediately after display math material.}
+%      {0}
+%   \TemplateKey{widow-penalty}{integer}
+%      {Penalty for generating a widow line when page breaking.}
+%      {150}
+%   \TemplateSemantics
+%   This template provides an interface to the underlying \TeX{} mechanism for
+%   controlling page breaking. The template applies on an ongoing basis to all
+%   paragraphs after the template is used.
+% \end{TemplateDescription}
+%
+% \begin{InstanceDescription}{paragraph-breaking}{std}{std}
+%   \InstanceSemantics
+%   Sets paragraphs such that they can break with widows and orphans
+%   discouraged but not prevented. Breaks are possible after display math
+%   material but no immediately before it.
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{paragraph-breaking}{nobreak}{std}
+%   \InstanceKey{interline-penalty}{10 000}
+%   \InstanceKey{post-display-penalty}{10 000}
+%   \InstanceSemantics
+%   Sets paragraphs such that they cannot be broken at all (as far as is
+%   possible in \TeX{}).
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{paragraph-breaking}{nolone}{std}
+%   \InstanceKey{club-penalty}{10 000}
+%   \InstanceKey{display-widow-penalty}{10 000}
+%   \InstanceKey{widow-penalty}{10 000}
+%   \InstanceSemantics
+%   Sets paragraphs such that they cannot be broken to leave a club or
+%   widow line (as far as is possible in \TeX{}).
+% \end{InstanceDescription}
+%
+% \begin{TemplateDescription}{paragraph-breaking}{single}
+%   \TemplateKey{badness}{integer}
+%      {^^A
+%        Boundary that if exceeded will cause \TeX{} to report an
+%        underfull vertical box.^^A
+%      }
+%      {\meta{none}}
+%   \TemplateKey{broken-penalty}{integer}
+%      {Penalty for page breaking after a hyphenated line.}
+%      {\meta{none}}
+%   \TemplateKey{club-penalty}{integer}
+%      {Penalty for generating a club line when page breaking.}
+%      {\meta{none}}
+%   \TemplateKey{display-club-penalty}{integer}
+%      {^^A
+%        Penalty for breaking between to leave a club line after display
+%        math.^^A
+%      }
+%      {\meta{none}}
+%   \TemplateKey{display-widow-penalty}{integer}
+%      {^^A
+%        Penalty for breaking between to leave a widow line before display
+%        math.^^A
+%      }
+%      {\meta{none}}
+%   \TemplateKey{fuzz}{length}
+%      {Boundary below which overfull vertical boxes are not reported.}
+%      {\meta{none}}
+%   \TemplateKey{interline-penalty}{integer}
+%      {Penalty for breaking between lines in a paragraph.}
+%      {\meta{none}}
+%   \TemplateKey{pre-display-penalty}{integer}
+%      {Penalty for breaking between immediately before display math material.}
+%      {\meta{none}}
+%   \TemplateKey{post-display-penalty}{integer}
+%      {Penalty for breaking between immediately after display math material.}
+%      {\meta{none}}
+%   \TemplateKey{widow-penalty}{integer}
+%      {Penalty for generating a widow line when page breaking.}
+%      {\meta{none}}
+%   \TemplateSemantics
+%   This template provides an interface to the underlying \TeX{} mechanism for
+%   controlling page breaking. The template applies only to the next paragraph,
+%   and can thus be used to achieve effects such as non-breaking paragraphs.
+% \end{TemplateDescription}
+%
+% \begin{InstanceDescription}{paragraph-breaking}{single-std}{single}
+%   \InstanceSemantics
+%   Sets the next paragraph such that it can break with widows and orphans
+%   discouraged but not prevented. Breaks are possible after display math
+%   material but no immediately before it.
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{paragraph-breaking}{single-nobreak}{single}
+%   \InstanceKey{interline-penalty}{10 000}
+%   \InstanceKey{post-display-penalty}{10 000}
+%   \InstanceSemantics
+%   Sets the next paragraph such that it cannot be broken at all (as far as is
+%   possible in \TeX{}).
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{paragraph-breaking}{single-noclub}{single}
+%   \InstanceKey{club-penalty}{10 000}
+%   \InstanceKey{display-club-penalty}{10 000}
+%   \InstanceSemantics
+%   Sets the next paragraph such that it cannot be broken to leave a club
+%   line (as far as is possible in \TeX{}).
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{paragraph-breaking}{single-nolone}{single}
+%   \InstanceKey{club-penalty}{10 000}
+%   \InstanceKey{display-club-penalty}{10 000}
+%   \InstanceKey{display-widow-penalty}{10 000}
+%   \InstanceKey{widow-penalty}{10 000}
+%   \InstanceSemantics
+%   Sets the next paragraph such that it cannot be broken to leave a club or
+%   widow line (as far as is possible in \TeX{}).
+% \end{InstanceDescription}
+%
+% \begin{InstanceDescription}{paragraph-breaking}{single-nowidow}{single}
+%   \InstanceKey{display-widow-penalty}{10 000}
+%   \InstanceKey{widow-penalty}{10 000}
+%   \InstanceSemantics
+%   Sets the next paragraph such that it cannot be broken to leave a
+%   widow line (as far as is possible in \TeX{}).
+% \end{InstanceDescription}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \section{\pkg{xgalley} Implementation}
+%
+% This module provided a template-level interface for the \LaTeX3 galley. As
+% such, the code here is intended for design-level changes which apply to
+% large blocks. The variables provided are therefore used only for supporting
+% the templates, while any documented interfaces are in \pkg{l3galley}.
+%
+%    \begin{macrocode}
+%<*package>
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\ProvidesExplPackage
+  {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
+\RequirePackage{xparse,xtemplate,l3galley}
+%    \end{macrocode}
+%
+% \subsection{Variables}
+%
+% \begin{variable}{\l_galley_tmpa_clist, \l_galley_tmpb_clist}
+%   Scratch space.
+%    \begin{macrocode}
+\clist_new:N \l_galley_tmpa_clist
+\clist_new:N \l_galley_tmpb_clist
+%    \end{macrocode}
+% \end{variable}
+%
+% \subsection{Layer two: internal dimensions}
+%
+% There is a single object type for level two, the \texttt{measure} for
+% the text in the galley. There are no arguments, as the measure is a design
+% concept.
+%    \begin{macrocode}
+\DeclareObjectType { measure } { 0 }
+%    \end{macrocode}
+%
+% There are two templates for galley measures: absolute and relative.
+% Both use the same interface.
+%    \begin{macrocode}
+\DeclareTemplateInterface { measure } { absolute } { 0 }
+  {
+    left-margin  : length = 0 pt ,
+    right-margin : length = 0 pt
+  }
+\DeclareTemplateInterface { measure } { relative } { 0 }
+  {
+    left-margin  : length = 0 pt ,
+    right-margin : length = 0 pt
+  }
+%    \end{macrocode}
+%
+% \begin{variable}{\l_galley_left_margin_dim, \l_galley_right_margin_dim}
+% In the \texttt{absolute} template, the two margin values are relative
+% to the edges of the galley. This means that any existing offset or
+% line-length adjustment are ignored.
+%    \begin{macrocode}
+%<*package>
+\cs_new_eq:NN \l_galley_left_margin_dim \leftmargin
+%</package>
+%<*package>
+\cs_new_eq:NN \l_galley_right_margin_dim \rightmargin
+%</package>
+\DeclareTemplateCode { measure } { absolute } { 0 }
+  {
+    left-margin  = \l_galley_left_margin_dim  ,
+    right-margin = \l_galley_right_margin_dim
+  }
+  {
+    \AssignTemplateKeys
+    \galley_margins_set_absolute:nn \l_galley_left_margin_dim
+      \l_galley_right_margin_dim
+  }
+%    \end{macrocode}
+% On the other hand, the \texttt{relative} template works relative to
+% the current indentation at both sides.
+%    \begin{macrocode}
+\DeclareTemplateCode { measure } { relative } { 0 }
+  {
+    left-margin  = \l_galley_left_margin_dim  ,
+    right-margin = \l_galley_right_margin_dim
+  }
+  {
+    \AssignTemplateKeys
+    \galley_margins_set_relative:nn \l_galley_left_margin_dim
+      \l_galley_right_margin_dim
+  }
+%    \end{macrocode}
+% \end{variable}
+%
+% \subsection{Layer three: paragraph shape}
+%
+% The object type \texttt{parshape} is a somewhat extended interface
+% to the \TeX{} \cs{tex_parshape:D} primitive. As with the \texttt{measure},
+% the \texttt{parshape} template has no arguments as it is essentially a
+% design-oriented concept.
+%    \begin{macrocode}
+\DeclareObjectType { parshape } { 0 }
+%    \end{macrocode}
+%
+% There are two standard templates for paragraph shapes which do
+% something, both with the same interface. The \texttt{hang} template
+% provides one or more standard lines followed by a hanging paragraph,
+% while the \texttt{initial} template cuts out a space at the start of
+% the paragraph.
+%    \begin{macrocode}
+\DeclareTemplateInterface { parshape } { hang } { 0 }
+  {
+    indent       : length  = 0 pt ,
+    on-left-side : boolean = true ,
+    lines        : integer = 1
+  }
+\DeclareTemplateInterface { parshape } { initial } { 0 }
+ {
+    indent       : length  = 0 pt ,
+    on-left-side : boolean = true ,
+    lines        : integer = 2
+  }
+%    \end{macrocode}
+% \begin{variable}{\l_galley_parshape_indent_dim}
+% \begin{variable}{\l_galley_parshape_on_left_bool}
+% \begin{variable}{\l_galley_parshape_lines_int}
+% Both of the templates are implemented as special cases of the more
+% general function defined earlier.
+%    \begin{macrocode}
+\DeclareTemplateCode { parshape } { hang } { 0 }
+  {
+    indent       = \l_galley_parshape_indent_dim   ,
+    on-left-side = \l_galley_parshape_on_left_bool ,
+    lines        = \l_galley_parshape_lines_int
+  }
+  {
+    \AssignTemplateKeys
+    \bool_if:NTF \l_galley_parshape_on_left_bool
+      {
+        \galley_parshape_single_par:nVVN
+          \l_galley_parshape_lines_int
+          \l_galley_parshape_indent_dim
+          \c_zero_dim
+          \c_false_bool
+      }
+      {
+        \galley_parshape_single_par:nVVN
+          \l_galley_parshape_lines_int
+          \c_zero_dim
+          \l_galley_parshape_indent_dim
+          \c_false_bool
+      }
+  }
+\DeclareTemplateCode { parshape } { initial } { 0 }
+  {
+    indent       = \l_galley_parshape_indent_dim   ,
+    on-left-side = \l_galley_parshape_on_left_bool ,
+    lines        = \l_galley_parshape_lines_int
+  }
+  {
+    \AssignTemplateKeys
+    \clist_clear:N \l_galley_tmpa_clist
+    \clist_clear:N \l_galley_tmpb_clist
+    \prg_replicate:nn { \l_galley_parshape_lines_int }
+      {
+        \clist_put_right:Nn \l_galley_tmpa_clist
+          { \l_galley_parshape_indent_dim }
+        \clist_put_right:Nn \l_galley_tmpb_clist
+          { \c_zero_dim }
+      }
+    \bool_if:NTF \l_galley_parshape_on_left_bool
+      {
+        \galley_parshape_single_par:nVVN
+          \c_zero
+          \l_galley_tmpa_clist
+          \l_galley_tmpb_clist
+          \c_true_bool
+      }
+      {
+        \galley_parshape_single_par:nVVN
+          \c_zero
+          \l_galley_tmpb_clist
+          \l_galley_tmpa_clist
+          \c_true_bool
+      }
+  }
+%    \end{macrocode}
+% \end{variable}
+% \end{variable}
+% \end{variable}
+%
+% There is also a \enquote{do nothing} paragraph shape for cases where
+% a template is needed but no action is desirable.
+%    \begin{macrocode}
+\DeclareTemplateInterface { parshape } { std } { 0 } { }
+\DeclareTemplateCode { parshape } { std } { 0 } { } { }
+%    \end{macrocode}
+%
+% \subsection{Layer four: formatting inside the paragraph}
+%
+% The first type of object within a paragraph is the hyphenation. This
+% object needs no arguments.
+%    \begin{macrocode}
+\DeclareObjectType { hyphenation } { 0 }
+%    \end{macrocode}
+%
+% There is only hyphenation template as standard. This provides a
+% semi-flexible interface to the underlying \TeX{} methods. (The detail
+% is therefore hidden within the implementation phase.)
+%    \begin{macrocode}
+\DeclareTemplateInterface { hyphenation } { std } { 0 }
+  {
+    enable            : boolean                        = true ,
+    enable-upper-case : boolean                        = true ,
+    penalty           : choice { low , medium , high } = low
+  }
+%    \end{macrocode}
+% The implementation for hyphenation mainly sets low-level values.
+% The minimum number of characters after a hyphen is set directly,
+% whereas the number before is not. This is so that
+% \cs{tex_lefthyphenmin:D} can also be used to completely prevent
+% hyphenation.
+%    \begin{macrocode}
+\DeclareTemplateCode { hyphenation } { std } { 0 }
+  {
+    enable            = \l_galley_hyphen_enable_bool    ,
+    enable-upper-case = \l_galley_hyphen_uppercase_bool ,
+    penalty           =
+      {
+        low    =
+          {
+            \int_set:Nn \tex_hyphenpenalty:D   { 51 }
+            \int_set:Nn \tex_exhyphenpenalty:D { 51 }
+          } ,
+        medium =
+          {
+            \int_set:Nn \tex_hyphenpenalty:D   { 151 }
+            \int_set:Nn \tex_exhyphenpenalty:D { 151 }
+          } ,
+        high   =
+          {
+            \int_set:Nn \tex_hyphenpenalty:D   { 301 }
+            \int_set:Nn \tex_exhyphenpenalty:D { 301 }
+          } ,
+      }
+  }
+  {
+    \AssignTemplateKeys
+    \int_set:Nn \tex_lefthyphenmin:D
+      {
+        \bool_if:NTF \l_galley_hyphen_enable_bool
+          { \l_galley_hyphen_left_int  } { 63 }
+      }
+    \int_set:Nn \tex_uchyph:D
+      { \bool_if:NTF \l_galley_hyphen_uppercase_bool { 1 } { 0 } }
+  }
+%    \end{macrocode}
+% At this stage, the default hyphenation character should be set and
+% hyphenation should be enabled.
+%    \begin{macrocode}
+%\UseTemplate { hyphenation } { std } { }
+\tex_defaulthyphenchar:D 45 \scan_stop:
+%    \end{macrocode}
+%
+% \begin{variable}{\l_galley_justification_other_tl}
+%   Used for the reset system for justification: using this token list means
+%   that there is no need to remove anything from
+%   \cs{g_galley_restore_running_tl}.
+%    \begin{macrocode}
+\tl_new:N \l_galley_justification_other_tl
+%    \end{macrocode}
+% \end{variable}
+%
+% The second level four object is the justification, which again
+% takes no arguments.
+%    \begin{macrocode}
+\DeclareObjectType { justification } { 0 }
+%    \end{macrocode}
+% There are two templates here with the same interface: the standard one
+% to apply from this point onward, and one which applies only to a single
+% paragraph.
+%    \begin{macrocode}
+\DeclareTemplateInterface { justification } { std } { 0 }
+  {
+    end-skip           : skip    = 0 pt plus 1 fil ,
+    fixed-word-spacing : boolean = false           ,
+    indent-width       : length                    ,
+    left-skip          : skip    = 0 pt            ,
+    right-skip         : skip    = 0 pt            ,
+    start-skip         : skip    = 0 pt            ,
+    stretch-last-line  : boolean = false
+  }
+\DeclareTemplateInterface { justification } { single } { 0 }
+  {
+    end-skip           : skip    = 0 pt plus 1 fil ,
+    fixed-word-spacing : boolean = false           ,
+    indent-width       : length                    ,
+    left-skip          : skip    = 0 pt            ,
+    right-skip         : skip    = 0 pt            ,
+    start-skip         : skip    = 0 pt            ,
+    stretch-last-line  : boolean = false
+  }
+%    \end{macrocode}
+% \begin{variable}{\l_galley_fixed_spacing_bool}
+%   The implementation here is pretty simple as almost everything that
+%   goes on is a simple case of saving the settings, which are then
+%   applied either by \TeX{} itself or the rest of the galley system.
+%    \begin{macrocode}
+\DeclareTemplateCode { justification } { std } { 0 }
+  {
+    end-skip           = \l_galley_par_end_skip          ,
+    fixed-word-spacing = \l_galley_fixed_spacing_bool    ,
+    indent-width       = \l_galley_par_indent_dim        ,
+    left-skip          = \l_galley_line_left_skip        ,
+    right-skip         = \l_galley_line_right_skip       ,
+    start-skip         = \l_galley_par_begin_skip        ,
+    stretch-last-line  = \l_galley_par_stretch_last_bool
+  }
+  {
+    \AssignTemplateKeys
+    \tl_clear:N \l_galley_justification_other_tl
+    \galley_set_interword_spacing:N \l_galley_fixed_spacing_bool
+    \bool_if:NTF \l_galley_par_stretch_last_bool
+      { \int_set_eq:NN \l_galley_last_line_fit_int \c_one_thousand }
+      { \int_zero:N \l_galley_last_line_fit_int }
+    \skip_set:Nn \@rightskip { \l_galley_line_right_skip }
+  }
+%    \end{macrocode}
+% \end{variable}
+% To deal with a single paragraph, the approach used is to save the current
+% settings to the paragraph-reset code, then to assign the template in the
+% same way as for the |std| template.
+%    \begin{macrocode}
+\DeclareTemplateCode { justification } { single } { 0 }
+  {
+    end-skip           = \l_galley_par_end_skip         ,
+    fixed-word-spacing = \l_galley_fixed_spacing_bool   ,
+    indent-width       = \l_galley_par_indent_dim       ,
+    left-skip          = \l_galley_line_left_skip       ,
+    right-skip         = \l_galley_line_right_skip      ,
+    start-skip         = \l_galley_par_begin_skip       ,
+    stretch-last-line  = \l_galley_par_stretch_last_bool
+  }
+  {
+    \tl_put_left:Nx \l_galley_justification_other_tl
+      {
+        \skip_set:Nn \exp_not:N \l_galley_par_end_skip
+          { \skip_use:N \l_galley_par_end_skip }
+        \bool_if:NTF \l_galley_fixed_spacing_bool
+          { \bool_set_true:N  \exp_not:N \l_galley_fixed_spacing_bool }
+          { \bool_set_false:N \exp_not:N \l_galley_fixed_spacing_bool }
+        \galley_set_interword_space:N
+          \exp_not:N \l_galley_fixed_spacing_bool
+        \dim_set:Nn \exp_not:N \l_galley_par_indent_dim
+          { \dim_use:N \l_galley_par_indent_dim  }
+        \skip_set:Nn \l_galley_line_left_skip
+          { \skip_use:N \l_galley_line_left_skip }
+        \skip_set:Nn \exp_not:N \l_galley_line_right_skip
+          { \skip_use:N \l_galley_line_right_skip }
+        \skip_set:Nn \exp_not:N \l_galley_par_start_skip
+          { \skip_use:N \l_galley_par_start_skip }
+        \int_set:Nn \exp_not:N \l_galley_last_line_fit_int
+          { \int_use:N \l_galley_last_line_fit_int }
+        \skip_set:Nn \exp_not:N \@rightskip
+          { \skip_use:N \l_galley_line_right_skip }
+      }
+    \tl_gput_right:Nn \g_galley_restore_running_tl
+      { \l_galley_justification_other_tl }
+    \AssignTemplateKeys
+    \galley_set_interword_spacing:N \l_galley_fixed_spacing_bool
+    \bool_if:NTF \l_galley_par_stretch_last_bool
+      { \int_set_eq:NN \l_galley_last_line_fit_int \c_one_thousand }
+      { \int_zero:N \l_galley_last_line_fit_int }
+    \skip_set:Nn \@rightskip { \l_galley_line_right_skip }
+  }
+%    \end{macrocode}
+% The standard instance for justification is very simple to set up as
+% the default values for the template are set up for exactly this case.
+% The advantage of this scheme is that at a design level altering the
+% indent used for justified paragraphs is very easy to do. As this is
+% the standard template for all \LaTeX3 documents, it is applied here.
+%    \begin{macrocode}
+\DeclareInstance { justification } { justified } { std }
+  { indent-width = 15 pt }
+\UseInstance { justification } { justified }
+%    \end{macrocode}
+% The instance for no indentation at all but with justified text is
+% intended for layouts which leave white space between paragraphs. With
+% no indentation, some space has to be included at the end of each
+% paragraph. This is set up to mirror the indent that has been removed.
+%    \begin{macrocode}
+\DeclareInstance { justification } { noindent } { std }
+  {
+    end-skip     = 15 pt plus 1 fil ,
+    indent-width = 0 pt
+  }
+%    \end{macrocode}
+% The other standard justification schemes are for text which is either
+% centred or ragged. The settings here are taken from the \LaTeXe{}
+% \pkg{ragged2e} package, as they maintain a reasonable appearance by
+% ensuring that \TeX{} will not be too tolerant of very short lines.
+% To keep the design clear here, no default values are relied on even
+% though this would make the instance declarations shorter.
+%    \begin{macrocode}
+\DeclareInstance { justification } { centered } { std }
+  {
+    end-skip           = 0 pt           ,
+    fixed-word-spacing = true           ,
+    indent-width       = 0 pt           ,
+    left-skip          = 0 pt plus 1 em ,
+    right-skip         = 0 pt plus 1 em
+  }
+\DeclareInstance { justification } { ragged-left } { std }
+  {
+    end-skip           = 0 pt            ,
+    fixed-word-spacing = true            ,
+    indent-width       = 0 pt            ,
+    left-skip          = 0 pt plus 2 em  ,
+    right-skip         = 0 pt
+  }
+\DeclareInstance { justification } { ragged-right } { std }
+  {
+    end-skip           = 0 pt plus 1 fil ,
+    fixed-word-spacing = true            ,
+    indent-width       = 0 pt            ,
+    left-skip          = 0 pt            ,
+    right-skip         = 0 pt plus 2 em
+  }
+%    \end{macrocode}
+% The \texttt{centering} instance is used to centre material without
+% hyphenation: this is used for centring arbitrary material rather
+% than text.
+%    \begin{macrocode}
+\DeclareInstance { justification } { centering } { std }
+  {
+    end-skip           = 0 pt            ,
+    fixed-word-spacing = true            ,
+    indent-width       = 0 pt            ,
+    left-skip          = 0 pt plus 1 fil ,
+    right-skip         = 0 pt plus 1 fil
+  }
+%    \end{macrocode}
+%
+% \begin{macro}{\galley_justification_first:, \galley_justification_other:}
+%   A second form of justification template is the case where the first
+%   paragraph is different from all of the others. This is set up by
+%   getting the justification to reset itself after the first paragraph.
+%   The code built into the \texttt{std} version will ensure that any
+%   subsequent template use will over-ride the setting here correctly.
+%    \begin{macrocode}
+\DeclareTemplateInterface { justification } { compound } { 0 }
+  {
+    first-paragraph  : instance { justification } ,
+    other-paragraphs : instance { justification }
+  }
+\DeclareTemplateCode { justification } { compound } { 0 }
+  {
+    first-paragraph  = \galley_justification_first: ,
+    other-paragraphs = \galley_justification_other:
+  }
+  {
+    \AssignTemplateKeys
+    \galley_justification_first:
+    \tl_set:Nn \l_galley_justification_other_tl
+      { \galley_justification_other: }
+    \tl_gput_right:Nn \g_galley_restore_running_tl
+      { \l_galley_justification_other_tl }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% How \TeX{} breaks text into lines is influences by a number of
+% parameters, most of which are not actually likely to change. These
+% work with the \texttt{hyphenation} but are independent of whether
+% any hyphenation is actually active. The math values here could be
+% set up as a separate template, but in practice this seems likely to
+% be overkill.
+%    \begin{macrocode}
+\DeclareObjectType { line-breaking } { 0 }
+%    \end{macrocode}
+% The only template provided for line breaking is a simple interface to
+% \TeX{}'s parameters. There is not really much that can be added to this:
+% after all, the way that penalties work is more or less arbitrary but
+% works well! The default values given here are intended to be sensible
+% for a lot of cases.
+%    \begin{macrocode}
+\DeclareTemplateInterface { line-breaking } { std } { 0 }
+  {
+    badness                : integer = 1000   ,
+    binop-penalty          : integer = 700    ,
+    double-hyphen-demerits : integer = 10 000 ,
+    emergency-stretch      : skip    = 0 pt   ,
+    final-hyphen-demerits  : integer = 5000   ,
+    fuzz                   : length  = 0.1 pt ,
+    line-penalty           : integer = 10     ,
+    mismatch-demerits      : integer = 10 000 ,
+    pretolerance           : integer = 100    ,
+    relation-penalty       : integer = 500    ,
+    tolerance              : integer = 200
+  }
+\DeclareTemplateCode{ line-breaking } { std } { 0 }
+  {
+    badness                = \l_galley_linebreak_badness_int      ,
+    binop-penalty          = \l_galley_binop_penalty_int          ,
+    double-hyphen-demerits = \l_galley_double_hyphen_demerits_int ,
+    emergency-stretch      = \l_galley_emergency_stretch_skip     ,
+    final-hyphen-demerits  = \l_galley_final_hyphen_demerits_int  ,
+    fuzz                   = \l_galley_linebreak_fuzz_dim         ,
+    line-penalty           = \l_galley_linebreak_penalty_int      ,
+    mismatch-demerits      = \l_galley_mismatch_demerits_int      ,
+    pretolerance           = \l_galley_linebreak_pretolerance_int ,
+    relation-penalty       = \l_galley_relation_penalty_int       ,
+    tolerance              = \l_galley_linebreak_tolerance_int
+  }
+  { \AssignTemplateKeys }
+%    \end{macrocode}
+% The default values are set such that they are suitable for good
+% quality typesetting. So the standard template changes nothing at
+% all from the template. This instance should also be applied now,
+% as it will then apply to the entire document unless changed
+% deliberately.
+%    \begin{macrocode}
+\DeclareInstance { line-breaking } { std } { std } { }
+\UseInstance { line-breaking } { std }
+%    \end{macrocode}
+%
+% \subsection{Between paragraphs}
+%
+% \begin{variable}
+%   {
+%     \l_galley_club_penalty_int          ,
+%     \l_galley_display_club_penalty_int  ,
+%     \l_galley_display_widow_penalty_int ,
+%     \l_galley_interline_penalty_int     ,
+%     \l_galley_widow_penalty_int
+%   }
+%   The second object here sets up how \TeX{} acts to break paragraphs at
+%   page boundaries. As with the \texttt{line-breaking} object, there is not
+%   much to do except provide an interface to the \TeX{} internals. The
+%   \texttt{std} template does \emph{not} make the \eTeX{} array nature of
+%   various penalties available.
+%    \begin{macrocode}
+\DeclareObjectType { paragraph-breaking } { 0 }
+\DeclareTemplateInterface { paragraph-breaking } { std } { 0 }
+  {
+    badness               : integer = 1000   ,
+    broken-penalty        : integer = 100    ,
+    club-penalty          : integer = 150    ,
+    display-club-penalty  : integer = 150    ,
+    display-widow-penalty : integer = 150    ,
+    fuzz                  : length  = 0.1 pt ,
+    interline-penalty     : integer = 0      ,
+    post-display-penalty  : integer = 0      ,
+    pre-display-penalty   : integer = 10 000 ,
+    widow-penalty         : integer = 150
+  }
+\DeclareTemplateCode { paragraph-breaking } { std } { 0 }
+  {
+    badness               = \l_galley_parbreak_badness_int      ,
+    broken-penalty        = \l_galley_broken_penalty_int        ,
+    club-penalty          = \l_galley_club_penalty_int          ,
+    display-club-penalty  = \l_galley_display_club_penalty_int  ,
+    display-widow-penalty = \l_galley_display_widow_penalty_int ,
+    fuzz                  = \l_galley_parbreak_fuzz_dim         ,
+    interline-penalty     = \l_galley_interline_penalty_int     ,
+    post-display-penalty  = \l_galley_post_display_penalty_int  ,
+    pre-display-penalty   = \l_galley_pre_display_penalty_int   ,
+    widow-penalty         = \l_galley_widow_penalty_int
+  }
+  {
+    \AssignTemplateKeys
+    \galley_set_club_penalties:V          \l_galley_club_penalty_int
+    \galley_set_display_club_penalties:V  \l_galley_display_club_penalty_int
+    \galley_set_display_widow_penalties:V \l_galley_display_widow_penalty_int
+    \galley_set_interline_penalty:n       \l_galley_interline_penalty_int
+    \galley_set_widow_penalties:V         \l_galley_widow_penalty_int
+  }
+%    \end{macrocode}
+% \end{variable}
+% The standard instance of the \texttt{paragraph-breaking} object simply
+% applies the defaults: this is used.
+%    \begin{macrocode}
+\DeclareInstance { paragraph-breaking } { std } { std } { }
+\UseInstance { paragraph-breaking } { std }
+%    \end{macrocode}
+% Two additional instances are provided: one to prevent any breaks
+% at all, and a second to prevent any widow or club lines.
+%    \begin{macrocode}
+\DeclareInstance { paragraph-breaking } { nobreak } { std }
+  {
+    interline-penalty    = 10 000 ,
+    post-display-penalty = 10 000
+  }
+\DeclareInstance { paragraph-breaking } { nolone } { std }
+  {
+    club-penalty          = 10 000 ,
+    display-club-penalty  = 10 000 ,
+    display-widow-penalty = 10 000 ,
+    widow-penalty         = 10 000
+  }
+%    \end{macrocode}
+% \begin{variable}
+%   {
+%     \l_galley_parbreak_badness_tl        ,
+%     \l_galley_broken_penalty_tl          ,
+%     \l_galley_club_penalties_tl          ,
+%     \l_galley_display_club_penalties_tl  ,
+%     \l_galley_display_widow_penalties_tl ,
+%     \l_galley_parbreak_fuzz_tl           ,
+%     \l_galley_interline_penalty_tl       ,
+%     \l_galley_post_display_penalty_tl    ,
+%     \l_galley_pre_display_penalty_tl     ,
+%     \l_galley_widow_penalties_tl         ,
+%     \c_galley_parbreak_multi_seq         ,
+%     \c_galley_parbreak_single_seq
+%   }
+%   There is also a version of this code which applies only to one
+%   paragraph. This is done by storing the input in token list variables
+%   with no default: only explicit settings will be picked up.
+%    \begin{macrocode}
+\DeclareTemplateInterface { paragraph-breaking } { single } { 0 }
+  {
+    badness               : tokenlist ,
+    broken-penalty        : tokenlist ,
+    club-penalty          : tokenlist ,
+    display-club-penalty  : tokenlist ,
+    display-widow-penalty : tokenlist ,
+    fuzz                  : tokenlist ,
+    interline-penalty     : tokenlist ,
+    post-display-penalty  : tokenlist ,
+    pre-display-penalty   : tokenlist ,
+    widow-penalty         : tokenlist
+  }
+\DeclareTemplateCode { paragraph-breaking } { single } { 0 }
+  {
+    badness               = \l_galley_parbreak_badness_tl        ,
+    broken-penalty        = \l_galley_broken_penalty_tl          ,
+    club-penalty          = \l_galley_club_penalties_tl          ,
+    display-club-penalty  = \l_galley_display_club_penalties_tl  ,
+    display-widow-penalty = \l_galley_display_widow_penalties_tl ,
+    fuzz                  = \l_galley_parbreak_fuzz_tl           ,
+    interline-penalty     = \l_galley_interline_penalty_tl       ,
+    post-display-penalty  = \l_galley_post_display_penalty_tl    ,
+    pre-display-penalty   = \l_galley_pre_display_penalty_tl     ,
+    widow-penalty         = \l_galley_widow_penalties_tl
+  }
+  {
+    \AssignTemplateKeys
+%    \end{macrocode}
+%   The fuzz and interline penalties are handled explicitly as they have
+%   particular requirements.
+%    \begin{macrocode}
+    \tl_if_empty:NF \l_galley_interline_penalty_tl
+      {
+        \tl_gput_right:Nx \g_galley_par_after_hook_tl
+          {
+            \int_set:Nn \exp_not:N \l_galley_interline_penalty_int
+              { \galley_interline_penalty: }
+          }
+        \int_set:Nn \l_galley_interline_penalty_int
+          { \l_galley_interline_penalty_tl }
+      }
+    \tl_if_empty:NF \l_galley_parbreak_fuzz_tl
+      {
+        \tl_gput_right:Nx \g_galley_par_after_hook_tl
+          {
+            \dim_set:Nn \exp_not:N \l_galley_parbreak_fuzz_dim
+              { \dim_use:N \l_galley_parbreak_fuzz_dim }
+          }
+        \dim_set:Nn \l_galley_parbreak_fuzz_dim { \l_galley_parbreak_fuzz_tl }
+      }
+%    \end{macrocode}
+%  For the single integer penalties, a simple check is needed to save the
+%  value.
+%    \begin{macrocode}
+    \seq_map_inline:Nn \c_galley_parbreak_single_seq
+      {
+        \tl_if_empty:cF { l_galley_ ##1 _tl }
+          {
+            \tl_gput_right:Nx \g_galley_par_after_hook_tl
+              {
+                \int_set:Nn \exp_not:c { l_galley_ ##1 _int }
+                  { \int_use:c { l_galley_ ##1 _int } }
+              }
+            \int_set:cn { l_galley_ ##1 _int }
+              { \tl_use:c { l_galley_ ##1 _tl } }
+          }
+      }
+%    \end{macrocode}
+%   A bit more complex for the array penalties. Although the interface here
+%   does not expose the arrays, it is necessary to correctly save them.
+%    \begin{macrocode}
+    \seq_map_inline:Nn \c_galley_parbreak_multi_seq
+      {
+        \tl_if_empty:cF { l_galley_ ##1 _tl }
+          {
+            \use:c { galley_save_ ##1 :N } \l_galley_tmpa_clist
+            \tl_gput_right:Nx \g_galley_par_after_hook_tl
+              {
+                \exp_not:c { galley_set_ ##1 :n }
+                  { \exp_not:o \l_galley_tmpa_clist }
+              }
+            \use:c { galley_set_ ##1 :v } { l_galley_ ##1 _tl }
+          }
+      }
+  }
+\seq_new:N \c_galley_parbreak_multi_seq
+\seq_gput_right:Nn \c_galley_parbreak_multi_seq { club_penalties }
+\seq_gput_right:Nn \c_galley_parbreak_multi_seq { display_club_penalties }
+\seq_gput_right:Nn \c_galley_parbreak_multi_seq { display_widow_penalties }
+\seq_gput_right:Nn \c_galley_parbreak_multi_seq { widow_penalties }
+\seq_new:N \c_galley_parbreak_single_seq
+\seq_gput_right:Nn \c_galley_parbreak_single_seq { parbreak_badness }
+\seq_gput_right:Nn \c_galley_parbreak_single_seq { broken_penalty }
+\seq_gput_right:Nn \c_galley_parbreak_single_seq { post_display_penalty }
+\seq_gput_right:Nn \c_galley_parbreak_single_seq { pre_display_penalty }
+%    \end{macrocode}
+% \end{variable}
+%    \begin{macrocode}
+\DeclareInstance { paragraph-breaking } { single-std } { single } { }
+\DeclareInstance { paragraph-breaking } { single-nobreak } { single }
+  {
+    interline-penalty    = 10 000 ,
+    post-display-penalty = 10 000
+  }
+\DeclareInstance { paragraph-breaking } { single-noclub } { single }
+  {
+    club-penalty         = 10 000 ,
+    display-club-penalty = 10 000 
+  }
+\DeclareInstance { paragraph-breaking } { single-nolone } { single }
+  {
+    club-penalty          = 10 000 ,
+    display-club-penalty  = 10 000 ,
+    display-widow-penalty = 10 000 ,
+    widow-penalty         = 10 000
+  }
+\DeclareInstance { paragraph-breaking } { single-nowidow } { single }
+  {
+    display-widow-penalty = 10 000 ,
+    widow-penalty         = 10 000
+  }
+%    \end{macrocode}
+%
+% \subsection{Templates for display material}
+%
+% To allow special handling of display-like material, templates are
+% needed at the beginning and end of the block which set up any special
+% space or breaks. These need to be optional, and so are stored as token
+% lists: rather than \enquote{magic} values, empty lists indicate that
+% standard settings are to be used. To ensure that the error checking
+% needed takes place early, each token list is re-set with the
+% appropriate evaluation.
+%    \begin{macrocode}
+\DeclareObjectType { display-begin } { 0 }
+\DeclareObjectType { display-end }   { 0 }
+\DeclareTemplateInterface { display-begin } { std } { 0 }
+  {
+    par-penalty : tokenlist ,
+    par-space   : tokenlist ,
+    penalty     : tokenlist ,
+    space       : tokenlist
+  }
+\DeclareTemplateInterface { display-end } { std } { 0 }
+  {
+    par-penalty : tokenlist ,
+    par-space   : tokenlist ,
+    penalty     : tokenlist ,
+    space       : tokenlist
+  }
+\DeclareTemplateCode { display-begin } { std } { 0 }
+  {
+    par-penalty = \l_galley_display_begin_par_vpenalty_tl ,
+    par-space   = \l_galley_display_begin_par_vspace_tl   ,
+    penalty     = \l_galley_display_begin_vpenalty_tl     ,
+    space       = \l_galley_display_begin_vspace_tl
+  }
+  {
+   \AssignTemplateKeys
+    \tl_if_empty:NF \l_galley_display_begin_par_vpenalty_tl
+      {
+        \tl_set:Nx \l_galley_display_begin_par_vpenalty_tl
+          { \int_eval:n { \l_galley_display_begin_par_vpenalty_tl } }
+      }
+    \tl_if_empty:NF \l_galley_display_begin_par_vspace_tl
+      {
+        \tl_set:Nx \l_galley_display_begin_par_vspace_tl
+          { \skip_eval:n { \l_galley_display_begin_par_vspace_tl } }
+      }
+    \tl_if_empty:NF \l_galley_display_begin_vpenalty_tl
+      {
+        \tl_set:Nx \l_galley_display_begin_vpenalty_tl
+          { \int_eval:n { \l_galley_display_begin_vpenalty_tl } }
+      }
+    \tl_if_empty:NF \l_galley_display_begin_vspace_tl
+      {
+        \tl_set:Nx \l_galley_display_begin_vspace_tl
+          { \skip_eval:n { \l_galley_display_begin_vspace_tl } }
+      }
+  }
+\DeclareTemplateCode { display-end } { std } { 0 }
+  {
+    par-penalty = \l_galley_display_end_par_vpenalty_tl ,
+    par-space   = \l_galley_display_end_par_vspace_tl   ,
+    penalty     = \l_galley_display_end_vpenalty_tl     ,
+    space       = \l_galley_display_end_vspace_tl
+  }
+  {
+    \AssignTemplateKeys
+    \tl_if_empty:NF \l_galley_display_end_par_vpenalty_tl
+      {
+        \tl_set:Nx \l_galley_display_end_par_vpenalty_tl
+          { \int_eval:n { \l_galley_display_end_par_vpenalty_tl } }
+      }
+    \tl_if_empty:NF \l_galley_display_end_par_vspace_tl
+      {
+        \tl_set:Nx \l_galley_display_end_par_vspace_tl
+          { \skip_eval:n { \l_galley_display_end_par_vspace_tl } }
+      }
+    \tl_if_empty:NF \l_galley_display_end_vpenalty_tl
+      {
+        \tl_set:Nx \l_galley_display_end_vpenalty_tl
+          { \int_eval:n { \l_galley_display_end_vpenalty_tl } }
+      }
+    \tl_if_empty:NF \l_galley_display_end_vspace_tl
+      {
+        \tl_set:Nx \l_galley_display_end_vspace_tl
+          { \skip_eval:n { \l_galley_display_end_vspace_tl } }
+      }
+  }
+%    \end{macrocode}
+%
+% \subsection{\LaTeXe{} functions}
+%
+% \begin{macro}{\nobreak}
+% \begin{macro}{\noindent}
+% \begin{macro}{\vspace}
+% In package mode, some of \LaTeXe{}'s functions are re-implemented using
+% the galley system. Not all of the optional arguments currently work!
+%    \begin{macrocode}
+\RenewDocumentCommand \nobreak { }
+  { \bool_gset_true:N \g_galley_no_break_next_bool }
+\RenewDocumentCommand \noindent { }
+  { \bool_gset_false:N \g_galley_omit_next_indent_bool }
+\RenewDocumentCommand \vspace { s m } { \galley_set_vspace_user:n {#2} }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%    \begin{macrocode}
+%</package>
+%    \end{macrocode}
+%
+% \end{implementation}
+%
+% \PrintIndex