summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/annotate-equations
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-02-16 03:01:36 +0000
committerNorbert Preining <norbert@preining.info>2023-02-16 03:01:36 +0000
commit024d47cb1c4e5ba541f3865b69168bef20f2bfce (patch)
tree4e55e91ce72e278a079000c9871135034111f910 /macros/latex/contrib/annotate-equations
parenta7d99429152acee049db679dc26a92e01faf4992 (diff)
CTAN sync 202302160301
Diffstat (limited to 'macros/latex/contrib/annotate-equations')
-rw-r--r--macros/latex/contrib/annotate-equations/README.md7
-rw-r--r--macros/latex/contrib/annotate-equations/annotate-equations.pdfbin124665 -> 203389 bytes
-rw-r--r--macros/latex/contrib/annotate-equations/annotate-equations.sty16
-rw-r--r--macros/latex/contrib/annotate-equations/annotate-equations.tex90
4 files changed, 78 insertions, 35 deletions
diff --git a/macros/latex/contrib/annotate-equations/README.md b/macros/latex/contrib/annotate-equations/README.md
index ca25cd8b0b..9f88390701 100644
--- a/macros/latex/contrib/annotate-equations/README.md
+++ b/macros/latex/contrib/annotate-equations/README.md
@@ -1,7 +1,9 @@
# Annotate equations in LaTeX using TikZ
+( [Documentation](annotate-equations.pdf) | License: [MIT](LICENSE) | [CTAN](https://ctan.org/pkg/annotate-equations) )
+
This package provides commands that make it easy to highlight terms in equations & add annotation labels (based on TikZ).
-Should work with pdflatex as well as lualatex.
+Tested with pdflatex and lualatex, but should work with most other LaTeX engines such as xelatex as well.
Inspired by Sibin Mohan's https://github.com/synercys/annotated_latex_equations/
@@ -9,9 +11,6 @@ Please report any bugs, issues, contribute changes & improvements on https://git
Package author: ST John, http://www.infinitecuriosity.org/
-License: [MIT](LICENSE)
-
-[Documentation](annotate-equations.pdf)
## A package with reusable commands
diff --git a/macros/latex/contrib/annotate-equations/annotate-equations.pdf b/macros/latex/contrib/annotate-equations/annotate-equations.pdf
index 984daaf8ad..b29c607771 100644
--- a/macros/latex/contrib/annotate-equations/annotate-equations.pdf
+++ b/macros/latex/contrib/annotate-equations/annotate-equations.pdf
Binary files differ
diff --git a/macros/latex/contrib/annotate-equations/annotate-equations.sty b/macros/latex/contrib/annotate-equations/annotate-equations.sty
index a5dbf002f3..dbdd5f59f5 100644
--- a/macros/latex/contrib/annotate-equations/annotate-equations.sty
+++ b/macros/latex/contrib/annotate-equations/annotate-equations.sty
@@ -5,7 +5,7 @@
%
\NeedsTeXFormat{LaTeX2e}[1994/06/01]
\ProvidesPackage{annotate-equations}
- [2022/03/29 v0.1.0 easily annotate equations using TikZ]
+ [2023/02/15 v0.2.0 easily annotate equations using TikZ]
%%% lualatex compatibility, from https://tex.stackexchange.com/a/351520/171664
\RequirePackage{ifluatex}
@@ -36,7 +36,8 @@
\newcommand{\eqnhighlightshade}{17} % light
%\renewcommand{\eqnhighlightshade}{47} % dark
-\newcommand{\eqnannotationtext}[1]{\sffamily\footnotesize#1\strut} %%% TODO remove textsf/footnotesize/strut?
+\newcommand{\eqnannotationstrut}{\strut} % Package default
+\newcommand{\eqnannotationfont}{\sffamily\footnotesize}
\providecommand\EAmarkanchor{north} % default set to "above"
@@ -126,10 +127,12 @@
\def\myEAcolor{\usevalue{\myEAmarkOne}}%
\begin{tikzpicture}[overlay,remember picture,>=stealth,nodes={align=left,inner ysep=1pt},<-]
% default anchor is at center
- \node[anchor=\swapNorthSouth{\EAmarkanchor},color=\myEAcolor!85,#1] % color blended with white to 85%, any (optional) extra args #1
+ \node[anchor=\swapNorthSouth{\EAmarkanchor},color=\myEAcolor!85,
+ font=\eqnannotationfont,#1
+ ] % color blended with white to 85%, any (optional) extra args #1
(\eqnannotateCurrentNode) % use counter-based "local node"
at ($(\myEAmarkOne.\EAmarkanchor)!0.5!(\myEAmarkTwo.\EAmarkanchor)$) % centered between the two nodes
- {\eqnannotationtext{\myEAtext}};
+ {\myEAtext\eqnannotationstrut};
% double arrow to two uses within the equation:
\draw [<->,color=\myEAcolor] (\myEAmarkOne.\EAmarkanchor) |- ([yshift=0.1ex] \eqnannotateCurrentNode.\EAlabelanchor) -| (\myEAmarkTwo.\EAmarkanchor); % from node 1 via annotation to node 2, with anchor #6 each
\end{tikzpicture}%
@@ -167,11 +170,12 @@
%
\def\myEAxshift{\EAxshift{\EAwesteast}}%
\begin{tikzpicture}[overlay,remember picture,>=stealth,nodes={align=left,inner ysep=1pt},<-]
- \node[anchor=\swapNorthSouth{\EAmarkanchor} \swapWestEast{\EAwesteast},color=\myEAcolor!85,#1] % TODO for some reason, passing #1 through command doesn't work...
+ \node[anchor=\swapNorthSouth{\EAmarkanchor} \swapWestEast{\EAwesteast},
+ color=\myEAcolor!85,font=\eqnannotationfont,#1] % TODO for some reason, passing #1 through command doesn't work...
% anchor=west: align left edge of text on top of tikzmark in equation
% should be north west for below and south west for above ...
(\eqnannotateCurrentNode) at (\myEAmark.\EAmarkanchor) % \EAmarkanchor north: above the equation, south: below
- {\eqnannotationtext{\myEAtext}};
+ {\myEAtext\eqnannotationstrut};
\foreach \EAmark in \myEAmarks
\draw [color=\myEAcolor] (\EAmark.\EAmarkanchor) % arrow from the equation
% \EAmarkanchor north: above the equation, south: below
diff --git a/macros/latex/contrib/annotate-equations/annotate-equations.tex b/macros/latex/contrib/annotate-equations/annotate-equations.tex
index 2b492a36e4..26396e679e 100644
--- a/macros/latex/contrib/annotate-equations/annotate-equations.tex
+++ b/macros/latex/contrib/annotate-equations/annotate-equations.tex
@@ -50,6 +50,8 @@ This package is there to make it easier to make annotated equations in \LaTeX, s
\end{LTXexample}
There is still a bit of manual tweaking required (such as adding vertical space before/after the equation), but hopefully this package will already make it a bit more inviting to annotate your equations!
+Note that this package relies on TikZ's \texttt{remember picture} option and therefore you have to compile your \LaTeX{} document at least twice to get everything in the right place (or just use \texttt{latexmk}!).
+
\section{Marking annotation targets within your equation}
\newcommand{\cmdoption}[1]{$\langle$\textit{#1}$\rangle$}
@@ -61,7 +63,7 @@ or
to define the target of an annotation within your equation. \verb|\eqnmarkbox| adds background shading, whereas \verb|\eqnmark| changes the text color.
(You can also use
\verb|\tikzmarknode{|\cmdoption{node name}\verb|}{|\cmdoption{equation term(s)}\verb|}|,
-but this is likely to end up with the arrow tip too close to the target.)
+but this is likely to end up with the arrow tip too close to the target, so you may want to also pass the \texttt{outer ysep} option, see \cref{sec:outerysep}.)
%
\begin{LTXexample}[text outside listing,lefthand width=1in]
\begin{equation*}
@@ -94,7 +96,7 @@ For \cmdoption{annotate keys}, see \cref{sec:annotate-keys}.
\noindent
%
\label{sec:tikz-options}
-You generally need to manually adjust the \texttt{yshift} to move the annotations to an appropriate distance above (or negative values for below) the equation.
+You generally need to manually adjust the \texttt{yshift} to move the annotations to an appropriate distance above (or negative values for below) the equation. If you want an annotation below the equation, with negative \texttt{yshift}, remember to also pass the \texttt{below} option (see \cref{sec:annotate-keys}).
(You can also adjust \texttt{xshift} if needed, also positive or negative.)
The annotation picks the same text color as given to \verb|\eqnmarkbox| or \verb|\eqnmark|, but you can also override it using \texttt{color} option.
@@ -152,6 +154,7 @@ Color is picked from the first of the two nodes.
%
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
\renewcommand{\eqnhighlightheight}{} % package default
+
\begin{equation*}
\eqnmarkbox[red]{hbar}{\hbar} \eqnmarkbox[blue]{q}{q}
\end{equation*}
@@ -160,6 +163,7 @@ Color is picked from the first of the two nodes.
%
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
\renewcommand{\eqnhighlightheight}{\mathstrut} % 0-width "constant" height
+
\begin{equation*}
\eqnmarkbox[red]{hbar}{\hbar} \eqnmarkbox[blue]{q}{q}
\end{equation*}
@@ -173,6 +177,7 @@ Note that in some cases \verb|\mathstrut| might not be enough, as in the introdu
%
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
\renewcommand{\eqnhighlightheight}{\mathstrut} % 0-width "constant" height
+
\begin{equation*}
\eqnmarkbox[red]{Hhat}{\hat{H}} \eqnmarkbox[blue]{Psi}{\Psi}
\end{equation*}
@@ -183,6 +188,7 @@ You can create custom 0-width characters using \verb|\vphantom|:
%
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
\renewcommand{\eqnhighlightheight}{\vphantom{\hat{H}}\mathstrut} % custom 0-width height
+
\begin{equation*}
\eqnmarkbox[red]{Hhat}{\hat{H}} \eqnmarkbox[blue]{Psi}{\Psi}
\end{equation*}
@@ -197,6 +203,7 @@ You can create custom 0-width characters using \verb|\vphantom|:
%
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
\renewcommand{\eqnhighlightshade}{17} % package default
+
\begin{equation*}
\eqnmarkbox[red]{hbar}{\hbar} \eqnmarkbox[blue]{q}{q}
\end{equation*}
@@ -207,6 +214,7 @@ By redefining this command, you can change the ``alpha'' value of the highlight:
%
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
\renewcommand{\eqnhighlightshade}{47} % 0 is white, 100 is solid color
+
\begin{equation*}
\eqnmarkbox[red]{hbar}{\hbar} \eqnmarkbox[blue]{q}{q}
\end{equation*}
@@ -215,10 +223,9 @@ By redefining this command, you can change the ``alpha'' value of the highlight:
\subsection{Default formatting of annotation labels}
-\verb|\eqnannotationtext| is a one-argument command that gets the annotation text as an argument and can be used to have consistent formatting:
+\verb|\eqnannotationfont| sets the \texttt{font} field of the TikZ annotation label and can be re-set to change its formatting:
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
-% package default:
-\renewcommand{\eqnannotationtext}[1]{\sffamily\footnotesize#1\strut}
+\renewcommand{\eqnannotationfont}{\sffamily\footnotesize} % package default
\begin{equation*}
\eqnmarkbox[blue]{v}{v}
@@ -228,10 +235,8 @@ By redefining this command, you can change the ``alpha'' value of the highlight:
\end{LTXexample}
\noindent
%
-(The \verb|\strut| has a similar effect to \verb|\mathstrut| in \verb|\eqnhighlightheight|.)
-%
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
-\renewcommand{\eqnannotationtext}[1]{\bfseries\small#1}
+\renewcommand{\eqnannotationfont}{\bfseries\small}
\begin{equation*}
\eqnmarkbox[blue]{v}{v}
@@ -240,43 +245,78 @@ By redefining this command, you can change the ``alpha'' value of the highlight:
\vspace{1em}
\end{LTXexample}
\noindent
-%
-\section{Recommendations, tips \& tricks}
-
-\subsection{Use \texttt{\textbackslash{}colorlet} for consistent, easily changeable colors}
+\verb|\eqnannotationstrut| is defined to be a strut (zero-width height) to
+provide minimum distance between the text and the corresponding arrow line. By
+default it is \verb|\strut|, which has a similar effect to
+\verb|\mathstrut| in \verb|\eqnhighlightheight|.
-\subsection{Line breaks within annotations}
-\label{sec:multiline}
-
-Possible, but a bit annoying. By default, the formatting only covers the first line:
-%
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
+\renewcommand{\eqnannotationstrut}{\strut} % package default
+
\begin{equation*}
- \eqnmarkbox[blue]{h}{h}
+ \eqnmarkbox[blue]{size}{s}
\end{equation*}
-\annotate[yshift=-0.5em]{below}{h}{Planck\\constant}
+\annotate[yshift=-0.5em]{below}{size}{The size}
\vspace{1em}
\end{LTXexample}
\noindent
%
-Here is a manual work-around:
-%
\begin{LTXexample}[text outside listing,lefthand width=0.5in]
+\renewcommand{\eqnannotationstrut}{}
+
\begin{equation*}
- \eqnmarkbox[blue]{h}{h}
+ \eqnmarkbox[blue]{size}{s}
\end{equation*}
-\annotate[yshift=-0.5em]{below}{h}{Planck\\\sffamily\footnotesize constant}
+\annotate[yshift=-0.5em]{below}{size}{The size}
\vspace{1em}
\end{LTXexample}
+
+
+\section{Recommendations, tips \& tricks}
+
+\subsection{Use \texttt{\textbackslash{}colorlet} for consistent, easily changeable colors}
+
+
+\subsection{Relations such as ``$=$''}
+\label{sec:mathrel}
+
+Wrapping a mathematical relation symbol such as {\color{blue}$=$} in, for example, \texttt{\textbackslash{}tikzmarknode}, breaks how \TeX{} determines spacing in equations:
+\begin{LTXexample}[text outside listing,lefthand width=0.5in]
+\[
+a \tikzmarknode{node1}{=} b
+\]
+\annotate[yshift=-1em]{below}{node1}{equality}
+\end{LTXexample}
\noindent
+This can be fixed by wrapping the \texttt{\textbackslash{}tikzmarknode} in \texttt{\textbackslash{}mathrel}:
+\begin{LTXexample}[text outside listing,lefthand width=0.5in]
+\[
+a \mathrel{\tikzmarknode{node1}{=}} b
+\]
+\annotate[yshift=-1em]{below}{node1}{equality}
+\end{LTXexample}
+
+\subsection{Extra spacing between \texttt{\textbackslash{}tikzmarknode} and arrow}
+\label{sec:outerysep}
+
+If you want more space between arrow tip and annotated term, you can pass the \texttt{outer ysep} option to \texttt{\textbackslash{}tikzmarknode}:
+\begin{LTXexample}[text outside listing,lefthand width=0.5in]
+\[
+a \mathrel{\tikzmarknode[outer ysep=5pt]{node1}{=}} b
+\]
+\annotate[yshift=-1em]{below}{node1}{equality}
+\end{LTXexample}
+
+
\section{Known issues}
\begin{itemize}
- \item \texttt{label above}/\texttt{label below} not implemented for \verb|\annotate|.
+ \item \texttt{label above}/\texttt{label below} is not implemented for \verb|\annotate|.
+
+ \item Annotations of mathematical relations require some manual patching to get the correct surrounding spacing (see \cref{sec:mathrel}).
- \item Formatting only covers first line in multi-line annotation texts (see \cref{sec:multiline}).
\end{itemize}
\end{document}