From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Mon, 2 Sep 2019 13:46:59 +0900
Subject: Initial commit

---
 macros/latex/contrib/underoverlap/underoverlap.tex | 267 +++++++++++++++++++++
 1 file changed, 267 insertions(+)
 create mode 100644 macros/latex/contrib/underoverlap/underoverlap.tex

(limited to 'macros/latex/contrib/underoverlap/underoverlap.tex')

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}                                                                 %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-- 
cgit v1.2.3

