% \iffalse
%%
%% $Header: /usr3/users/latex3/design/consolidation/CURRENT/RCS/xhj.dtx,v 1.8 2000/01/14 15:24:24 latex3 Exp $
%%
%% (C) Copyright 1999-2000 Frank Mittelbach
%% All rights reserved.
%%
%% Not for general distribution. In its present form it is not allowed
%% to put this package onto CD or an archive without consulting the
%% the authors.
%%
%% This module only works in conjunction with the galley2 module.
%% 
%<*dtx>
          \ProvidesFile{xhj.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{xhj}
%<driver>\ProvidesFile{xhj.drv}
% \fi
%         \ProvidesFile{xhj.dtx}
          [2000/01/14 v0.3c hyphenation & justification]
%
% \iffalse
%<*driver>
 \documentclass{ltxdoc}
%\usepackage{xlists-samples} 
%\makeatletter \let\GAL@typeout\@gobble \let\GAL@show@datastructure\@gobble
% \usepackage{ldcdoc}

\newcommand\LaTeXplus{\LaTeXe$*$}

\newcommand\DelayEvaluation{\texttt{\textbackslash DelayEvalution} 
                            \ignorespaces}
\newcommand\fontwordspace{\texttt{\textbackslash fontwordspace}}
\newcommand\fontextraspace{\texttt{\textbackslash fontextraspace}}


% next three definitions are big hacks to run the file
% without the above packages
%
\newcommand\NoValue{\texttt{\textbackslash NoValue}}

\makeatletter
\newenvironment{TemplateInterfaceDescription}[1]
  {\subsection{The Template Type `#1'}%
   \begingroup
   \@beginparpenalty\@M
   \description
   \def\TemplateArgument##1##2{\item[Arg: ##1]##2\par}%
   \def\TemplateSemantics{\enddescription\endgroup
       \subsubsection*{Semantics:}}%
  }
  {\par\bigskip}

\newenvironment{TemplateDescription}[2]
  {\subsection{The Template `#2' (type #1)}%
   \subsubsection*{Attributes:}%
   \begingroup
   \@beginparpenalty\@M
   \description
   \def\TemplateKey##1##2##3##4{\item[##1 (##2)]##3%
     \ifx\TemplateKey##4\TemplateKey\else
%         \hskip0ptplus3em\penalty-500\hskip 0pt plus 1filll Default:~##4%
         \hfill\penalty500\hbox{}\hfill Default:~##4%
         \nobreak\hskip-\parfillskip\hskip0pt\relax
     \fi
     \par}%
   \def\TemplateSemantics{\enddescription\endgroup
       \subsubsection*{Semantics \& Comments:}}%
  }
  {\par\bigskip}

\newenvironment{InstanceDescription}[4][xxxxxxxxxxxxxxx]
  {\subsubsection{The Instance `#3' (template #2/#4)}%
   \subsubsection*{Attribute values:}%
   \begingroup
   \@beginparpenalty\@M
   \def\InstanceKey##1##2{\>\textbf{##1}\>##2\\}%
   \def\InstanceSemantics{\endtabbing\endgroup
       \vskip-30pt\vskip0pt
       \subsubsection*{Layout description \& Comments:}}%
   \tabbing
   xxxx\=#1\=\kill
  }
  {\par\bigskip}

\makeatother

\newcommand\key[1]{\textbf{#1}}

 \begin{document}
 \DocInput{xhj.dtx}
 \end{document}
%</driver>
% \fi
%
% \CheckSum{298}
%
% \newcommand\subsubsubsection{\paragraph}
%
% \GetFileInfo{xhj.dtx}
%
% \title{The \textsf{h\&j} 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 for interfacing with the
%   galley mechanism as set up by the module
%   \texttt{galley2}. These templates are intended for class
%   designers and are mostly usable out of the box (i.e., this is one
%   of the modules where providing a suitable number of default
%   instances is probably sensible since they would cover 98\% of all
%   usage. In contrast the \texttt{galley2} module contains only
%   low-level interfaces for 
%   direct manipulation of the galley mechanism which are geared
%   towards package writers having special needs which are not
%   fulfilled by the templates in this module.
% \end{abstract}
% 
%
%
%
% \section{Introduction}
%
% In \LaTeXplus{} terminology a galley is a rectangular area which
% receives text and other material filling it from
% top.\footnote{The predominant direction depends on the writing
% system and with extensions to \TeX{} such as Omega there are
% possibilities to define galleys with a different filling direction.}
% The vertically extend of a galley is normally not restricted 
% (there are exceptions); 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 behavior.
%
% Examples for galleys are `the main galley', where the continuous
% document data gets formatted into  and from which columns and pages are
% constructed, and  `vbox galley's, such as the body of  a minipage
% environment or the body of a float (in \LaTeXe only---the new float
% mechanism for \LaTeXplus{} will employ horizontally oriented float
% bodies). The latter galleys are typically not being split after
% formatting though there can be exceptions.
%
% Low-level interfaces for setting up such galleys and the way objects
% are formatted into them are provided by the module
% \texttt{galley2}.
%
% \subsection{Formatting layers}
%
% The present module is mainly concerned with the
% formatting of text in such galleys.
% The galley mechanism provides interfaces at four different layers
% some of which can be manipulated through the templates provided by
% this module.
%
% \subsubsection{Outer galley dimensions}
%
% In the bottom layer the external dimensions of a galley are
% fixed. In most cases only the horizontal dimension is defined while
% the vertical dimension (i.e., the filling direction) remains
% unspecified. These dimensions are fixed when initiating a new galley,
% using low-level functions, and are not modifiable. The horizontal
% overall width of the current galley is available for inspection in
% the register |\hsize|.\footnote{This is going to change once there
% is a final concept for handling this part of the interface, e.g.,
% the relation of \texttt{\textbackslash hsize},
% \texttt{\textbackslash columnwidth}, and \texttt{\textbackslash
% textwidth}. The latter are actually parameters of the text-page and
% should probably not be handled as it is done in \LaTeXe{}, i.e., by
% also using \texttt{\textbackslash columnwidth} as a measure for the
% current galley width. Perhaps one should introduce a
% \texttt{\textbackslash galleywidth} parameter instead of using
% \texttt{\textbackslash hsize}.}
% There are no templates that only set variable of this layer, though
% higher level 
% templates (e.g., a template for providing minipage functionality)
% will of course address this part of the galley mechanism.
%
%
% \subsubsection{Inner galley dimensions}
%
% The second layer defines the inner horizontal galley dimensions of
% the galley, i.e., the measure used for paragraph text and its
% positioning within the galley. The current measure of the galley is
% available for inspection in the register |\linewidth| and the
% indentation from the left outer margin is available in the register
% |\@totalleftmargin|.\footnote{The two registers are already
% available in \LaTeXe{} and their names have been  retained to make
% it easier to use a mixture of old and new code. However at some
% point the interface should be made more uniform by either providing
% two user accessible or two user inaccessible names.}
%
% This layer can (and should) be manipulated by higher-level templates
% through template instances of the type `measure'. These templates
% make long-term changes.
%
% 
%
%
% \subsubsection{Paragraph shapes}
%
% 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.
%
% For this layer we are restricted by the mechanisms offered by
% \TeX{}. This means that it is possible to define particular
% paragraph shapes such as cutouts only from the top of a paragraph
% but not relative to its bottom.
%
% This layer can (and should) be manipulated by higher-level templates
% through template instances of the type `pshape'. Templates in this
% layer typically make short-term changes only (i.e. applicable only
% to the upcoming paragraph), however templates for long-term changes
% are also permissable though none are provided right now.
%
% A future implementation of the \texttt{galley2} module is probably
% going to support pshapes spanning several paragraphs, however at the
% moment pshapes apply per paragraph only.
%
%
% \subsubsection{Text formatting within the paragraph shape}
%
% The forth (and currently final) layer deals with  the paragraph
% formatting aspects such as hyphenation and justification (h\&j which
% gave the current module its name).
%
% There are several template types in this layer: `hj' is a type that
% sets all aspects of h\&j in a single template whereas the types
% `justification', `linebreak', and `hyphenation' deal with individual
% aspects.
%
% \subsection{Open issues}
%
% Several but right now most of them are discussed when describing the
% interfaces in more details below.
%
% \begin{itemize}
% \item
%   The model attempts a proper separation between paragraph shapes
%   (layer three) and justification (part of layer four). However, due
%   to the way \TeX{} works certain paragraph shapes can only be
%   accomplished by using the parameters that are normally reserved
%   for justification (an example would be the famous shape used by
%   |\@dottedcontentsline|, i.e., a rectangular shape with the first
%   line sticking out to the left and the last line sticking out to
%   the right). How to integrate such shapes on layer three needs some
%   more thought.
% \item
%   What does the argument to the `measure' type really signal? Always
%   a relative value (to current |\@totalleftmargin|), always an
%   absolute value, or a value depending on what the template makes
%   out of it? Perhaps this is not that important as one can't expect
%   any such document supplied value be correct for different
%   designs---or is this the wrong idea? At the moment I make
%   it always be a relative change to |\@totalleftmargin| independent
%   of the type of template being used.
% \end{itemize}
%
%
% \section{Interfaces}
%
% \begin{TemplateInterfaceDescription}{measure}
%
%   \TemplateArgument{1}
%       {Indentation of the left margin overwriting the default change
%        or \NoValue{} in which case the value from the template
%        is used. If provide the value is \emph{always} interpreted as
%        being relative to the current indentation in the galley.}
%
%   \TemplateSemantics
%     This template type defines the basic measure of the galley,
%     i.e., the width of the lines (|\linewidth|) and  their
%     indentation from the left (|\@totalleftmargin|).
%
%     Each template of this type has to set the above parameters
%     locally to their correct value.\footnote{That part of the
%     implementation in \texttt{galley2.dtx} probably needs changing.}
%
%     The templates can (and in most cases do) refer to an
%     external\footnote{Again that is something which may not survive
%     for long. It might very well be the case that all these
%     parameters need to be added to the main galley data structures.}
%     parameter holding the overall nominal width of the current
%     galley (|\hsize|). However it is perfectly admissible that the
%     template parameters are set in a way that |\@totalleftmargin| +
%     |\linewidth| exceeds this nominal width (the galley mechanism
%     provides low-level calls that allow for this without producing
%     an error. This way paragraphs in a galley may stick out on
%     either side if desired.
%
%     One could think of making also the right margin being user
%     over-writable or providing something like a boolean to modify the
%     meaning of the template argument---suggestions/applications
%     needed.\footnote{Think!}
%
%     Templates of this type make long-term changes, i.e., their
%     settings remain until the next occurence of an instance of this
%     type or until the galley ends or its previous settings are
%     restored. As remarked in the introduction
%     there is a need for saving and restoring the settings of this
%     particular part of the mechanism individually.
%
% \end{TemplateInterfaceDescription}
%
%
% \begin{TemplateDescription}{measure}{relative}
%
%   \TemplateKey{leftmargin}{l}
%      {Additional indentation on the left for all lines}
%      {none}
%
%   \TemplateKey{rightmargin}{l}
%      {Additional indentation on the right for all lines}
%      {none}
%
%   \TemplateSemantics
%    This is the main template needed for defining vertically oriented
%    lists and the like (at least if they are supposed to allow for
%    nesting).
%
% \end{TemplateDescription}
%
%
%
% \begin{TemplateDescription}{measure}{absolute}
%
%   \TemplateKey{leftmargin}{l}
%      {Indentation on the left for all lines}
%      {none}
%
%   \TemplateKey{rightmargin}{l}
%      {Indentation on the right for all lines measured from the
%      nominal width of the galley (i.e., \texttt{\textbackslash
%      hsize})}
%      {none}
%
%   \TemplateSemantics
%     This template can be used in cases where one wishes to ignore
%     any already existing indentations. Whether or not this has real
%     applications remains to be seen.
%
% \end{TemplateDescription}
%
%
%
%
%
% \begin{TemplateInterfaceDescription}{pshape}
%
%   \TemplateArgument{none}
%       {---}
%
%   \TemplateSemantics
%    Templates of this type define the shape of the paragraph within
%    the given measure of the galley, e.g., whether it has some
%    special form such as a cutout one or the other side.
%
%    Typically they define a shape only for the next paragraph,
%    however templates that provide long term changes are also allowed.
%
%    Since such special forms often require that all lines of a
%    paragraph are kept together on a page these templates typically
%    also define whether or not pages breaks within a paragraph are
%    allowed.
%
%    An interesting question is whether or not such templates should
%    set (or inhibit) paragraph indentations via a template key. After
%    all with cutouts on the top left such indentations are usually
%    not desired.\footnote{Right now only justification templates set
%    indentation but perhaps they should not, or both should, or what?}
%
% \end{TemplateInterfaceDescription}
%
%
%
% \begin{TemplateDescription}{pshape}{cutout}
%
%   \TemplateKey{no-page-break-boolean}{s}
%      {If true the upcoming paragraph will not be broken across a
%       page. If false the breakability of the upcoming paragraph
%       depends on other elements in the galley, i.e., it might still
%       be forbidden to break.}
%      {false}
%
%   \TemplateKey{left-side-boolean}{s}
%      {If true, the cutout will appear on the left otherwise it will
%       appear on the right.}
%      {true}
%
%   \TemplateKey{normal-lines-num}{c}
%      {Number of lines before the cutoff starts.}
%      {0}
%
%   \TemplateKey{parshape-list}{f0}
%      {Comma separated list of dimensions denoting the horizontal
%       size of the cutout for successive lines. If the paragraph
%       contains more lines than the sum of \key{normal-lines-num} and
%       the number of elements in this list then the remaining lines
%       are all normal lines (i.e., cutout width 0pt) again.}
%      {none}
%
%   \TemplateSemantics
%     This template is used to define a fixed cutout on one or the
%     other side of a paragraph. It applies to the next paragraph
%     only.
%
%     The \key{normal-lines-num} is for convenience
%     only. Alternatively one could prepend a suitable number of
%     `\texttt{0pt,}'s to \key{parshape-list}.
%
% \end{TemplateDescription}
%
%
% \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-num}{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}
%
%
% \begin{InstanceDescription}[\textbf{no-page-break-boolean}xx]
%       {pshape}{ltriangle}{cutout}
%
%   \InstanceKey{no-page-break-boolean}{true}
%
%   \InstanceKey{left-side-boolean}{true}
%
%   \InstanceKey{normal-lines-num}{0}
%
%   \InstanceKey{parshape-list}{60pt,40pt,20pt}
%
%   \InstanceSemantics
%    This instance will produce a triangle cutout on the left upper
%    corner of a paragraph. Could, for example, used together with an
%    unusual heading layout~\ldots
%
% \end{InstanceDescription}
%
%
% \begin{InstanceDescription}[\textbf{no-page-break-boolean}xx]
%       {pshape}{rectangle}{cutout}
%
%   \InstanceKey{no-page-break-boolean}{false}
%
%   \InstanceKey{left-side-boolean}{true}
%
%   \InstanceKey{normal-lines-num}{0}
%
%   \InstanceKey{parshape-list}{}
%
%   \InstanceSemantics
%    This instance can be used when a pshape is required but one just
%    wants a standard regular paragraph area.\footnote{Using the cutoff
%    template for this is overkill; at some point in the future this
%    instance should be reimplemented.}
%
% \end{InstanceDescription}
%
%
%
%
% \begin{TemplateInterfaceDescription}{justification}
%
%   \TemplateArgument{none}
%       {---}
%
%   \TemplateSemantics
%     Templates of this type define how a paragraph text is formatted
%     within the boundaries of a general paragraph shape (as defined
%     through a measure (and perhaps additionally a pshape)
%     template). More exactly they define whether or
%     not the text should be justified at both sides or only at one
%     side and in the latter case how much raggedness is desired,
%     etc. See the instance examples for more details.
%
%     The \key{linefillskip} in the templates below is worth
%     mentioning. It defines a stretchable space that is used by
%     commands that end a line prematurely in the middle of a
%     paragraph, e.g., |\\| or |\newline|. In most cases what is
%     needed is to fill the line with white space in exactly the same
%     way as \TeX's |\parfillskip| parameter works (which is also the
%     reason for the chosen default). However, for special instances
%     this is not appropriate. Important is that any template of this
%     type provides this key or rather provides a mechanism to
%     correctly feeds the underlying data structure.
%
%     Originally there have been different template types for setting
%     the paragraph specs for all following paragraphs and for only
%     the next one but this was combined into a single type. Whether
%     or not this is the right approach remains to be seen.
%
% \end{TemplateInterfaceDescription}
%
%
% \begin{TemplateDescription}{justification}{std}
%
%   \TemplateKey{startskip}{l}
%      {Stretchable space added to the left of the first line in a
%       paragraph (in addition to \key{leftskip}).}
%      {0pt}
%
%   \TemplateKey{leftskip}{l}
%      {Stretchable space added to the left of every line in a
%       paragraph.}
%      {\texttt{\textbackslash leftskip}}
%
%   \TemplateKey{rightskip}{l}
%      {Stretchable space added to the right of every line in a
%       paragraph.}
%      {\texttt{\textbackslash rightskip}}
%
%   \TemplateKey{parfillskip}{l}
%      {Stretchable space added to the right of the last line in a
%       paragraph (in addition to \key{rightskip}).}
%      {\texttt{\textbackslash parfillskip}}
%
%   \TemplateKey{spaceskip}{l}
%      {Stretchable space to use between words if non-zero. Otherwise
%      size for space between words is taken from the current font
%      metrics.}
%      {\texttt{\textbackslash spaceskip}}
%
%   \TemplateKey{xspaceskip}{l}
%      {Extra space to use after periods etc.~(in certain situations)}
%      {\texttt{\textbackslash xspaceskip}}
%
%   \TemplateKey{linefillskip}{l}
%      {Space to add at the point where some command requests a
%      ``carriage-return line-feed'' in the middle of a paragraph,
%      e.g., the \LaTeX{} command \texttt{\textbackslash newline}.}
%      {value of \key{parfillskip}}
%
%   \TemplateKey{parindent}{l}
%      {Non-stretchable space to be added at the beginning of a
%      paragraph.}
%      {\texttt{\textbackslash parindent}}
%
%   \TemplateSemantics
%
%     This template sets the paragraph justification for all following
%     paragraph (within the normal scope, i.e., until the end of the
%     galley or a new specification).
%
%     The key names for this template are derived from the original
%     \TeX{} primitives whenever applicable. Perhaps this is a bad
%     idea as \key{startskip} and \key{parfillskip} do not go well
%     together.
%
%     The defaults for most keys are actually the command names of the
%     original \TeX{} primitives. The intention is that something like
%     \key{parindent} could be externally provided by setting
%     |\parindent| for all instances which do not explicitly set it to
%     some value (e.g., to 0pt in instances where paragraph
%     indentation is not really appropriate). Whether this is a good
%     idea remains to be seen, this probably need some radically
%     different default concept.
%
% \end{TemplateDescription}
%
%
%
%
% \begin{InstanceDescription}{justification}{default}{std}
%
%   \InstanceKey{leftskip}{0pt}
%
%   \InstanceKey{rightskip}{0pt}
%
%   \InstanceKey{parfillskip}{0pt plus 1fil}
%
%   \InstanceSemantics
%
%   This instance is slightly special as it is internally called
%   whenever a new galley is instantiated, e.g., in a minipage. Thus
%   it must be defined by class. The setting above is the same as for
%   the adjust instance, but of course a class might wish to change
%   this, e.g., if the desired layout requires ragged right setting by
%   default.
%
% \end{InstanceDescription}
%
%
%
%
%
%
% \begin{InstanceDescription}{justification}{adjust}{std}
%
%   \InstanceKey{leftskip}{0pt}
%
%   \InstanceKey{rightskip}{0pt}
%
%   \InstanceKey{parfillskip}{0pt plus 1fil}
%
%   \InstanceSemantics
%
%     This instance provides the standard justified paragraph setting,
%     i.e., every line is justified at both sides and the final line
%     is set flush left. Paragraph indentation is not set, i.e. will
%     be whatever the value of |\parindent| is.
%
% \end{InstanceDescription}
%
%
%
%
%
% \begin{InstanceDescription}{justification}{adjust2}{std}
%
%   \InstanceKey{leftskip}{0pt}
%
%   \InstanceKey{rightskip}{0pt}
%
%   \InstanceKey{parfillskip}{20pt plus 1fil}
%
%   \InstanceSemantics
%
%     This is a variation of the previous instance: the difference is
%     that the last line of a paragraph can never be completely
%     filled. In some sense this defines a paragraph indent at the
%     end.
%
%     Further variations are possible, e.g., one can ensure that the
%     last line always contains at least a certain amount of space.
%
% \end{InstanceDescription}
%
%
%
%
%
% \begin{InstanceDescription}{justification}{center}{std}
%
%   \InstanceKey{parindent}{0pt}
%
%   \InstanceKey{leftskip}{0pt}
%
%   \InstanceKey{rightskip}{0pt}
%
%   \InstanceKey{parfillskip}{0pt}
%
%   \InstanceSemantics
%
%     This instance is an example of a layout where the paragraph
%     indent is explicitly set to zero to ensure that all lines are
%     properly centered. Of course even with centered lines somebody
%     could think of having a paragraph indentation: if so define a
%     variation of the this instance.
%
% \end{InstanceDescription}
%
%
%
%
% \begin{InstanceDescription}{justification}{centermiddle}{std}
%
%   \InstanceKey{parindent}{0pt}
%
%   \InstanceKey{startskip}{-36pt plus -1fill}
%
%   \InstanceKey{leftskip}{36pt plus 1fill}
%
%   \InstanceKey{rightskip}{36pt plus 1fill}
%
%   \InstanceKey{parfillskip}{-36pt plus -1fill}
%
%   \InstanceSemantics
%
%     A specialized instance that sets the first line of the paragraph
%     flush left, the last line flush right and the intermediate lines
%     centered with at least one centimeter space at each
%     side. Possible application could be two or three line headings.
%
% \end{InstanceDescription}
%
%
%
%
%
% \begin{InstanceDescription}{justification}{raggedright}{std}
%
%   \InstanceKey{startskip}{0pt}
%
%   \InstanceKey{leftskip}{0pt}
%
%   \InstanceKey{rightskip}{\DelayEvaluation 0pt plus 2em}
%
%   \InstanceKey{parfillskip}{0pt plus 1fil}
%
%   \InstanceKey{spaceskip}{\DelayEvaluation \fontwordspace}
%
%   \InstanceKey{xspaceskip}{\DelayEvaluation 
%                            \fontwordspace + \fontextraspace}
%
%   \InstanceSemantics
%
%    This interesting instance defines a ragged right setting which
%    allows for hyphenation in case the raggedness would otherwise be
%    too extreme (2em in the current font are considered okay anything
%    in addition will start making the line bad as far as \TeX's
%    paragraph algorithm is concerned so \TeX{} will consider
%    hyphenation in such cases.
%
%    An unjustified setting should always contain identical word
%    spaces. Since we restrict the stretchability at the right  end (it is
%    of the same strength as the default word  space stretchability), we
%    have to ensure that the word spaces to not stretch or shrink at
%    all. This is achieved by forcing the \key{spaceskip} to the
%    normal font word space (without any stretch).
%
% \end{InstanceDescription}
%
%
%
%
%
%
% \begin{InstanceDescription}{justification}{flushleft}{std}
%
%   \InstanceKey{startskip}{0pt}
%
%   \InstanceKey{leftskip}{0pt}
%
%   \InstanceKey{rightskip}{0pt plus 1fill}
%
%   \InstanceKey{parfillskip}{0pt plus 1fill}
%
%   \InstanceSemantics
%
%    In contrast to the previous instance, this instance allows for
%    arbitrary short lines, i.e., a paragraph set using this instance
%    will never get hyphenated unless it contains words longer than
%    the line measure.
%
%    As all the stretchable space will appear at the right margin
%    there in no point in artifically modify the word spaces as they
%    will be set at their natural size anyway.
%
% \end{InstanceDescription}
%
%
%
%
%
% \begin{InstanceDescription}{justification}{raggedleft}{std}
%
%   \InstanceKey{startskip}{0pt}
%
%   \InstanceKey{leftskip}{\DelayEvaluation 0pt plus 2em}
%
%   \InstanceKey{rightskip}{0pt}
%
%   \InstanceKey{parfillskip}{0pt}
%
%   \InstanceKey{spaceskip}{\DelayEvaluation \fontwordspace}
%
%   \InstanceKey{xspaceskip}{\DelayEvaluation 
%                            \fontwordspace + \fontextraspace}
%
%   \InstanceSemantics
%
%     This instance is the raggedleft counter part to the raggedright
%     instance above.
%
% \end{InstanceDescription}
%
%
%
%
%
% \begin{InstanceDescription}{justification}{flushright}{std}
%
%   \InstanceKey{startskip}{0pt}
%
%   \InstanceKey{leftskip}{0pt plus 1fill}
%
%   \InstanceKey{rightskip}{0pt}
%
%   \InstanceKey{parfillskip}{0pt}
%
%   \InstanceSemantics
%
%     And here is the variation which is not using hyphenation unless
%     there is absolutely no other alternative.
%
% \end{InstanceDescription}
%
%
%
% \begin{TemplateDescription}{justification}{single}
%
%   \TemplateKey{startskip}{l}
%      {Stretchable space added to the left of the first line in a
%       paragraph (in addition to \key{leftskip}).}
%      {0pt}
%
%   \TemplateKey{leftskip}{l}
%      {Stretchable space added to the left of every line in a
%       paragraph.}
%      {\texttt{\textbackslash leftskip}}
%
%   \TemplateKey{rightskip}{l}
%      {Stretchable space added to the right of every line in a
%       paragraph.}
%      {\texttt{\textbackslash rightskip}}
%
%   \TemplateKey{parfillskip}{l}
%      {Stretchable space added to the right of the last line in a
%       paragraph (in addition to \key{rightskip}).}
%      {\texttt{\textbackslash parfillskip}}
%
%   \TemplateKey{spaceskip}{l}
%      {Stretchable space to use between words if non-zero. Otherwise
%      size for space between words is taken from the current font
%      metrics.}
%      {\texttt{\textbackslash spaceskip}}
%
%   \TemplateKey{xspaceskip}{l}
%      {Extra space to use after periods etc.~(in certain situations)}
%      {\texttt{\textbackslash xspaceskip}}
%
%   \TemplateKey{linefillskip}{l}
%      {Space to add at the point where some command requests a
%      ``carriage-return line-feed'' in the middle of a paragraph,
%      e.g., the \LaTeX{} command \texttt{\textbackslash newline}.}
%      {value of \key{parfillskip}}
%
%   \TemplateKey{parindent}{l}
%      {Non-stretchable space to be added at the beginning of a
%      paragraph.}
%      {\texttt{\textbackslash parindent}}
%
%   \TemplateSemantics
%
%     This template is exactly the same as the std one, except that it
%     applies only to the next paragraph after which the previous
%     setting will become active again. For an explanation of the keys
%     see the std template description.
%
%     It is not clear whether this approach makes much
%     sense. See comments below.
%
% \end{TemplateDescription}
%
%
%
%
%
% \begin{InstanceDescription}{justification}{centerfirst}{single}
%
%   \InstanceKey{startskip}{0pt plus 2fill}
%
%   \InstanceKey{leftskip}{0pt plus -1fill}
%
%   \InstanceKey{rightskip}{0pt plus 1fill}
%
%   \InstanceKey{parfillskip}{0pt}
%
%   \InstanceKey{linefillskip}{0pt}
%
%   \InstanceSemantics
%
%    This instance centers the first line of a paragraph and sets all
%    remaining lines as a solid block (including the last line). This
%    is a rather specialized justification method which relies on some
%    peculiar features of the \TeX's internal handling of stretchable
%    space. It is not possible to control the amount of white space on
%    the first line (other than forcing it to be centered) with the
%    controls available. Anything further needs manual intervention by
%    the user.
%
%    In a similar fashion centering of the last line could be achieved
%    (by setting \key{parfillskip} rather than \key{startskip}.
%
% \end{InstanceDescription}
%
%
%
%
%
%
%
% \begin{TemplateDescription}{justification}{complex}
%
%   \TemplateKey{first-para-justification-setup}{i}
%      {Justification setup for the first paragraph of a sequence.}
%      {none}
%
%   \TemplateKey{other-para-justification-setup}{i}
%      {Justification setup for the remaining paragraphs in the sequence}
%      {none}
%
%   \TemplateSemantics
%
%    This template allows to specify a different justification setup
%   for the first paragraph of a sequence and its remaining
%   paragraphs. Due to the implementation it is currently required
%   that the key \key{first-para-justification-setup} receives an
%   instance defined through the template `single' or more exactly
%   through a template that modifies the justification setup only for
%   a single paragraph. Otherwise all paragraphs in the sequence will
%   be formatted in the same way (i.e., the second key would have no
%   effect).
%
%   This is largely due to the fact that the implementation previously
%   contained different template types for local and `global' changes
%   to the justification.\footnote{Better concept needed! Perhaps the
%   coding in galley2 needs changing in this area.}
%
%
% \end{TemplateDescription}
%
%
%
%
% \begin{InstanceDescription}[\textbf{other-para-justification-setup}xx]
%       {justification}{centerfirst-adjust}{complex}
%
%   \InstanceKey{first-para-justification-setup}{centerfirst}
%
%   \InstanceKey{other-para-justification-setup}{adjust}
%
%   \InstanceSemantics
%
%    This instance is an example for a paragraph justification where
%    the first and the remaining paragraphs are handled differently:
%    the first paragraph will get a centered first line (with the
%    remaining lines being set as a squared block and any additional
%    paragraph will be justified. A common use for such a
%    layout would be table captions.
%
% \end{InstanceDescription}
%
%
%
%
%
%
%
%
%
%
% \begin{TemplateInterfaceDescription}{hyphenation}
%
%   \TemplateArgument{none}
%       {---}
%
%   \TemplateSemantics
%
%   Templates of this type define whether or not hyphenation is
%   attempted for upcoming paragraphs in the galley and if hyphenation
%   is allowed whether it should be encouraged (to support better
%   justification) or whether it should be only used if justification
%   would get too bad without it.\footnote{There are a few conceptual
%   questions: should templates of this type set anything like
%   \key{hyphenpenalty} or would this be better handled in the
%   linebreak template type and this template type only be used to set
%   hyphenation on/off? In case of the latter is it needed as a
%   separate type or should it be added to some other type?}
%
% \end{TemplateInterfaceDescription}
%
%
% \begin{TemplateDescription}{hyphenation}{TeX}
%
%   \TemplateKey{uchyph}{c}
%      {If positive allow hyphenation of words starting with an
%      uppercase letter.}
%      {1}
%
%   \TemplateKey{hyphenpenalty}{c}
%      {}
%      {50}
%
%   \TemplateKey{exhyphenpenalty}{c}
%      {}
%      {50}
%
%   \TemplateKey{lefthyphenmin}{c}
%      {}
%      {leave unchanged}
%
%   \TemplateKey{righthyphenmin}{c}
%      {}
%      {leave unchanged}
%
%   \TemplateSemantics
%
%     Keys are named like the \TeX{} primitives. As I remarked
%     earlier, perhaps \key{hyphenpenalty} and \key{exhyphenpenalty}
%     should be moved to the linebreak templates.
%
%     Also an open question is the keys
%     \key{left/righthyphenmin}. Their minimum values are actually a
%     feature of the current language or more exactly a feature of the
%     hyphenation patterns in force, but on the other hand one can
%     increase their values without harm and especially by setting
%     them to extremely high values one can disable hyphenation
%     altogether. So how should this be handled?
%
% \end{TemplateDescription}
%
%
%
% \begin{TemplateDescription}{hyphenation}{std}
%
%   \TemplateKey{hyphen-enable-boolean}{s}
%      {If false disables hyphenation}
%      {none}
%
%   \TemplateKey{hyphen-uppercase-boolean}{s}
%      {If positive allows hyphenation of words starting with an
%      uppercase letter.}
%      {none}
%
%   \TemplateKey{hyphen-discourage-boolean}{s}
%      {Sets penalties for breaking a line at a discretionary to a
%      higher value. Only relevant if \key{hyphen-enable-boolean} is
%      set to true.}
%      {none}
%
%   \TemplateKey{hyphen-encourage-boolean}{s}
%      {Sets penalties for breaking a line at a discretionary to a
%      higher value. Only relevant if \key{hyphen-enable-boolean} is
%      set to true.}
%      {none}
%
%   \TemplateSemantics
%
%    Better or worse than the TeX version? In any case it remains a
%    question of whether the line breaking parts should be set in a
%    template like this.
%
% \end{TemplateDescription}
%
%
%
%
%
%
% \begin{TemplateInterfaceDescription}{linebreak}
%
%   \TemplateArgument{none}
%       {---}
%
%   \TemplateSemantics
%
%    This template type determines the line breaking behavior of the
%    \TeX{} machinery, with the exception of whether or not to
%    hyphenate (certain) words. It could be considered to moved the
%    parameters related to breaking up math formulas to a separate
%    type. 
%
% \end{TemplateInterfaceDescription}
%
%
% \begin{TemplateDescription}{linebreak}{TeX}
%
%   \TemplateKey{pretolerance}{c}
%      {Maximum tolerance allowed for individual lines to break the
%      paragraph without attempting hyphenation.}
%      {100}
%
%   \TemplateKey{tolerance}{c}
%      {Maximum tolerance allowed for individual lines when breaking a
%      paragraph while attempting hyphenation (if this limit can't be
%      met \key{emergencystretch} comes into play.}
%      {200}
%
%   \TemplateKey{linepenalty}{c}
%      {Extra penalty charged per line in the paragraph. By making
%      this penalty higher \TeX{} will try harder to produce compact
%      paragraphs.}
%      {10}
%
%   \TemplateKey{binoppenalty}{c}
%      {Penalty charged if an inline math formula is broken at a
%      binary operator.}
%      {700}
%
%   \TemplateKey{relpenalty}{c}
%      {Penalty charged if an inline math formula is broken at a
%      relational symbol.}
%      {500}
%
%   \TemplateKey{hbadness}{c}
%      {Boundary that if exceeded will cause \TeX{} to report an
%      underfull line.}
%      {1000}
%
%   \TemplateKey{adjdemerits}{c}
%      {Extra demerit charge if two visually incompatible lines follow
%      each other.}
%      {10000}
%
%   \TemplateKey{doublehyphendemerits}{c}
%      {Extra demerit charge of two (or more) lines in succession end
%      in a hyphen.}
%      {10000}
%
%   \TemplateKey{finalhyphendemerits}{c}
%      {Extra demerit charge if the second last line is hyphenated.}
%      {5000}
%
%   \TemplateKey{hfuzz}{l}
%      {Boundary below overfull lines are not reported.}
%      {.1pt}
%
%   \TemplateKey{emergencystretch}{l}
%      {Complicated --- I write up the explanation at some other day :-)}
%      {0pt}
%
%   \TemplateSemantics
%     Keys are named like the \TeX{} primitives. As I remarked
%     earlier, perhaps \key{hyphenpenalty} and \key{exhyphenpenalty}
%     from the hyphenation template
%     should be moved to the linebreak templates.
%
%
% \end{TemplateDescription}
%
%
%
%
%
%
% \begin{TemplateInterfaceDescription}{hj}
%
%   \TemplateArgument{none}
%       {---}
%
%   \TemplateSemantics
%    Often certain combinations of justification, line breaking and
%    hyphenation settings are used together. For those case it might
%    be desirable to be able to identify these settings with a single
%    name. The hj type provides for this. It is supposed to set the
%    complete ``micro typography'' setting concerning paragraphs,
%    i.e., everything that happens within the outer form as defined by
%    the measure and/or pshape templates.
%
%    Whether this template type is actually needed remains to be
%    seen. Clearly everywhere where it gets applied one could apply
%    individually templates of type justification, linebreak, and
%    hyphenation.
%
%    Right now the low-level galley interface uses an instance of this
%    type (with the name ``default'') to initialize a new
%    galley.
%
% \end{TemplateInterfaceDescription}
%
%
% \begin{TemplateDescription}{hj}{std}
%
%   \TemplateKey{justification-setup}{i}
%      {Instance specifying the justification used.}
%      {\texttt{default}}
%
%   \TemplateKey{linebreak-setup}{i}
%      {Instance specifying the line breaking parameters}
%      {\texttt{default}}
%
%   \TemplateKey{hyphenation-setup}{i}
%      {Instance specifying the hyphenation parameter used.}
%      {\texttt{default}}
%
%   \TemplateSemantics
%    This is the shortcut template as discussed before. One could
%    think of other templates that do set the parameters using a large
%    number keys (\TeX{} style, for example) --- whether this
%    makes sense~\ldots
%
% \end{TemplateDescription}
%
%

% \begin{InstanceDescription}[\textbf{justification-setup}xx]
%       {hj}{default}{std}
%
%   \InstanceKey{justification-setup}{default}
%
%   \InstanceKey{linebreak-setup}{default}
%
%   \InstanceKey{hyphenation-setup}{default}
%
%   \InstanceSemantics
%
%    This instance is used when initializing new galleys. It is in
%    fact slightly faster to run |\UseInstance{hj}{default}| compared
%    to three calls to |\UseInstance| for the individual template
%    instances.\footnote{This is because we avoid the overhead of
%    \texttt{\textbackslash UseInstance} (the keys of type \texttt{i}
%    are optimized in this respect.}
%
% \end{InstanceDescription}
%%
%
%
%
% \StopEventually{}
% 
% \section{Implementation}
%
% Set up certain defaults including to ignore white space
% within the body of this package. \LaTeXe{} release needs to be
% recent because of changing some bits of the |\parbox| handling below.
%    \begin{macrocode}
%<*package>
\NeedsTeXFormat{LaTeX2e}[1998/12/01]
%    \end{macrocode}
%
%    \begin{macrocode}
\RequirePackage{template,xparse}
% \RequirePackage{galley2}       % this is required but needs to
                                 % be loaded afterwards !!!!
%    \end{macrocode}
%
% The primitives of the galley mechanism currently have ``:'' in their
% names so\ldots
%    \begin{macrocode}
\IgnoreWhiteSpace
\catcode`\:=11\relax
%    \end{macrocode}
%
%
% \subsection{Using Font Dimensions}
%
% Some helper functions to access information in a tfm file.
% They do not really belong here but right now we don't have a place
% for them.
% \begin{macro}{\@usefontdimen}
%    A shorthand:
%    \begin{macrocode}
\def\@usefontdimen#1{\fontdimen#1\font}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\fontslant}
% \begin{macro}{\fontwordspace}
% \begin{macro}{\fontwordspacestretch}
% \begin{macro}{\fontwordspaceshrink}
% \begin{macro}{\fontex}
% \begin{macro}{\fontem}
% \begin{macro}{\fontextraspace}
%    The following commands access dimension of the current font,
%    e.g., |\fontwordspace| gives the width of a space between words
%    in the current font. Typically these commands have to be used
%    together with |\DelayEvaluation| so that they are applied at
%    runtime rather than during the declaration of template
%    instances.
%    \begin{macrocode}
\def\fontslant             {\@usefontdimen1}
\def\fontwordspace         {\@usefontdimen2}
\def\fontwordspacestretch  {\@usefontdimen3}
\def\fontwordspaceshrink   {\@usefontdimen4}
\def\fontex                {\@usefontdimen5}
\def\fontem                {\@usefontdimen6}
\def\fontextraspace        {\@usefontdimen7}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \subsection{Templates for the second layer}
%
% \subsubsection{The template type `measure'}
%
%    The `measure' type takes one argument (left margin or
%    |\NoValue|), see discussion above.
%    \begin{macrocode}
\DeclareTemplateType{measure}{1}
%    \end{macrocode}
%
%    \begin{macrocode}
\DeclareTemplate{measure}{absolute}{1}{
  leftmargin  =l \leftmargin,
  rightmargin =l \rightmargin,
 }{
  \DoParameterAssignments
%    \end{macrocode}
%
%    User provided left margin is always relative to current
%    indentation even if template does provide absolute values.
%    \begin{macrocode}
  \IfNoValueF{#1} { \setlength\leftmargin{ #1 + \@totalleftmargin } } 
  \setSGPVmeasure:nn \leftmargin {\hsize -\leftmargin -\rightmargin }
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareTemplate{measure}{relative}{1}{
  leftmargin  =l \leftmargin,
  rightmargin =l \rightmargin,
 }{
  \DoParameterAssignments
  \IfNoValueF{#1} { \setlength\leftmargin{#1} } 
  \addSGPVmeasure:nn \leftmargin { -\leftmargin -\rightmargin }
}
%    \end{macrocode}
%
%
%
% \subsection{Templates for the third layer}
%
% \subsubsection{The template type `pshape'}
%
% The template type `pshape' right now is mostly an interface to
% \TeX's |\parshape| primitive. This is probably going to be extended.
%
%    \begin{macrocode}
\DeclareTemplateType{pshape}{0}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareTemplate{pshape}{cutout}{0}{
  no-page-break-boolean  =s {\setGALbreak:n {-3}}{},
  left-side-boolean      =s {}{\let\shape@side\setGALrightparshape:nnn},
  normal-lines-num       =C  \pshape@normalines,
  parshape-list          =f0 \pshape@parshape,
 }{
  \let\pshape@normalines\z@
  \let\shape@side\setGALleftparshape:nnn
  \DoParameterAssignments 
  \shape@side \pshape@normalines \z@ \pshape@parshape
 }
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{pshape}{staggered}{cutout}{
   no-page-break-boolean = true,
   normal-lines-num  = 1,
   parshape-list = { 20pt, 40pt, 60pt },   
}
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
\DeclareInstance{pshape}{ltriangle}{cutout}{
   no-page-break-boolean = true,
   normal-lines-num  = 0,
   parshape-list = { 60pt, 40pt, 20pt },   
}
%    \end{macrocode}
%
% The next instance provides a ``noop'' or ``regular'' pshape instance,
% i.e., one 
% that can be applied when a template requests to set up a pshape but
% the standard rectangular is desired (of course using using the
% cutout template for this task is very very inefficient so at some
% point this should be done differently).
%
%    \begin{macrocode}
\DeclareInstance{pshape}{rectangle}{cutout}{
   no-page-break-boolean = false,
   normal-lines-num  = 0,
   parshape-list = { },   
}
%    \end{macrocode}
%
%
% \subsection{Templates for the forth layer}
%
% \subsubsection{The template type `justification'}
%
%    How we justify the text within the measure:
%    \begin{macrocode}
\DeclareTemplateType{justification}{0}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareTemplate{justification}{single}{0}{
  startskip    =L \justification@a ,
  leftskip     =L \justification@b ,
  rightskip    =L \justification@c ,
  parfillskip  =L \justification@d ,
  spaceskip    =L \justification@e ,
  xspaceskip   =L \justification@f ,
  linefillskip =L \justification@g ,
  parindent    =L \justification@h ,
 }{
  \def\justification@a{\z@}
  \def\justification@b{\leftskip}
  \def\justification@c{\rightskip}
  \def\justification@d{\parfillskip}
  \def\justification@e{\spaceskip}
  \def\justification@f{\xspaceskip}
  \def\justification@g{\justification@d}
  \def\justification@h{\parindent}
%
  \DoParameterAssignments
%    \end{macrocode}
%    Next is a written out form of |\appendtoDGPVthing:nx| (more or less)
%    \begin{macrocode}
  \xdef \GAL@j@
            {{\justification@a}
             {\justification@b}
             {\justification@c}
             {\justification@d}
             {\justification@e}
             {\justification@f}
             {\justification@g}
             {\justification@h}
             }
  \GAL@prepare@reassign:NN  \GAL@j@  \GAL@j@s 
 }
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareTemplate{justification}{std}{0}{
  startskip      =L  \justification@a ,
  leftskip       =L  \justification@b ,
  rightskip      =L  \justification@c ,
  parfillskip    =L  \justification@d ,
  spaceskip      =L  \justification@e ,
  xspaceskip     =L  \justification@f ,
  linefillskip   =L  \justification@g ,
  parindent      =L  \justification@h ,
 }
 {
  \def\justification@a{\z@}
  \def\justification@b{\leftskip}
  \def\justification@c{\rightskip}
  \def\justification@d{\parfillskip}
  \def\justification@e{\spaceskip}
  \def\justification@f{\xspaceskip}
  \def\justification@g{\justification@d}
%
  \def\justification@h{\parindent}
  \DoParameterAssignments
  \edef \@tempa {\noexpand \setSGPVthing:nn j
                                {{\justification@a}
                                 {\justification@b}
                                 {\justification@c}
                                 {\justification@d}
                                 {\justification@e}
                                 {\justification@f}
                                 {\justification@g}
                                 {\justification@h}
                                }
                }
  \@tempa     
%    \end{macrocode}
%    \begin{macrocode}
  \expandafter \setup@paragraph@justification \GAL@j@
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareTemplate{justification}{complex}{0}{
  first-para-justification-setup =i {justification}
                                            \justification@first,
  other-para-justification-setup =i {justification}
                                            \justification@other,
 }
 {
  \DoParameterAssignments
% long term changes first!
  \justification@other
  \justification@first
 }
%    \end{macrocode}
%
%
%
% And some instances for testing \ldots
%    \begin{macrocode}
\DeclareInstance{justification}{adjust}{std}
   {rightskip  =0pt,
    leftskip   =0pt,
    startskip  =0pt,
    parfillskip=\fill
}
%    \end{macrocode}
%
%
%
% Another name for the above:
%    \begin{macrocode}
\DeclareInstance{justification}{default}{std}
   {rightskip  =0pt,
    leftskip   =0pt,
    startskip  =0pt,
    parfillskip=\fill
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{justification}{adjust2}{std}
   {parindent  = 0pt,
    rightskip  = 0pt,
    leftskip   = 0pt,
    startskip  = 0pt,
    parfillskip= 20pt plus 1fil
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{justification}{center}{std}
   {parindent  =0pt,
    rightskip  =\fill,
    leftskip   =\fill,
    startskip  =0pt,
    parfillskip=0pt
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{justification}{centermiddle}{std}
   {parindent  =0pt,
    rightskip  =36pt plus 1fill,
    leftskip   =36pt plus 1fill,
    startskip  =-36pt plus -1fill,
    parfillskip=-36pt plus -1fill,
    linefillskip= 0pt,
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{justification}{raggedright}{std}
   {rightskip  = \DelayEvaluation 0pt plus 2em,
    leftskip   = 0pt,
    startskip  = 0pt,
    parfillskip= \fill,
    spaceskip =  \DelayEvaluation \fontwordspace,
    xspaceskip = \DelayEvaluation \fontwordspace + \fontextraspace,
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{justification}{flushleft}{std}
   {rightskip  =\fill,
    leftskip   =0pt,
    startskip  =0pt,
    parfillskip=\fill,
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{justification}{raggedleft}{std}
   {leftskip   = \DelayEvaluation 0pt plus 2em,
    rightskip  = 0pt,
    startskip  = 0pt,
    parfillskip= 0pt,
    spaceskip  = \DelayEvaluation \fontwordspace,
    xspaceskip = \DelayEvaluation \fontwordspace + \fontextraspace,
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{justification}{flushright}{std}
   {leftskip   = \fill,
    rightskip  = 0pt,
    startskip  = 0pt,
    parfillskip= 0pt,
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
% this does now work:
\DeclareInstance{justification}{centerfirst}{single}
   {parindent  = 0pt,
    rightskip  = \fill,
    leftskip   = -\fill,
    parfillskip= 0pt,
    startskip  = 0pt plus 2fill,
    linefillskip= 0pt,
}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{justification}{centerfirst-adjust}{complex}
 {  first-para-justification-setup = centerfirst,
    other-para-justification-setup = adjust
 }
%    \end{macrocode}
%
%
%
% \subsubsection{The template `linebreak'}
%
%    How we attempt to break the paragraph into lines:
%    \begin{macrocode}
\DeclareTemplateType{linebreak}{0}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareTemplate{linebreak}{TeX}{0}{
  pretolerance         =c [100]   \pretolerance,
  tolerance            =c [200]   \tolerance,
  linepenalty          =c [10]    \linepenalty,
  binoppenalty         =c [700]   \binoppenalty,
  relpenalty           =c [500]   \relpenalty,
  hbadness             =c [1000]  \hbadness,
  adjdemerits          =c [10000] \adjdemerits,
  doublehyphendemerits =c [10000] \doublehyphendemerits,
  finalhyphendemerits  =c [5000]  \finalhyphendemerits,
%
  hfuzz                =l [.1pt] \hfuzz,
  emergencystretch     =l [0pt]  \emergencystretch,
%
}
 {\DoParameterAssignments 
%<*trace>
  \GAL@typeout{Now~ changing~ linebreaking}
%</trace>
 }
%    \end{macrocode}
%
%
%
%
%
%    \begin{macrocode}
\DeclareInstance{linebreak}{default}{TeX}{}
\DeclareInstance{linebreak}{fussy}{TeX}{}
\DeclareInstance{linebreak}{sloppy}{TeX}
  {
  tolerance            = 9999,
  hfuzz                = .5pt,
  emergencystretch     = \DelayEvaluation 3em,
  }
%    \end{macrocode}
%
%
% \begin{macro}{\fussy}
% \begin{macro}{\sloppy}
%    Two old friends from \LaTeX:
%    \begin{macrocode}
\def\fussy {\UseInstance{linebreak}{fussy}}
\def\sloppy{\UseInstance{linebreak}{sloppy}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%
% \subsubsection{The template type `hyphenation'}
%
%    How do we handle the question of hyphenation:
%    \begin{macrocode}
\DeclareTemplateType{hyphenation}{0}

\DeclareTemplate{hyphenation}{TeX}{0}{
  uchyph                   =c [1]   \uchyph,
  hyphenpenalty            =c [50]  \hyphenpenalty,
  exhyphenpenalty          =c [50]  \exhyphenpenalty,
  lefthyphenmin            =c       \lefthyphenmin,
  righthyphenmin           =c       \righthyphenmin,
}
 {\DoParameterAssignments 
%<*trace>
  \GAL@typeout{Now~ changing~ hyphenation}
%</trace>
 }
%    \end{macrocode}
%
%
%
%
%
%    \begin{macrocode}
\newcount\@@lefthyphenmin
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareTemplate{hyphenation}{std}{0}{
  hyphen-enable-boolean    =s  {\ifnum\@@lefthyphenmin>\z@
                                  \lefthyphenmin\@@lefthyphenmin
                                \fi}
                               {\@@lefthyphenmin\lefthyphenmin
                                \lefthyphenmin\@M},
  hyphen-uppercase-boolean =s  {\uchyph\@ne}{\uchyph\z@},
  hyphen-discourage-boolean=s  {\hyphenpenalty\@highpenalty
                                \exhyphenpenalty\@highpenalty}{},
  hyphen-encourage-boolean =s  {\hyphenpenalty\@lowpenalty
                                \exhyphenpenalty\@lowpenalty}{},
}
 {\DoParameterAssignments 
%<*trace>
  \GAL@typeout{Now~ changing~ hyphenation}
%</trace>
 }
%    \end{macrocode}
%
%
%
%
%
%    \begin{macrocode}
\DeclareInstance{hyphenation}{default}{TeX}
    {}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{hyphenation}{off}{std}
    {hyphen-enable-boolean = false}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{hyphenation}{on}{std}
    {hyphen-enable-boolean = true}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{hyphenation}{discourage}{std}
    {hyphen-enable-boolean = true,
     hyphen-discourage-boolean = true}
%
%\ShowInstance{hyphenation}{off}
%\ShowInstance{hyphenation}{discourage}
%    \end{macrocode}
%
%
%
% \subsubsection{The template type `hj'}
%
%    \begin{macrocode}
\DeclareTemplateType{hj}{0}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareTemplate{hj}{std}{0}{
  justification-setup =i {justification} [default] \hj@justification,
  linebreak-setup     =i {linebreak}     [default] \hj@linebreak,
  hyphenation-setup   =i {hyphenation}   [default] \hj@hyphenation,
}
 {\DoParameterAssignments 
  \hj@justification
  \hj@linebreak
  \hj@hyphenation
 }
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{hj}{default}{std}{}
%    \end{macrocode}
%
%
%    \begin{macrocode}
%\ShowInstance{hj}{default}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\catcode`\:=12\relax
\endinput
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
%
% \Finale
%
% \endinput
%
%
%
% \subsection{The template `pagebreak'}
%
%
%
% The rest doesn't belong here but i've already set it up I have to
% keep it somewhere until work on the page builder actually
% starts---so why not in this place.
%
% \begin{TemplateInterfaceDescription}{pagebreak}
%
%   \TemplateArgument{1}
%       {none}
%
%   \TemplateSemantics
%
% \end{TemplateInterfaceDescription}
%
%
% \begin{TemplateDescription}{pagebreak}{TeX}
%
%   \TemplateKey{clubpenalty}{c}
%      {}
%      {150}
%
%   \TemplateKey{widowpenalty}{c}
%      {}
%      {150}
%
%   \TemplateKey{displaywidowpenalty}{c}
%      {}
%      {50}
%
%   \TemplateKey{predisplaypenalty}{c}
%      {}
%      {10000}
%
%   \TemplateKey{postdisplaypenalty}{c}
%      {}
%      {0}
%
%   \TemplateKey{brokenpenalty}{c}
%      {}
%      {100}
%
%   \TemplateKey{interlinepenalty}{c}
%      {}
%      {0}
%
%   \TemplateKey{vbadness}{c}
%      {}
%      {1000}
%
%   \TemplateKey{vfuzz}{l}
%      {}
%      {.1pt}
%
%   \TemplateSemantics
%
% \end{TemplateDescription}
%
%
%
%
%    \begin{macrocode}
\DeclareTemplateType{pagebreak}{0}
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareTemplate{pagebreak}{TeX}{0}{
  clubpenalty          =c [150]   \clubpenalty,
  widowpenalty         =c [150]   \widowpenalty,
  displaywidowpenalty  =c [50]    \displaywidowpenalty,
  predisplaypenalty    =c [10000] \predisplaypenalty,
  postdisplaypenalty   =c [0]     \postdisplaypenalty,
  brokenpenalty        =c [100]   \brokenpenalty,
  interlinepenalty     =c [0]     \interlinepenalty,
%
  vbadness             =c [1000]  \vbadness,
  vfuzz                =l [.1pt]  \vfuzz,
}
 {\DoParameterAssignments 
%<*trace>
  \GAL@typeout{Now~ changing~ pagebreaking}
%</trace>
 }
%    \end{macrocode}
%
%
%    \begin{macrocode}
\DeclareInstance{pagebreak}{default}{TeX}{}
%    \end{macrocode}
%
%
%
%
%
%
%
%
% \begin{TemplateInterfaceDescription}{}
%
%   \TemplateArgument{1}
%       {}
%
%   \TemplateSemantics
%
% \end{TemplateInterfaceDescription}
%
%
