diff options
author | Norbert Preining <norbert@preining.info> | 2023-02-16 03:01:36 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-02-16 03:01:36 +0000 |
commit | 024d47cb1c4e5ba541f3865b69168bef20f2bfce (patch) | |
tree | 4e55e91ce72e278a079000c9871135034111f910 /macros/latex/contrib/annotate-equations | |
parent | a7d99429152acee049db679dc26a92e01faf4992 (diff) |
CTAN sync 202302160301
Diffstat (limited to 'macros/latex/contrib/annotate-equations')
-rw-r--r-- | macros/latex/contrib/annotate-equations/README.md | 7 | ||||
-rw-r--r-- | macros/latex/contrib/annotate-equations/annotate-equations.pdf | bin | 124665 -> 203389 bytes | |||
-rw-r--r-- | macros/latex/contrib/annotate-equations/annotate-equations.sty | 16 | ||||
-rw-r--r-- | macros/latex/contrib/annotate-equations/annotate-equations.tex | 90 |
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 Binary files differindex 984daaf8ad..b29c607771 100644 --- a/macros/latex/contrib/annotate-equations/annotate-equations.pdf +++ b/macros/latex/contrib/annotate-equations/annotate-equations.pdf 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} |