summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/underoverlap/underoverlap.tex
blob: b7fe382a09bc3ce56e6bd56d332a07d13a8939bc (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
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
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                              %
%  Copyright (c) 2013 - Michiel Helvensteijn - www.mhelvens.net                %
%                                                                              %
%  http://latex-concepts.googlecode.com                                        %
%                                                                              %
%  This work may be distributed and/or modified under the                      %
%  conditions of the LaTeX Project Public License, either                      %
%  version 1.3 of this license or (at your option) any later                   %
%  version. The latest version of this license is in                           %
%      http://www.latex-project.org/lppl.txt                                   %
%  and version 1.3 or later is part of all distributions of                    %
%  LaTeX version 2005/12/01 or later.                                          %
%                                                                              %
%  This work has the LPPL maintenance status `maintained'.                     %
%                                                                              %
%  The Current Maintainer of this work is Michiel Helvensteijn.                %
%                                                                              %
%  This work consists of the files underoverlap.tex and underoverlap.sty.      %
%                                                                              %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[a4paper]{packagedoc}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Setup                                                                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\moretexcs{%
	newUOLdecorator, UOLaugment,%
	UOLoverbrace, UOLunderbrace,%
	UOLoverline, UOLunderline,%
	UOLfbox, bigstrut%
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Global Changes                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\changes{0.0.1}{2013/02/02}
  {initial version}

\changes{0.0.1-r1}{2012/02/03}
  {several improvements in the documentation}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\maketitle

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}                                                         %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\TeX\ and \LaTeX\ provide several commands for decorating parts of our
equations---to direct attention or to indicate some special meaning. For
\hbox{example}:

\begin{latex-example-show}
\[ n \times x = \overbrace{x + \cdots + x}^n \]
\end{latex-example-show}

\noindent I'm refering to the |\overbrace|, of course. You can even nest
such commands:

\begin{latex-example-show}
\[ n \times x =
   \overbrace{x + \underbrace{x + \cdots + x}_{n-2}{} + x}^n \]
\end{latex-example-show}

\noindent But they have an inherent limitation: they cannot overlap partially. For
example, you cannot do the following out-of-the-box:
\[
	a + \UOLoverbrace{b +}[c + d]^x \UOLunderbrace{+ e}_y + f
\]
That's what this package is all about. It allows you to define new
decorator commands that can partially overlap like this, as well as
augment existing commands.

\break

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Usage}                                                                %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemetamacro{UOL decorator}{
  \marg{non-overlapping content} \oarg{overlapping content}
}

\noindent An \meta{UOL decorator} is a decorator command prepared by this
package, such as |\UOLoverbrace| and |\UOLunderbrace| in the examples below.

If you never use the optional argument at all, they should behave exactly like
the simple \TeX\ commands |\overbrace| and |\underbrace|.

As far as the `current \meta{UOL decorator}' is concerned, the optional
content is placed directly to the right of the mandatory content and both are
decorated as a whole. But a subsequent \meta{UOL decorator} will be
expected directly following this one. Its decorator will cover also the
optional content from the current command. That's how we can
typeset the example from the introduction:

\begin{latex-example-show}
\[ a + \UOLoverbrace{b +}[c + d]^x \UOLunderbrace{+ e}_y + f \]
\end{latex-example-show}

\noindent
\DescribeMacro{\UOLoverbrace}
\DescribeMacro{\UOLunderbrace}
\DescribeMacro{\UOLoverline}
\DescribeMacro{\UOLunderline}
The following \meta{UOL decorator} commands are predefined by the package,
with obvious meaning:
\begin{itemize}\parskip=0pt
  \item |\UOLoverbrace|
  \item |\UOLunderbrace|
  \item |\UOLoverline|
  \item |\UOLunderline|
\end{itemize}

\noindent Note that you are not limited to \emph{two} overlapping decorators:

\begin{latex-example-show}
\[ a + \UOLoverbrace{b +}[c]^x \UOLunderbrace{+}[d]_y
   \UOLoverbrace{+ e}^z + f \]
\end{latex-example-show}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemacro{\newUOLdecorator}{
  \marg{command sequence} \marg{definition containing\/ {\upshape|\#1|}}
}

\noindent Using this command you can create a new \meta{UOL decorator}. The
first argument is the desired command sequence and the second contains its
definition.

Define it as if a simple |\newcommand| were used for a traditional decorator.
The package will automatically augment it to allow it to overlap. You can use
|#1| to stand for the content provided by the user. The |\UOLoverline| decorator,
for example, was defined as follows:

\let\UOLoverline\relax
\begin{latex-example}
\newUOLdecorator\UOLoverline{\overline{#1}}
\end{latex-example}

\noindent But note that the result will not be satisfactory unless the decorator
requires no \emph{horizontal space} to be allocated other than for its
content. For the commands listed above, this is no problem. But this
may not be true for all native decorations.

For example, one may naively try to define a |\UOLfbox| command as follows:

\begin{latex-example}
\newUOLdecorator\UOLfbox{{%
    \fboxsep=1.2pt \fboxrule=.8pt \fbox{$#1$}%
}}
\end{latex-example}

\noindent To test it, we define the following command as well:

\begin{latex-example}
\newcommand\bigstrut{\vrule height 10pt depth 4pt width 0pt}
\end{latex-example}

\noindent The result will look like this:

\begin{latex-example-show}
\[ a + \UOLfbox{b +c +}[d]^x \UOLfbox{\bigstrut + e}^y + f \]
\end{latex-example-show}

\noindent The spacing is incorrect because |\fbox| allocates horizontal space for itself
in addition to the space for its content and our package cannot take that into
account. We'll have to correct for this manually:

\let\UOLfbox\relax
\begin{latex-example}
\newUOLdecorator\UOLfbox{{%
    \fboxsep=1.2pt \fboxrule=.8pt%
    \kern-\fboxrule \kern-\fboxsep%
    \fbox{$#1$}%
    \kern-\fboxsep  \kern-\fboxrule%
}}
\end{latex-example}

\begin{latex-example-show}
\[ a + \UOLfbox{b +c +}[d]^x \UOLfbox{\bigstrut + e}^y + f \]
\end{latex-example-show}

\noindent Much better!

Note that subscripts / superscripts will be placed directly
below / above the content, even if the original decorator did not
support that.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemacro{\UOLaugment}{
  \marg{command sequence}
}

\noindent This command can augment an existing native decorator command to
allow overlapping with its original name:

\begin{latex-example-show}
\UOLaugment\overline
\UOLaugment\overbrace
\[ a + \overline{b +}[c + d] \overbrace{\bigstrut + e}^y + f \]
\end{latex-example-show}

\noindent Note, however, the following assumptions on the original command:
\begin{itemize}
  \item It should not be a native \TeX\ command such as |\underline|.
        Augmenting |\underline| like this actually seems to work fine, but the
        \TeX\ specification can give us no guarantees about its behavior if
        we do. 
  \item It should originally only support one standard mandatory argument.
        If it already supported optional arguments or other code structures
        then that behavior will be lost after augmentation.
\end{itemize}

\noindent If these requirements are satisfied then the new command should be
\emph{almost} backwards compatible. The exceptions being, of course,
when you supply an optional argument or when it follows another
\meta{UOL decorator} that does. The other exception is the behavior of
subscripts and superscripts if the original decorator did not place them
directly below / above the content.

Of course, you can manually correct for these exceptions, but be aware
that backwards compatibility is not completely guaranteed if you simply
augment a decorator without any other measures.

This package does not `pre-augment' any commands.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemacro{\UOLunaugment}{
  \marg{command sequence}
}

\noindent Assuming that \meta{command sequence} has been augmented by the
|\UOLaugment| command, using |\UOLunaugment| reverses the effects and
\meta{command sequence} will once again have its original meaning.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Acknowledgements}                                                     %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

I originaly read the following question on \url{http://tex.stackexchange.com}:
\begin{itemize}
  \item \url{http://tex.stackexchange.com/questions/12963}
\end{itemize}
The commands of this package are partially based on the technique described by
Herbert and the command definitions proposed by Martin Scharrer.

I got a lot of useful help from the answers to my own questions too:
\begin{itemize}
  \item \url{http://tex.stackexchange.com/questions/95786}
  \item \url{http://tex.stackexchange.com/questions/95897}
\end{itemize}
Thanks in particular to David Carlisle and Hendrik Vogt.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%