summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/abraces/abraces-doc.tex
blob: 6db0fca990f46c7adde524ee583ec9309f9cfa15 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
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}