texlive[65851] Master/texmf-dist: annotate-equations (16feb23)

commits+karl at tug.org commits+karl at tug.org
Thu Feb 16 22:34:36 CET 2023 

Revision: 65851
          http://tug.org/svn/texlive?view=revision&revision=65851
Author:   karl
Date:     2023-02-16 22:34:35 +0100 (Thu, 16 Feb 2023)
Log Message:
-----------
annotate-equations (16feb23)

Modified Paths:
--------------
    trunk/Master/texmf-dist/doc/latex/annotate-equations/README.md
    trunk/Master/texmf-dist/doc/latex/annotate-equations/annotate-equations.pdf
    trunk/Master/texmf-dist/doc/latex/annotate-equations/annotate-equations.tex
    trunk/Master/texmf-dist/tex/latex/annotate-equations/annotate-equations.sty

Modified: trunk/Master/texmf-dist/doc/latex/annotate-equations/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/annotate-equations/README.md	2023-02-16 00:49:24 UTC (rev 65850)
+++ trunk/Master/texmf-dist/doc/latex/annotate-equations/README.md	2023-02-16 21:34:35 UTC (rev 65851)
@@ -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,10 +11,7 @@
 
 Package author: ST John, http://www.infinitecuriosity.org/
 
-License: [MIT](LICENSE)
 
-[Documentation](annotate-equations.pdf)
-
 ## A package with reusable commands
 
 ![rendering of annotated equation](examples/example_annotation_package.png)

Modified: trunk/Master/texmf-dist/doc/latex/annotate-equations/annotate-equations.pdf
===================================================================
(Binary files differ)

Modified: trunk/Master/texmf-dist/doc/latex/annotate-equations/annotate-equations.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/annotate-equations/annotate-equations.tex	2023-02-16 00:49:24 UTC (rev 65850)
+++ trunk/Master/texmf-dist/doc/latex/annotate-equations/annotate-equations.tex	2023-02-16 21:34:35 UTC (rev 65851)
@@ -50,6 +50,8 @@
 \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 @@
 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 @@
 \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 @@
 %
 \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 @@
 %
 \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 @@
 %
 \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 @@
 %
 \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 @@
 %
 \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 @@
 %
 \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 @@
 
 \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 @@
 \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 @@
 \vspace{1em}
 \end{LTXexample}
 \noindent
-%
 
-\section{Recommendations, tips \& tricks}
+\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{Use \texttt{\textbackslash{}colorlet} for consistent, easily changeable colors}
+\begin{LTXexample}[text outside listing,lefthand width=0.5in]
+\renewcommand{\eqnannotationstrut}{\strut}  % package default
 
-\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]
 \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 Formatting only covers first line in multi-line annotation texts (see \cref{sec:multiline}).
+    \item Annotations of mathematical relations require some manual patching to get the correct surrounding spacing (see \cref{sec:mathrel}).
+
 \end{itemize}
 
 \end{document}

Modified: trunk/Master/texmf-dist/tex/latex/annotate-equations/annotate-equations.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/annotate-equations/annotate-equations.sty	2023-02-16 00:49:24 UTC (rev 65850)
+++ trunk/Master/texmf-dist/tex/latex/annotate-equations/annotate-equations.sty	2023-02-16 21:34:35 UTC (rev 65851)
@@ -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

More information about the tex-live-commits mailing list.