summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/underoverlap/underoverlap.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/underoverlap/underoverlap.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/underoverlap/underoverlap.tex')
-rw-r--r--macros/latex/contrib/underoverlap/underoverlap.tex267
1 files changed, 267 insertions, 0 deletions
diff --git a/macros/latex/contrib/underoverlap/underoverlap.tex b/macros/latex/contrib/underoverlap/underoverlap.tex
new file mode 100644
index 0000000000..b7fe382a09
--- /dev/null
+++ b/macros/latex/contrib/underoverlap/underoverlap.tex
@@ -0,0 +1,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} %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%