new latex package abraces (3sep12)

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

2 files changed, 214 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/abraces/abraces-doc.pdf b/Master/texmf-dist/doc/latex/abraces/abraces-doc.pdf
new file mode 100644
index 00000000000..95030130faf
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/abraces/abraces-doc.pdf
diff --git a/Master/texmf-dist/doc/latex/abraces/abraces-doc.tex b/Master/texmf-dist/doc/latex/abraces/abraces-doc.tex
new file mode 100644
index 00000000000..6db0fca990f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/abraces/abraces-doc.tex
@@ -0,0 +1,214 @@
+% $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}
\ No newline at end of file