-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathabraces-doc.tex
343 lines (268 loc) · 16.2 KB
/
abraces-doc.tex
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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
% $Id: abraces-doc.tex,v 2.2 2024/08/02 00:00:00 wgrundlingh stable $
\RequirePackage{xcolor}% http://ctan.org/pkg/xcolor (required to "overload" color package)
\documentclass[10pt]{ltxdockit}[2011/03/25]
%\usepackage{xspace}% Already loaded by ltxdockit
\usepackage[overload]{abraces}
\usepackage{booktabs,shortvrb,amsmath,xfp}
\MakeShortVerb{\|}
\rcsid{$Id: abraces.tex,v 2.2 2024/08/02 00:00:00 wgrundlingh stable $}
%\setcounter{secnumdepth}{2}
%\setcounter{tocdepth}{4}
% https://tex.stackexchange.com/a/472150/5764
% Use cases for breaking a paragraph that is not visible to the end user, forcing the paragraph to be set with a full-width/-length
% last line. Then one could insert a \pagebreak if needed, depending on the layout requirements
\newcommand{\parnopar}[1][]{\parfillskip=0pt\par%
#1%
\parskip=0pt\noindent\parfillskip=0pt plus1fil}
\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,
FnD,
newcolumntype,
newbracespec,
bracecolor,
color,
textcolor,
aftergroup,
text}
}
\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 (latex.abraces@gmail.com)},
pdfkeywords={tex, latex, braces, overbrace, underbrace, math-mode}}
\usepackage{parskip}
\newlength{\bracecusplen}
\settowidth{\bracecusplen}{$\braceru\bracelu$}
\begin{document}
\printtitlepage
%\tableofcontents
\section{Introduction} \label{sec:introduction}
The \href{http://ctan.org/pkg/abraces}{\sty{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{Basic user interface} \label{sec:user-interface}
This package defines two counterparts to the existing braces:
\begin{ltxsyntax}
\cmditem{aoverbrace}[brace spec]{stuff}[script spec]\lstinline!^{!\prm{upper script}\lstinline!}_{!\prm{lower script}\lstinline!}!
\cmditem{aunderbrace}[brace spec]{stuff}[script spec]\lstinline!^{!\prm{upper script}\lstinline!}_{!\prm{lower script}\lstinline!}!
\end{ltxsyntax}
Note that both the \prm{brace spec} and \prm{script spec} arguments are optional, as well as the use of an \prm{upper script} and \prm{lower script}. As such, in its most basic form, \lstinline!\aoverbrace{!\prm{stuff}\lstinline!}! (and \lstinline!\aunderbrace{!\prm{stuff}\lstinline!}!) would be similar to the traditional \lstinline!\overbrace{!\prm{stuff}\lstinline!}! (and \lstinline!\underbrace{!\prm{stuff}\lstinline!}!). However, if you specify a \prm{brace spec} -- a construction pattern based on the elements in \hyperref[tab:abrace-spec]{Table~\ref*{tab:abrace-spec}} -- you could adjust the shape of the brace in an arbitrary way. These definitions are robust.
The \prm{brace spec} 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/cusp of the brace), thereby forcing the tip/cust to be placed directly in the center horizontally. With \lstinline!abraces!, 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. The same holds for elements specified within \prm{script spec}, except these are used to alter the location of the scrips. For more detail, see section \hyperref[sec:advanced-interface]{\ref*{sec:advanced-interface}~\nameref*{sec:advanced-interface}}.
Other, more complex constructions are possible by mixing the elements presented in \hyperref[tab:abrace-spec]{Table~\ref*{tab:abrace-spec}}. See section \hyperref[sec:examples]{\ref*{sec:examples} \nameref*{sec:examples}} for a showcase of uses.
\begin{ltxsyntax}
\cmditem{newbracespec}{char}{brace spec}
\end{ltxsyntax}
This allows the user to define a new brace specification \prm{char} that results in the (possibly complex) construction \prm{brace spec}. Note that \prm{char} should be different from any already used (see \hyperref[tab:abrace-spec]{Table~\ref*{tab:abrace-spec}}). The usage is similar to that of a \lstinline!\newcolumntype! construction provided by the \href{http://ctan.org/pkg/array}{\sty{array} package}.
\begin{table}[t]
\centering
\makeatletter
\begin{tabular}{cl}
\toprule
\prm{spec} character & Output \\
\midrule
|l| & $\bracelu$ (left upward brace) \\
|L| & $\braceld$ (left downward brace) \\
|r| & $\braceru$ (right upward brace) \\
|R| & $\bracerd$ (right downward brace)\\
|U| & $\braceru\bracelu$ (upward cusp) \\
|D| & $\bracerd\braceld$ (downward cusp) \\
|,[|\prm{len}|]| & % Similar to \downbracketend in abraces.sty
\sbox\z@{$\braceld$}\dimen@\ht\z@ \advance\dimen@.7\fontdimen5\textfont2\relax
\vrule \@width\ht\z@ \@height\ht\z@ \@depth\dimexpr\dimen@-\ht\z@\ (downward end with optional \prm{len}gth control) \\
|'[|\prm{len}|]| & % Similar to \upbracketend in abraces.sty
\sbox\z@{$\bracelu$}\dimen@\ht\z@ \advance\dimen@.7\fontdimen5\textfont2\relax
\vrule \@width\ht\z@ \@height\dimen@ \@depth\z@\ (upward end with optional \prm{len}gth control) \\
|0| & (single) Empty fill \\
|1|, \ldots, |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}
\makeatother
\caption{Character specifications within \prm{brace spec} used to construct braces.}
\label{tab:abrace-spec}
\end{table}
By default, any scripts will be placed at the cusp (|D| when providing a \prm{lower script} via \lstinline|_| or |U| when providing an \prm{upper script} via \lstinline|^|) of the brace. If you use more than one cusp within your \prm{brace spec}, you can separate scripts using \lstinline!&! which will place them above/below subsequent brace cusps, similar to separating columns within a \lstinline!tabular!.
\begin{ltxsyntax}
\cmditem{bracecolor}{spec}
\end{ltxsyntax}
If you're interested in using any form of colour, \lstinline|\bracecolor| will allow you to change the brace colour via an \lstinline!@!-insertion (for example, \lstinline!@{\bracecolor{red}}! would yield a \textcolor{red}{red} brace from that point onward). Regular script colouring can still be achieved using \lstinline!\color! or \lstinline!\textcolor!. The motivation here is that elements within the \lstinline!@!-insertions are grouped; \lstinline!\bracecolor! uses \lstinline!\aftergroup! to re-insert the use of \lstinline!\color!.
If the package is loaded with the \lstinline!overload! option
\begin{lstlisting}
\usepackage[overload]{abraces}
\end{lstlisting}
the traditional \lstinline!\overbrace!/\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{Advanced uses} \label{sec:advanced-interface}
There are some cases where you don't want to place elements exactly at the tip(s) of the brace(s). Maybe it's because you don't have any tips on your braces, or need to write other information around the tips. To that end, the second optional \prm{script spec} argument is provided where you can specify a new sequence that may differ from the original brace specification. Without any tips, for example, one could write \lstinline!$\aoverbrace[L1R]{a + b + \cdots +!\parnopar\lstinline!z}[U]^{\text{26 terms}}$! to denote a grouping of elements:
\[
\aoverbrace[L1R]{a + b + \cdots + z}[U]^{\text{26 terms}}
\]
More detailed examples are covered in section \hyperref[sec:examples]{\ref*{sec:examples}~\nameref*{sec:examples}}.
\section{Examples} \label{sec:examples}
Some basic examples of the types of braces that can be constructed using \sty{abraces}:
\begin{lstlisting}
\newcommand{\FnD}{%
\textrm{The quick brown fox jumped over the lazy dog}}
\end{lstlisting}
\newcommand{\FnD}{%
\textrm{The quick brown fox jumped over the lazy dog}}
\begin{itemize}
\item \lstinline!\aoverbrace{\FnD}! (traditional \lstinline!\overbrace!): \\
$\aoverbrace{\FnD}$
\item \lstinline!\aunderbrace{\FnD}! (traditional \lstinline!\underbrace!): \\
$\aunderbrace{\FnD}$
\item \lstinline!\aoverbrace[L3U1R]{\FnD}!: \\
$\aoverbrace[L3U1R]{\FnD}$
\item \lstinline!\aoverbrace[*{6}{0}l1D1r*{5}{0}]{\FnD}!: \\
$\aoverbrace[*{6}{0}l1D1r*{5}{0}]{\FnD}$
\item \lstinline~\aunderbrace[l2D1r000@{\bracecolor{blue!70!black}}l1D2r]{\FnD}~: \\
$\aunderbrace[l2D1r000@{\bracecolor{blue!70!black}}l1D2r]{\FnD}$
\item \lstinline!\aunderbrace[l1D2U2D1r]{\FnD}!: \\
$\aunderbrace[l1D2U2D1r]{\FnD}$
\item \lstinline!\aoverbrace[L1R]{\FnD}!: \\
$\aoverbrace[L1R]{\FnD}$
\item \lstinline!\aunderbrace[L1U3R]{\FnD}!: \\
$\aunderbrace[L1U3R]{\FnD}$
\item \lstinline!\aunderbrace['6,0l3D3r0,6']{\FnD}!: \\
$\aunderbrace['6,0l3D3r0,6']{\FnD}$
\item \lstinline!\aoverbrace[L5*{3}{01}05U50*{3}{10}5R]{\FnD}!: \\
$\aoverbrace[L5*{3}{01}05U50*{3}{10}5R]{\FnD}$
\item \lstinline!\aunderbrace[l1@{\hspace{5em}}2D2@{~\ldots~}1r]{\FnD}!: \\
$\aunderbrace[l1@{\hspace{5em}}2D2@{~\ldots~}1r]{\FnD}$
\item \lstinline~\aunderbrace[l1R@{\bracecolor{red!80!white}}L1r]{\FnD}~: \\
$\aunderbrace[l1R@{\bracecolor{red!80!white}}L1r]{\FnD}$
\item \lstinline~\aoverbrace[,1D!{5em},]{\FnD}~: \\
$\aoverbrace[,1D!{5em},]{\FnD}$
\end{itemize}
Some more advanced techniques of adding content to the brace cusps:
\begin{itemize}
\item \lstinline!\aoverbrace[L1U2R]{\FnD}^{\text{one-third of the way}}!: \\
$\aoverbrace[L1U2R]{\FnD}^{\text{one-third of the way}}$
\item \lstinline!\aoverbrace[L1U1D1U1R]{\FnD}^{\text{left} & \text{right}}!: \\
$\aoverbrace[L1U1D1U1R]{\FnD}^{\text{left} & \text{right}}$
\item \lstinline!\aoverbrace[L1U1D1U1R]{\FnD}! \\
\quad\lstinline![L1U1U1U1R]^{\text{left} & \text{middle} & \text{right}}!: \\
$\aoverbrace[L1U1D1U1R]{\FnD}[L*{3}{1U}1R]^{\text{left} & \text{middle} & \text{right}}$
\item
\newcommand{\ind}[1][1]{\hspace*{\fpeval{#1*1.5}em}}%
\lstinline!\newbracespec{u}! \\
\ind\lstinline!{@{\hspace{-.5\bracecusplen}}U@{\hspace{-.5\bracecusplen}}}! \\
\lstinline!\newbracespec{d}! \\
\ind\lstinline!{@{\hspace{-.5\bracecusplen}}D@{\hspace{-.5\bracecusplen}}}! \\
\lstinline!$\aunderbrace! \\
\ind[1]\lstinline![00l2@{\hspace{-\bracecusplen}}1r]{% \aunderbrace brace script! \\
\ind[2]\lstinline!\aoverbrace! \\
\ind[3]\lstinline![L1@{\hspace{-\bracecusplen}}1R000]% \aoverbrace brace script! \\
\ind[3]\lstinline!{\FnD}% stuff! \\
\ind[3]\lstinline![1u13]% \aoverbrace script spec! \\
\ind[3]\lstinline!^{2/5}% \aoverbrace upper script! \\
\ind\lstinline!}! \\
\lstinline![43d3]% \aunderbrace script spec! \\
\lstinline!_{3/5}$% \aunderbrace lower script!: \\
\newbracespec{u}{@{\hspace{-.5\bracecusplen}}U@{\hspace{-.5\bracecusplen}}}%
\newbracespec{d}{@{\hspace{-.5\bracecusplen}}D@{\hspace{-.5\bracecusplen}}}%
$\aunderbrace
[00l2@{\hspace{-\bracecusplen}}1r]{% \aunderbrace brace script
\aoverbrace
[L1@{\hspace{-\bracecusplen}}1R000]% \aoverbrace brace script
{\FnD}% stuff
[1u13]% \aoverbrace script spec
^{2/5}% \aoverbrace upper script
}
[43d3]% \aunderbrace script spec
_{3/5}$% \aunderbrace lower script
\item
\lstinline!\newbracespec{a}{@{\hspace{-.5\bracecusplen}}D}! \\
\quad\lstinline!\newbracespec{z}{D@{\hspace{-.5\bracecusplen}}}! \\
\quad\lstinline!\aunderbrace[l1r]{\FnD}! \\
\quad\quad\lstinline![a1z]_{\text{\rlap{far left}} & \text{\llap{far right}}}!: \\
\newbracespec{a}{@{\hspace{-.5\bracecusplen}}D}%
\newbracespec{z}{D@{\hspace{-.5\bracecusplen}}}%
$\aunderbrace[l1r]{\FnD}[a1z]_{\text{\rlap{far left}} & \text{\llap{far right}}}$
\end{itemize}
\begin{lrbox}{\codebox}\footnotesize\lstinline!\overbrace!\end{lrbox}% Capture code in \codebox
Here is a real-world example where ``breaking'' a brace across lines is required to indicate a continuous grouping of objects. This 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 that ``span'' multiple lines:
\begin{multline*}
f(x) = a_0 + a_1 x + a_2 x^2 +
\aoverbrace[L1U1@{~\ldots}]{a_3 x^3 + a_4 x^4 + \dots +
a_{i - 1} x^{i - 1} + \quad}^
{\text{some text}} \\[\jot]
\aoverbrace[@{\ldots~}1R]{\quad a_i x^i + a_{i + 1} x^{i + 1}} +
\dots + a_{n - 1} x^{n - 1}
\end{multline*}
\begin{lstlisting}
\usepackage{amsmath}% http://ctan.org/pkg/amsmath
%...
\begin{multline*}
f(x) = a_0 + a_1 x + a_2 x^2 +
\aoverbrace[L1U1@{~\ldots}]{a_3 x^3 + a_4 x^4 + \dots +
a_{i - 1} x^{i - 1} + \quad}^
{\text{some text}} \\[\jot]
\aoverbrace[@{\ldots~}1R]{\quad a_i x^i + a_{i + 1} x^{i + 1}} +
\dots + 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]{\FnD}_{\text{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]{\FnD}_{\text{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 \href{http://ctan.org/pkg/mathtools}{\sty{mathtools} package}.
This material is released under and subject to the \href{https://latex-project.org/lppl/}{LaTeX Project Public Licence}.
\section{Acknowledgements}
Thanks to Frank Mittlebach who stepped in and suggested an improvement in the original way \sty{abraces} functioned. Expansions included the use of \LaTeX3 command interface.
\section{Change log}
\begin{itemize}
\item v2.2 (2024-08-02) Minor update
\begin{itemize}
\item
Added \href{http://ctan.org/pkg/xcolor}{\sty{xcolor}} dependency to always have \lstinline|\bracecolor| available.
\end{itemize}
\item v2.1 (2022-11-06) Minor update
\begin{itemize}
\item
\lstinline|\Repeat| is replaced by something more obscure (\lstinline|\Repeat@br@ces|) to avoid other package conflicts.
\end{itemize}
\item v2.0 (2021-03-31) Major update
\begin{itemize}
\item
The package now uses \href{http://ctan.org/pkg/xparse}{\sty{xparse}} for macro definitions.
\item
Included an automated way for handling elementary/default scripts. The placement of scripts can still be modified using the \lstinline|\bracescript| interface.
\item
The documentation was also updated to reflect the changes.
\end{itemize}
\item v1.0 (2012-08-31) Initial release
\end{itemize}
\end{document}