% \iffalse
%% File xhead.dtx (C) Copyright 2010 Frank Mittelbach, LaTeX3 Project
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
%% license or (at your option) any later version.  The latest version
%% of this license is in the file
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% This file is part of the ``xhead bundle'' (The Work in LPPL)
%% and all files in that bundle must be distributed together.
%%
%% The released version of this bundle is available from CTAN.
%%
%% -----------------------------------------------------------------------
%%
%% The development version of the bundle can be found at
%%
%%    http://www.latex-project.org/svnroot/experimental/trunk/
%%
%% for those people who are interested.
%%
%%%%%%%%%%%
%% NOTE: %% 
%%%%%%%%%%%
%%
%%   Snapshots taken from the repository represent work in progress and may
%%   not work or may contain conflicting material!  We therefore ask
%%   people _not_ to put them into distributions, archives, etc. without
%%   prior consultation with the LaTeX Project Team.
%%
%% -----------------------------------------------------------------------
%%
%<*driver|package>
\RequirePackage{expl3}
\GetIdInfo$Id: xhead.dtx 1914 2010-05-21 16:18:46Z schoepf $
          {Templates heading commands}
%</driver|package>
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass{l3doc}


% next three definitions are big hacks to run the file
% without the above packages
%
\makeatother

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

 \begin{document}
 \DocInput{xhead.dtx}
 \end{document}
%</driver>
% \fi
%
% ^^A\CheckSum{343}
%
%
% \title{The \textsf{xhead} package\thanks{This file
%         has version number \fileversion, last
%         revised \filedate.}}
% \author{FMi}
% \date{\filedate}
% \maketitle
%
% \tableofcontents
%
% \bigskip
%
% \begin{abstract}
%   This module contains basic templates generating typical headings for
%   various levels. This is very much work in progress and none of its content
%   should be considered stable.  Concepts and implementation are still under
%   development.
% \end{abstract}
% 
%
% \newcommand\NOVALUE{\texttt{\string\NoValue}}
% \newcommand\EMPTY{\textit{<empty>}}
% \newcommand\STRING{\textit{<string>}}
% \newcommand\TRUE{\texttt{true}}
% \newcommand\FALSE{\texttt{false}}
% \newcommand\KEYVALS{\textit{<key/value list>}}
% \newcommand\HASH[1]{\texttt{\##1}}
%
% \makeatletter
% \renewenvironment{TemplateInterfaceDescription}[1]
%   {\subsection{The~object~type~`#1'}%
%    \begingroup
%    \@beginparpenalty\@M
%    \description
%    \def\TemplateArgument##1##2{\item[Arg:~##1 (##2)]}^^A
%    \def\TemplateSemantics{\enddescription\endgroup
%        \subsubsection*{Semantics:}}^^A
%   }
%   {\par\bigskip}
% \makeatother
%
% \section{Introduction}
%
%
% \section{Interfaces}
%
% \begin{TemplateInterfaceDescription}{heading}
%
%
%   \TemplateArgument{1}{boolean}
%     If \TRUE{} generate an unnumbered heading, otherwise a number is
%    generated up to a certain heading level. If \TRUE{} TOC entries and
%    running headers are suppressed unless explicitly forced by other
%    arguments below.
%
%   \TemplateArgument{2}
%       {\STRING/\NOVALUE/\EMPTY}
%     Specifies an alternate heading text for the TOC if one is produced. If
%     \NOVALUE{} or \EMPTY{} the TOC receives the  the main title text.
%
%   \TemplateArgument{3}
%       {boolean}
%     If \TRUE{} a TOC entry is forced (i.e., generated even if normally supressed).
%
%   \TemplateArgument{4}
%       {\STRING/\NOVALUE/\EMPTY}
%     Specifies an alternate heading text for the running header if one is
%    produced. If \NOVALUE{} or \EMPTY{} the running header receives the the
%    main title text.
%
%   \TemplateArgument{5}
%       {boolean}
%     If \TRUE{} a running header is forced (i.e., generated even if normally
%    supressed).
%
%   \TemplateArgument{6}
%       {\STRING}
%    The title of the heading in the document. Also used for the TOC entry and
%     running header (if produced) unless overwritten by other arguments.
%
%   \TemplateArgument{7}
%       {\KEYVALS}
%   Extension argument to receive less use key value pairs to manipulate the
%     heading. Exact syntax and semantics still need to be defined.
%
%   \TemplateSemantics
%     This template type defines the basic interface for headings both display
%     headings as well as run-in headings.
%
%    A TOC entry is generated if \HASH{1} is \FALSE{} or \HASH{3} being
%    \TRUE{}. The heading title for the TOC entry is \HASH{6} unless
%    overwritten by a non-empty HASH{2}.  Whether or not this TOC entry
%    actually appears in the TOC depends on settings for the TOC
%    generation. (However, if not generated if will obviously not appear.)
%
%    A running header is generated if \HASH{1} is \FALSE{} or \HASH{5} or
%    \TRUE{}. The heading title for the determined as follows: if \HASH{4} is
%    non-empty it will be used, otherwise if \HASH{2} is non-empty it will be
%    used, otherwise HASH{6} will be used.
%
%    \HASH{7} will hold additional key/value pairs that define more specific
%    semantics. This isn't implemented yet.
%
%    The above describes my current thinking about how those arguments should
%    interact. In simpler templates (based on 2e semantics) the arguments
%    \HASH{3} to \HASH{5} and \HASH{7} will get ignored.
%
%
% \end{TemplateInterfaceDescription}
%
%
% \begin{TemplateDescription}{heading}{2e-vertical}
%
%
%   \TemplateKey{name}{tokenlist}
%      {Name of the heading. Used to refer to parts of its data structure,
%     e.g., the counter associated with the heading will have this name. Must
%     be set to a suitable string like ``section''}
%      {none}
%
%   \TemplateKey{level}{integer}
%      {The level of the heading in the hierarchy. Required.}
%      {none}
%
%   \TemplateKey{break-penalty}{penalty}
%      {Penlty to break in front of the heading unless it is immediately
%     preceeded a higher-level heading in which case breaking is prohibited.}
%      {-300}
%
%   \TemplateKey{indent}{length}
%      {Indentation of the heading from the left margin.}
%      {0pt}
%
%   \TemplateKey{above-skip}{skip}
%      {Vertical space above the heading.}
%      {0pt}
%
%   \TemplateKey{below-skip}{skip}
%      {Vertical space below the heading.}
%      {0pt}
%
%   \TemplateKey{title-decl}{function 0}
%      {Declarations to format the heading, e.g., font changes.}
%      {\EMPTY}
%
%   \TemplateKey{number-format}{function 1}
%      {Formatting instruction for the heading number (if present), receiving
%    the heading counter representation as an argument.}
%      {\cs{xhead_default_number_format:n}}
%
%   \TemplateKey{indent-after}{boolean}
%      {Should the first paragraph after the heading be indented?}
%      {\FALSE}
%
%   \TemplateSemantics
%
%      This is, or should be, a reimplementation of the 2e |\@startsection|
%      command for generating vertical headings. |\@startsection| is also able
%      to produce run-in headings, but this is not covered by the current
%      template.
%
% \end{TemplateDescription}
%
%
%
%
%
% \StopEventually{}
% 
% \section{Implementation}
%
%    \begin{macrocode}
%<*package>
\RequirePackage{expl3,xtemplate}
%    \end{macrocode}
%    
%    \begin{macrocode}
\GetIdInfo$Id: xhead.dtx 1914 2010-05-21 16:18:46Z schoepf $
  {heading module}
\ProvidesExplPackage
  {\filename}{\filedate}{\fileversion}{\filedescription}
%    \end{macrocode}
%
%
% \subsection{The heading object type}
%
% Arguments:
%\begin{verbatim}
%   #1 (boolean)                : produce no number
%   #2 (string/\NoValue/empty)  : toc-title  if different from title
%   #3 (boolean)                : force toc entry
%   #4 (string/\NoValue/empty)  : mark-title if different from toc-title
%   #5 (Boolean)                : force mark entry
%   #6 (string)                 : title
%   #7 (extra key vals)
%\end{verbatim}
%
%    \begin{macrocode}
\DeclareObjectType {heading} {7}
%    \end{macrocode}
%
%
% \subsection{Interfaces to other components}
%
% This section holds code that is (or should be) common between different
% heading templates, for example, code for passing a title to the TOC system
% will always use the same TOC interface so it is encapsulated
% here. Effectively this means that this section should be the only part that
% needs modification if we update these other components and intorduce new
% interfaces for them.
%
% At the moment everything is set up to use the old 2e interfaces, but this
% will change over time.
%
%
%
% \subsubsection{Generating TOC and mark entries}
%
%
%  \begin{macro}{\xhead_generate_toc:NNNNN}
%  \begin{macro}{\xhead_generate_toc:NNNNo}
%    This command provides the interface to the TOC system (currently the 2e
%   one). It uses its first two arguments to decide if a TOC entry should be produced
%   and if so generates the entry from the remaining arguments.
%
%     Arguments:
%\begin{verbatim}
%   #1 (boolean)       : produce no number
%   #2 (boolean)       : force toc entry
%   #3 (string)        : heading name (\l_xhead_name_tl)
%   #4 (string)        : heading number if any (\l_xhead_number_tl)
%   #5 (string)        : toc-title (\l_xhead_toc_title_tl)
%\end{verbatim}
%
%    \begin{macrocode}
\cs_new:Npn \xhead_generate_toc:NNNNN #1#2#3#4#5 {
%<*trace>
   \typeout{xhead_generate_toc:NNNNN=#1:#2:#3:#4:#5}
%</trace>
%    \end{macrocode}
%    A TOC entry is produced if the heading number was not suppressed (|!#1|)
%    or it is forced (|#2|).
%    \begin{macrocode}
   \bool_if:nT
    { #2 || ! #1 }
    {
     \group_begin:
%    \end{macrocode}
%    Guard against use of mark commands in the heading title (from old sources).
%    \begin{macrocode}
      \cs_set_eq:NN \@mkboth \use_none:nn
      \cs_set_eq:NN \markboth \use_none:nn
      \cs_set_eq:NN \markright \use_none:n
%    \end{macrocode}
%    Use the old 2e |\addcontentsline| interface:
%    \begin{macrocode}
      \addcontentsline{toc}{#3}
         {
          \tl_if_empty:NF #4
              { \protect\numberline{ #4 } }
          #5
         }
    \group_end:
   }
}
%    \end{macrocode}
%    In the templates we really want to make sure that the title in the last
%    argument is passed and not a tokenlist in which it is saved. After all,
%    this text will get passed around over long distances. We therefore
%    provide the following variant for use in templates:
%    \begin{macrocode}
\cs_generate_variant:Nn \xhead_generate_toc:NNNNN {NNNNo}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%
%
%
%  \begin{macro}{\xhead_generate_mark:NNNNN}
%  \begin{macro}{\xhead_generate_mark:NNNNo}
%    This command provides the interface to the mark system for running
%    headers(currently the 2e one). It uses its first two arguments to decide
%    if a mark entry should be produced and if so generates the entry from the
%    remaining arguments.
%
%    Arguments:
%\begin{verbatim}
%   #1 (boolean)       : produce no number
%   #2 (boolean)       : force running header  entry
%   #3 (string)        : heading name (\l_xhead_name_tl)
%   #4 (string)        : heading number if any (\l_xhead_number_tl)
%   #5 (string)        : mark-title (\l_xhead_mark_title_tl)
%\end{verbatim}
%
%    \begin{macrocode}
\cs_new:Npn \xhead_generate_mark:NNNNN #1#2#3#4#5 {
%<*trace>
   \typeout{xhead_generate_mark:NNNNN=#1:#2:#3:#4:#5}
%</trace>
%    \end{macrocode}
%    A running header entry is produced if the heading number was not
%    suppressed (|!#1|) or it is forced (|#2|).
%    \begin{macrocode}
   \bool_if:nT
    { #2 || ! #1 }
    {
     \group_begin:
%    \end{macrocode}
%    Guard against use of mark command in heading titles (from old
%    sources)\footnote{This is wrong here, needs thought.}
%    \begin{macrocode}
       \cs_set_eq:NN \@mkboth \use_none:nn
%    \end{macrocode}
%    Again we use the original 2e interface.  |\markright|, etc.\ currently adds
%    the section number so we do not add it here---for now.
%    \begin{macrocode}
       \use:c {#3 mark} {#5}
     \group_end:
    }
}
%    \end{macrocode}
%    In the templates we really want to make sure that the title in the last
%    argument is passed and not a tokenlist in which it is saved. After all,
%    this text will get passed around over long distances. We therefore
%    provide the following variant for use in templates:
%    \begin{macrocode}
\cs_generate_variant:Nn \xhead_generate_mark:NNNNN {NNNNo}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%
%
%
%  \begin{macro}{\xhead_generate_toc_and_mark:NNNNNNN}
%
%   This is just putting it all together, may not be worth having.
%    
%    Arguments:
%\begin{verbatim}
%   #1 (boolean)       : produce no number
%   #2 (boolean)       : force toc entry
%   #3 (boolean)       : force running header entry
%   #4 (string)        : heading name (\l_xhead_name_tl)
%   #5 (string)        : heading number or empty (\l_xhead_number_tl)
%   #6 (string)        : toc-title (\l_xhead_toc_title_tl)
%   #7 (string)        : mark-title (\l_xhead_mark_title_tl)
%\end{verbatim}
%
%    \begin{macrocode}
\cs_new:Npn \xhead_generate_toc_and_mark:NNNNNNN #1#2#3#4#5#6#7 {
     \xhead_generate_toc:NNNNo  
          #1 #2 #4 #5 #6
     \xhead_generate_mark:NNNNo 
          #1 #3 #4 #5 #7
}
%    \end{macrocode}
%  \end{macro}
%
%
%
%
% \subsubsection{Prepare heading number}
%
%
%
%  \begin{macro}{\xhead_update_prepare_number:N}
%
%    This command checks if a number should be produced and if so increments
%    the corresponding counter and stores the number in
%    |\l_xhead_number_tl|. Otherwise |\l_xhead_number_tl| will be set to empty
%    to indicate that no number should be displayed.
%
%    Arguments:
%\begin{verbatim}
%   #1 (boolean)       : produce no number
%\end{verbatim}

%    Assumptions:
%\begin{verbatim}
%   \l_xhead_name_tl        : holds heading name
%   \l_xhead_level_int      : holds heading level
%\end{verbatim}
%
%   Outputs:
%\begin{verbatim}
%   \l_xhead_number_tl : holds heading number or returns empty
%\end{verbatim}
%
%    \begin{macrocode}
\cs_new:Npn \xhead_update_prepare_number:N #1 {
   \bool_if:nTF
     { #1 || \intexpr_compare_p:n { \l_xhead_level_int > \c@secnumdepth } }
     { \tl_clear:N \l_xhead_number_tl }
     {
       \refstepcounter \l_xhead_name_tl
       \tl_set:Nx \l_xhead_number_tl { \use:c {the \l_xhead_name_tl} }
     }
}
%    \end{macrocode}
%  \end{macro}
%
%
%
%
% \subsubsection{Prepare indentation after heading}
%
%  To set the paragraph indentation after a heading we need to interact with
%  the galley mechanism, which at one point will be \texttt{xgalley}. Right
%  now we use the 2e interface.
%
%  \begin{macro}{\xhead_set_after_indention:N}
%    Here we set the 2e flag depending
%    \begin{macrocode}
\cs_new:Npn \xhead_set_after_indention:N  #1 {
   \bool_if:NTF #1 \@afterindenttrue \@afterindentfalse 
}
%    \end{macrocode}
%  \end{macro}
%
%
%
%
%
% \subsubsection{Evaluating the title arguments}
%
%  According to the heading object type spec the title text for the toc and
%  running header may differ from the main title in dependence of the
%  arguments passed to the template.
%  The code below implements the documented logic.
%
%  \begin{macro}{\xhead_set_titles:nnn}
%
%    Arguments:
%\begin{verbatim}
%   #1 (string/\NoValue/empty)  : toc-title  if different from title
%   #2 (string/\NoValue/empty)  : mark-title if different from toc-title
%   #3 (string)                 : title
%\end{verbatim}
%
%    \begin{macrocode}
\cs_new:Npn \xhead_set_titles:nnn #1#2#3 {
%    \end{macrocode}
%    Determine title for toc:
%    If \HASH{1} is \NOVALUE{} or \EMPTY{} use \HASH{3} for the toc-title.
%    Otherwise use \HASH{1}.
%    \begin{macrocode}
   \IfNoValueTF{#1}
         { \tl_set:Nn \l_xhead_toc_title_tl {#3} }
         { \tl_if_empty:nTF {#1}
                { \tl_set:Nn \l_xhead_toc_title_tl {#3} }
                { \tl_set:Nn \l_xhead_toc_title_tl {#1} }
         }
%    \end{macrocode}
%    Determine title for mark: If \HASH{2} is \NOVALUE{} then use whatever was
%    determined for the toc-title as value (i.e., if a special toc-title was
%    used this will be also used for the running header, if not the main title
%    is used). Otherwise, if \HASH{2} is \EMPTY{} use \HASH{3}.  Otherwise use
%    \HASH{2} (i.e., a special title was passed for the running header).
%    \begin{macrocode}
   \IfNoValueTF{#2}
         { \tl_set_eq:NN \l_xhead_mark_title_tl \l_xhead_toc_title_tl }
         { \tl_if_empty:nTF {#2}
                { \tl_set:Nn \l_xhead_mark_title_tl {#3} }
                { \tl_set:Nn \l_xhead_mark_title_tl {#2} }
         }
}
%    \end{macrocode}
%  \end{macro}
%
%
%
%
% \subsection{Support variables for template code}
%
%
%    \begin{macrocode}
\dim_new:N  \l_xhead_indent_dim
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
\skip_new:N \l_xhead_above_skip
\skip_new:N \l_xhead_below_skip
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
\int_new:N  \l_xhead_level_int
\int_new:N  \l_xhead_break_penalty_int
%    \end{macrocode}
%    
%    \begin{macrocode}
\tl_new:N   \l_xhead_name_tl
\tl_new:N   \l_xhead_number_tl
\tl_new:N   \l_xhead_toc_title_tl
\tl_new:N   \l_xhead_mark_title_tl
%    \end{macrocode}
%    
%    \begin{macrocode}
\bool_new:N \l_xhead_indent_after_bool

\cs_new:Npn \xhead_title_decl: {}

\cs_new:Npn \xhead_number_format:n #1 {}

\cs_new:Npn \xhead_default_number_format:n #1 { #1 \quad}
%    \end{macrocode}
%
%
%
%
% \subsection{The template \texttt{2e-vertical}}
%
%    \begin{macrocode}
\DeclareTemplateInterface {heading} {2e-vertical} {7}
  {
    name         : tokenlist    = ???   ,
    level        : integer      = 0     ,
    break-penalty: integer      = -300  ,
    indent       : length       = 0pt   ,
    above-skip   : skip         = 0pt   ,
    below-skip   : skip         = 0pt   ,
    title-decl   : function {0} =       ,
    number-format: function {1} = \xhead_default_number_format:n {#1}  ,
    indent-after : boolean      = false ,
  }
%    \end{macrocode}
%    
%    \begin{macrocode}
\DeclareTemplateCode {heading} {2e-vertical} {7}
  {
    name          = \l_xhead_name_tl           ,
    level         = \l_xhead_level_int         ,
    break-penalty = \l_xhead_break_penalty_int ,
    indent        = \l_xhead_indent_dim        ,
    above-skip    = \l_xhead_above_skip        ,
    below-skip    = \l_xhead_below_skip        ,
    title-decl    = \xhead_title_decl:         ,
    number-format = \xhead_number_format:n     ,
    indent-after  = \l_xhead_indent_after_bool ,
  }
  {
   \AssignTemplateKeys
%    \end{macrocode}
%    Determine title for toc and mark using the 2e logic: Do not generate
%    them if the star-form of the heading is used and always use the same text
%    for TOC and mark:
%    \begin{macrocode}
   \bool_if:NF #1
    {
      \IfNoValueTF{#2}
         { \tl_set:Nn \l_xhead_toc_title_tl {#6} }
         { \tl_set:Nn \l_xhead_toc_title_tl {#2} }
      \tl_set_eq:NN \l_xhead_mark_title_tl \l_xhead_toc_title_tl
    }
%    \end{macrocode}
%    If heading number increment counter and set |\l_xhead_number_tl|
%    \begin{macrocode}
   \xhead_update_prepare_number:N #1
%    \end{macrocode}
%    Indent after heading if requested (use old mechanism):
%    \begin{macrocode}
   \xhead_set_after_indention:N \l_xhead_indent_after_bool
%    \end{macrocode}
%    Produce the space above the heading (using old 2e methods):
%    \begin{macrocode}
   \if@noskipsec \leavevmode \fi
   \par
   \if@nobreak
     \everypar{}
   \else:
     \addpenalty \l_xhead_break_penalty_int
     \addvspace  \l_xhead_above_skip
   \fi:
%    \end{macrocode}
%    Produce the title of the heading (using old 2e methods)
%    \begin{macrocode}
   \group_begin:
     \xhead_title_decl:
       {
        \@hangfrom{\hskip \l_xhead_indent_dim \scan_stop:
                   \tl_if_empty:NF \l_xhead_number_tl
                      { \xhead_number_format:n \l_xhead_number_tl }
                  }
        \interlinepenalty \@M #6\@@par
       }
   \group_end:
%    \end{macrocode}
%    Generate toc entry and mark if required:
%    \begin{macrocode}
   \xhead_generate_toc_and_mark:NNNNNNN 
          #1 \BooleanFalse \BooleanFalse     % no forcing in 2e
          \l_xhead_name_tl 
          \l_xhead_number_tl 
          \l_xhead_toc_title_tl 
          \l_xhead_mark_title_tl
%    \end{macrocode}
%    Produce the space below the heading and the handling of following
%    paragraph (using old 2e methods):
%    \begin{macrocode}
   \par \nobreak
   \vspace \l_xhead_below_skip
   \@afterheading
   \ignorespaces
 }
%    \end{macrocode}
%
%
%
%
% \subsection{The template \texttt{3a-vertical}}
%
%    Right now this template is more or less equal to \texttt{2e-vertical}
%    except that it supports the extended heading arguments with the exception
%    of \HASH{7}.
%
%    \begin{macrocode}
\DeclareTemplateInterface {heading} {3a-vertical} {7}
  {
    name                : tokenlist                = ???   ,
    level               : integer                  = 0     ,
    break-penalty       : integer                  = -300  ,
    indent              : length                   = 0pt   ,
    above-skip          : skip                     = 0pt   ,
    below-skip          : skip                     = 0pt   ,
    format              : tokenlist                = indent-by-number   ,
    parshape            : instance {parshape}      = plain  ,
    justification       : instance {justification} = flush-left ,
    font                : tokenlist                =       ,
    number-format       : function {1}             = \xhead_default_number_format:n {#1}  ,
    indent-after        : boolean                  = false ,
  }
%    \end{macrocode}
%

%  \begin{macro}{\l_xhead_title_format_tl}
%    
%    \begin{macrocode}
\tl_new:N \l_xhead_title_format_tl
\tl_new:N \l_xhead_title_font_tl

\cs_new:Npn \xhead_title_parshape:      {}
\cs_new:Npn \xhead_title_justification: {}

%    \end{macrocode}
%  \end{macro}
%
%
%    \begin{macrocode}
\DeclareTemplateCode {heading} {3a-vertical} {7}
  {
    name                = \l_xhead_name_tl            ,
    level               = \l_xhead_level_int          ,
    break-penalty       = \l_xhead_break_penalty_int  ,
    indent              = \l_xhead_indent_dim         ,
    above-skip          = \l_xhead_above_skip         ,
    below-skip          = \l_xhead_below_skip         ,
    format              = \l_xhead_title_format_tl    ,
    parshape            = \xhead_title_parshape:      ,
    justification       = \xhead_title_justification: ,
    font                = \l_xhead_title_font_tl      ,
    number-format       = \xhead_number_format:n      ,
    indent-after        = \l_xhead_indent_after_bool  ,
  }
  {
   \AssignTemplateKeys
%    \end{macrocode}
%    Set title text for TOC and mark entry:
%    \begin{macrocode}
   \xhead_set_titles:nnn {#2} {#4} {#6}
%    \end{macrocode}
%    If heading gets a number, increment counter and set
%    |\l_xhead_number_tl|.
%    \begin{macrocode}
   \xhead_update_prepare_number:N #1
%    \end{macrocode}
%    Indent after heading if requested (use old mechanism)
%    \begin{macrocode}
   \xhead_set_after_indention:N \l_xhead_indent_after_bool
%    \end{macrocode}
%
%    Produce the space above the heading (using old 2e methods)
%
%    \begin{macrocode}
   \if@noskipsec \leavevmode \fi
   \par
   \if@nobreak
     \everypar{}
   \else:
     \addpenalty \l_xhead_break_penalty_int
     \addvspace  \l_xhead_above_skip
   \fi:
%    \end{macrocode}
%
%    Produce the title of the heading
%
%    \begin{macrocode}
   \xhead_use_title_format:nn \l_xhead_title_format_tl  {#6}

%    \end{macrocode}
%    Generate toc entry and mark:
%    \begin{macrocode}
   \xhead_generate_toc_and_mark:NNNNNNN 
          #1 #3 #5 
          \l_xhead_name_tl 
          \l_xhead_number_tl 
          \l_xhead_toc_title_tl 
          \l_xhead_mark_title_tl
%    \end{macrocode}
%    Produce the space below the heading and the handling of following
%    paragraph (using old 2e methods)
%    \begin{macrocode}
   \par \nobreak
   \vspace \l_xhead_below_skip
   \@afterheading
   \ignorespaces
 }
%    \end{macrocode}
%
%
%
%  \begin{macro}{\xhead_use_title_format:nn}
%    Select a formatting command (based on first arg string) and use it to
%    format the title (second arg). 
%
%    The formatting command makes a bunch of
%    assumptions with respect to the variable names used by the templates (it
%    might ignore some of them):
%\begin{verbatim}
%   \l_xhead_title_font_tl       : font declarations for title text
%   \l_xhead_indent_dim          : indentation from the left of title
%   \xhead_title_parshape:       : parshape instance to use for title
%   \xhead_title_justification:  : justification instance to use for title
%   \l_xhead_number_tl           : raw title number or empty
%   \xhead_number_format:n       : formatting command for title number
%\end{verbatim}
%    In addition it takes a single mandatory argument holding the title text.
%
%    \begin{macrocode}
\cs_new:Npn \xhead_use_title_format:nn #1 {
  \cs_if_exist:cTF {xhead_format_ #1:n}
     { \use:c{xhead_format_ #1:n} }
     { \ERROR xhead format not defined }
}
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\xhead_format_indent-by-number:n}
%    Implementing vertical version of |\@startsection| \ldots
%    \begin{macrocode}
\cs_new:cpn {xhead_format_indent-by-number:n} #1 {
   \group_begin:
      \l_xhead_title_font_tl 
      \hbox_set:Nn \l_tmpa_box 
                   {
                     \tl_if_empty:NF \l_xhead_number_tl
                         { \xhead_number_format:n \l_xhead_number_tl }
                   }

      \UseInstance{measure}{fullwidth} 
                  {\l_xhead_indent_dim + \box_wd:N \l_tmpa_box }

      \xhead_title_parshape: 
      \xhead_title_justification:
      \interlinepenalty \@M

      \noindent \hbox_overlap_left:n { \box_use:N \l_tmpa_box } 
       #1\@@par
   \group_end:
}
%    \end{macrocode}
%  \end{macro}
%
%
%
%
%  \begin{macro}{\xhead_format_number-above-text:n}
%    
%    \begin{macrocode}
\cs_new:cpn {xhead_format_number-above-text:n} #1 {
   \group_begin:
      \l_xhead_title_font_tl 
      \xhead_title_parshape: 
      \xhead_title_justification:
      \interlinepenalty \@M

      \tl_if_empty:NF \l_xhead_number_tl
          { 
            \xhead_number_format:n \l_xhead_number_tl
          }

       #1\@@par
   \group_end:
}
%    \end{macrocode}
%  \end{macro}
%
%    
%    \begin{macrocode}

\input{xtextblock.sty}


\DeclareTemplateInterface {heading} {3b-vertical} {7}
  {
    name                : tokenlist                = ???   ,
    level               : integer                  = 0     ,
    break-penalty       : integer                  = -300  ,
    indent              : length                   = 0pt   ,
    above-skip          : skip                     = 0pt   ,
    below-skip          : skip                     = 0pt   ,
    title-format        : instance {textblock-2}   = heading  ,
    number-format       : function {1}             = \xhead_default_number_format:n {#1}  ,
    indent-after        : boolean                  = false ,
  }

\cs_new:Npn \xhead_title_format:nn #1#2 {}

\DeclareTemplateCode {heading} {3b-vertical} {7}
  {
    name                = \l_xhead_name_tl            ,
    level               = \l_xhead_level_int          ,
    break-penalty       = \l_xhead_break_penalty_int  ,
    indent              = \l_xhead_indent_dim         ,
    above-skip          = \l_xhead_above_skip         ,
    below-skip          = \l_xhead_below_skip         ,
    title-format        = \xhead_title_format:nn      ,
    number-format       = \xhead_number_format:n      ,
    indent-after        = \l_xhead_indent_after_bool  ,
  }
  {
   \AssignTemplateKeys

   \xhead_set_titles:nnn {#2} {#4} {#6}

   \xhead_update_prepare_number:N #1

   \xhead_set_after_indention:N \l_xhead_indent_after_bool

   \if@noskipsec \leavevmode \fi
   \par
   \if@nobreak
     \everypar{}
   \else:
     \addpenalty \l_xhead_break_penalty_int
     \addvspace  \l_xhead_above_skip
   \fi:

   \xhead_title_format:nn \l_xhead_number_tl {#6}

   \xhead_generate_toc_and_mark:NNNNNNN 
          #1 #3 #5 
          \l_xhead_name_tl 
          \l_xhead_number_tl 
          \l_xhead_toc_title_tl 
          \l_xhead_mark_title_tl

   \par \nobreak
   \vspace \l_xhead_below_skip
   \@afterheading
   \ignorespaces
 }


%    \end{macrocode}
%
% \Finale
%
%    
%    \begin{macrocode}
\endinput
%</package>
%    \end{macrocode}
%
% \endinput
%
%
%
%
% \begin{TemplateInterfaceDescription}{}
%
%   \TemplateArgument{1}
%       {}
%
%   \TemplateSemantics
%
% \end{TemplateInterfaceDescription}
%
%


  - motto/quote text to display alongside the heading title
  - flag to number heading
  -label name for cross-reference

%
% \begin{InstanceDescription}[\textbf{no-page-break-boolean}xx]
%       {pshape}{staggered}{cutout}
%
%   \InstanceKey{no-page-break-boolean}{true}
%
%   \InstanceKey{left-side-boolean}{true}
%
%   \InstanceKey{normal-lines-int}{1}
%
%   \InstanceKey{parshape-list}{20pt,40pt,60pt}
%
%   \InstanceSemantics
%   This instance will indent each line by an additional 20pt (up to
%   the fourth line). A possible application would be a heading text
%   (with a maximum number of four lines).
%   This should then perhaps be combined with a special justification
%   instance which does ragged right except for the last line which is
%   set to full measure.
%
% \end{InstanceDescription}
%
%

