% $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}