% $Id: abraces-doc.tex,v 1.0 2012/08/31 00:00:00 wgrundlingh stable $
\RequirePackage{xcolor}% http://ctan.org/pkg/xcolor (required to "overload" color package)
\documentclass{ltxdockit}[2011/03/25]
%\usepackage{xspace}% http://ctan.org/pkg/xspace (already loaded by ltxdockit)
\usepackage[overload]{abraces}% http://ctan.org/pkg/abraces
\usepackage{booktabs}% http://ctan.org/pkg/booktabs
\usepackage{shortvrb}% http://ctan.org/pkg/shortvrb
\usepackage{amsmath}% http://ctan.org/pkg/amsmath
\MakeShortVerb{\|}

\rcsid{$Id: abraces.tex,v 1.0 2012/08/31 00:00:00 wgrundlingh stable $}
%\setcounter{secnumdepth}{2}
%\setcounter{tocdepth}{4}

\newsavebox{\codebox}% For storing code segments in footer.
\newcommand*{\abracesctan}{http://ctan.org/pkg/abraces}

\lstset{
  language={[LaTeX]TeX},
  morekeywords={%
    aoverbrace,
    aunderbrace,
    color,
    bracetext,
    bracescript,
    foxanddog,
    newcolumntype,
    newbracespec}
}

\titlepage{%
  title={The \sty{abraces} package},
  subtitle={Asymmetric or arbitrary braces},
  url={\abracesctan},
  author={Werner Grundlingh},
  email={latex.abraces@gmail.com},
  revision={\rcsrevision},
  date={\rcstoday}}

\hypersetup{%
  pdftitle={The abraces Package},
  pdfsubject={Asymmetric or arbitrary braces},
  pdfauthor={Werner Grundlingh},
  pdfkeywords={tex, latex, braces, overbrace, underbrace, math-mode}}

\begin{document}

\printtitlepage
%\tableofcontents

\section{Introduction} \label{intro}

The \sty{abraces}\footnote{The \sty{abraces} package: \url{http://ctan.org/pkg/abraces}} package provides a character key-driven interface to supplement new constructions of the traditional \lstinline!\overbrace! and \lstinline!\underbrace! pairs in an asymmetric or arbitrary way.

\section{User interface} \label{user-interface}

\sty{abraces} defines two counterparts to the existing braces:

\begin{ltxsyntax}

\cmditem{aoverbrace}[spec]{stuff}

\cmditem{aunderbrace}[spec]{stuff}

These create an overbrace and underbrace where \prm{spec} defines a construction pattern based on the elements in Table~\ref{tab:abrace-spec}.

The provided interface is based on a ratio-principle, allowing one to put a larger share of ``filler'' (the horizontal rule) at any location within the brace construction. The traditional \lstinline!\overbrace! and \lstinline!\underbrace! pairs have a \mbox{1:1} share between the left and right side (either side of the tip/cust of the brace). Using a \mbox{1:2} ratio would place the brace cusp one third (from the left) into the brace. Similary a \mbox{3:2} ratio would place the cusp 40\% (or two fifths) from the right edge of the brace.

Other, more complex construction -- by means of the optional \prm{spec} argument -- can also be made by mixing the elements presented in Table~\ref{tab:abrace-spec}.

\cmditem{newbracespec}{char}{spec}

This allows the user to define a new brace specification \prm{char} the results in the (possibly complex) construction \prm{spec}. The usage is similar to that of a \lstinline!\newcolumntype! construction provided by the \sty{array}\footnote{The \sty{array} package: \url{http://ctan.org/pkg/array}} package.

\cmditem{bracescript}{spec}

Since the brace cusps may not fall directly at the horizontal centre of the construction, \lstinline|\bracescript| is provided that takes a similar construction-style interface to that of \prm{spec} in \lstinline|\aoverbrace| and \lstinline|\aunderbrace|. This allows the user to position the scripted text at the location(s) best-suited for presentation.

\end{ltxsyntax}


\begin{table}[t]
  \centering
  \begin{tabular}{cl}
    \toprule
    \prm{spec} character & Output \\
    \midrule
    |l| & $\bracelu$ \\
    |L| & $\braceld$ \\
    |r| & $\braceru$ \\
    |R| & $\bracerd$ \\
    |U| & $\braceru\bracelu$ \\
    |D| & $\bracerd\braceld$ \\
    |0| & (single) Empty fill \\
    |1|, \ldots,\verb|9| & Copies of regular fill \rule[.4ex]{2em}{1.5pt} \\
    |@{|\prm{stuff}|}| & Places \prm{stuff} into brace \\
    |!{|\prm{len}|}| & Regular fill of length \prm{len} \\
    |*{|\prm{num}|}{|\prm{stuff}|}| & Repeat \prm{stuff} a total of \prm{num} times \\
    \bottomrule
  \end{tabular}
  \caption{Character specifications \prm{spec} used to construct braces.}
  \label{tab:abrace-spec}
\end{table}

If the package is loaded with the \lstinline!overload! option

\begin{lstlisting}
\usepackage[overload]{abraces}
\end{lstlisting}

\noindent the traditional \lstinline!\overbrace! and \lstinline!\underbrace! pairs are redefined to be equivalent to \lstinline!\aoverbrace! and \lstinline!\aunderbrace!, respectively, via a straight-forward \lstinline!\let!:

\begin{lstlisting}
\let\overbrace\aoverbrace
\let\underbrace\aunderbrace
\end{lstlisting}

\section{Examples}

Some examples of the types of braces that can be constructed using \sty{abraces}:

\begin{lstlisting}
\newcommand{\foxanddog}{%
  \textrm{The quick brown fox jumped over the lazy dog}}
\end{lstlisting}

\newcommand{\foxanddog}{%
  \textrm{The quick brown fox jumped over the lazy dog}}
\begin{itemize}
  \item \lstinline!\aoverbrace{\foxanddog}! (traditional \lstinline!\overbrace!): \\ $\aoverbrace{\foxanddog}$
  \item \lstinline!\aunderbrace{\foxanddog}! (traditional \lstinline!\underbrace!): \\ $\aunderbrace{\foxanddog}$
  \item \lstinline!\aoverbrace[L3U1R]{\foxanddog}!: \\ $\aoverbrace[L3U1R]{\foxanddog}$
  \item \lstinline!\aoverbrace[l1D1r]{\foxanddog}!: \\ $\aoverbrace[l1D1r]{\foxanddog}$
  \item \lstinline!\aunderbrace[l2D7r]{\foxanddog}!: \\ $\aunderbrace[l2D7r]{\foxanddog}$
  \item \lstinline!\aunderbrace[l1D2U2D1r]{\foxanddog}!: \\ $\aunderbrace[l1D2U2D1r]{\foxanddog}$
  \item \lstinline!\aoverbrace[L1R]{\foxanddog}!: \\ $\aoverbrace[L1R]{\foxanddog}$
  \item \lstinline!\aunderbrace[L1U3R]{\foxanddog}!: \\ $\aunderbrace[L1U3R]{\foxanddog}$
  \item \lstinline!\aunderbrace[l6R0l3D3r0L6r]{\foxanddog}!: \\ $\aunderbrace[l6R0l3D3r0L6r]{\foxanddog}$
  \item \lstinline!\aoverbrace[L5*{3}{01}05U50*{3}{10}5R]{\foxanddog}!: \\ $\aoverbrace[L5*{3}{01}05U50*{3}{10}5R]{\foxanddog}$
  \item \lstinline!\aunderbrace[l1@{\hspace{5em}}2D2@{\hspace{3em}}1r]{\foxanddog}!: \\ $\aunderbrace[l1@{\hspace{5em}}2D2@{\hspace{3em}}1r]{\foxanddog}$
  \item \lstinline~\aunderbrace[l1R@{\color{red!80!white}}L1r]{\foxanddog}~: \\ $\aunderbrace[l1R@{\color{red!80!white}}L1r]{\foxanddog}$
  \item \lstinline~\aoverbrace[L1D!{5em}R]{\foxanddog}~: \\ $\aoverbrace[L1D!{5em}R]{\foxanddog}$
\end{itemize}

The next question might be how to add content to the brace cusps. Here's a possible way to insert text at the appropriate ratio, using the above construction techniques:

\newcommand{\bracetext}[1]{%
  \makebox[0pt][c]{\scriptsize#1}}%
\[
  \overbrace[L2U2D1U1R]{\foxanddog}^{%
    \bracescript{L2r@{\bracetext{left}}l2D1r@{\bracetext{right}}l1R}%
    }%
\]

\begin{lstlisting}
\newcommand{\bracetext}[1]{%
  \makebox[0pt][c]{\scriptsize#1}}%
\[
  \overbrace[L2U2D1U1R]{\foxanddog}^{%
    \bracescript{L2r@{\bracetext{left}}l2D1r@{\bracetext{right}}l1R}%
    }%
\]
\end{lstlisting}

\begin{lrbox}{\codebox}\footnotesize\lstinline!\overbrace!\end{lrbox}% Capture code in \codebox
Another usage might include ``breaking'' a brace across lines to indicate a continuous grouping of objects. The following example\footnote{Taken from the question \href{http://tex.stackexchange.com/q/25510/5764}{\usebox{\codebox} split across multiple lines} on the TeX StackExchange network.} constructs two open-ended \lstinline!\aoverbrace!s which ``spans'' multiple lines:

\begin{multline*}
  f(x)=a_0+a_1x+a_2x^2+
    \aoverbrace[L1U1]{a_3x^3+a_4x^4+\cdots+a_{i-1}x^{i-1}+\hspace{1em}}^
      {\bracescript{L1r@{\bracetext{some text}}l1}} \\[\jot]
    \aoverbrace[1R]{\hspace{1em}a_ix^i+a_{i+1}x^{i+1}}+\cdots+a_{n-1}x^{n-1}
\end{multline*}

\begin{lstlisting}
\usepackage{amsmath}% http://ctan.org/pkg/amsmath
%...
\begin{multline*}
  f(x)=a_0+a_1x+a_2x^2+
    \aoverbrace[L1U1]{a_3x^3+a_4x^4+\cdots+a_{i-1}x^{i-1}+\hspace{1em}}^
      {\bracescript{L1r@{\bracetext{some text}}l1}} \\[\jot]
    \aoverbrace[1R]{\hspace{1em}a_ix^i+a_{i+1}x^{i+1}}+
      \cdots+a_{n-1}x^{n-1}
\end{multline*}
\end{lstlisting}

As a final example, consider a brace that should include a dashed component. Using \lstinline|\newbracespec| one can define your own dashed component:

\begin{lstlisting}
\newbracespec{d}{%
  5@{\hspace{4pt}}1@{\hspace{4pt}}!{2em}@{\hspace{4pt}}1@{\hspace{4pt}}5%
}
\end{lstlisting}

\noindent and then use

\begin{lstlisting}
\[
  \aunderbrace[l*{3}{d}D*{3}{d}r]{\foxanddog}_
    {\bracetext{What happened to the cat?}}
\]
\end{lstlisting}

\newbracespec{d}{1@{\hspace{4pt}}1@{\hspace{4pt}}!{1em}@{\hspace{4pt}}1@{\hspace{4pt}}1}

\[ \aunderbrace[l*{3}{d}D*{3}{d}r]{\foxanddog}_{\bracetext{What happened to the cat?}} \]

\section{Terms of reference}

This package originated from a question on the TeX StackEchange network called \href{http://tex.stackexchange.com/q/68526/5764}{Asymmetric overbrace}. Some code was taken from the \sty{mathtools}\footnote{The \sty{mathtools} package: \url{http://ctan.org/pkg/mathtools}} package.

This material is released under and subject to the \href{http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html}{LaTeX Project Public Licence}.

\end{document}