eqannotate.tex

\documentclass[11pt]{article}
\usepackage[margin=28mm]{geometry}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{xcolor}
\usepackage{hyperref}
\usepackage{eqannotate}
\hypersetup{colorlinks=true,linkcolor=blue!50!black,urlcolor=blue!50!black,pdftitle={EqAnnotate User Manual}}
\newcommand{\pkg}{\textsf{eqannotate}}
\newcommand{\cmd}[1]{\texttt{\string#1}}
\title{\pkg\\\large Declarative equation annotations with automatic layout}
\author{EqAnnotate contributors}
\date{Version v0.1.1 \quad 2026-08-28}
\begin{document}
\maketitle
\begin{abstract}
\pkg{} is a LaTeX package for labelled display mathematics. Mark a term,
declare its meaning, and let the package arrange the annotation. This manual
documents the stable v0.1.1 user interface.
\end{abstract}
\tableofcontents

\section{Introduction}
EqAnnotate is for \emph{display} equations. Its normal workflow is: mark a
term, declare a label, then compile to convergence. Automatic layout is the
default workflow, with manual placement available when exact control is useful.

\section{Installation}
Place \texttt{eqannotate.sty} beside the main document and write:
\begin{verbatim}
\usepackage{eqannotate}
\end{verbatim}
For a user TeX tree, install it below \texttt{tex/latex/eqannotate/}.
Requirements are LaTeX2e, \textsf{amsmath}, \textsf{xcolor}, TikZ with
\texttt{tikzmark}, \texttt{arrows.meta}, and \texttt{calc}, plus
\textsf{expl3}/\textsf{xparse}. The tested engines are pdfLaTeX, LuaLaTeX,
and XeLaTeX.

\section{Quick start}
\begin{annotatedequation}
p(x)=\frac{1}{\sqrt{2\pi}\eqmark[blue]{sigma}{\sigma}}
\exp\left(-\frac{(x-\eqmark[yellow]{mu}{\mu})^2}{2\sigma^2}\right)

\eqannotate{mu}{Mean}
\eqannotate{sigma}{Scale}
\end{annotatedequation}
Mark identifiers are local to one display. The declarations may follow the
formula in any order.

\section{Core API}
\subsection{Marking terms}
\begin{verbatim}
\eqmark[<color>]{<id>}{<math>}
\end{verbatim}
The optional color is used by the colorful theme. IDs are semantic names local
to one wrapper. Duplicate marks keep the first target and issue a warning.

\subsection{Automatic labels}
\begin{verbatim}
\eqannotate[prefer=auto|above|below]{<id>}{<label>}
\end{verbatim}
The optional \texttt{prefer} value is a soft side preference interpreted by the
automatic layout solver.
A label with no matching mark is skipped with a warning.

\section{Display environments}
Four wrappers are available:
\begin{description}
\item[\texttt{annotatedequation}] A single display.
\item[\texttt{annotatedalign}] A multi-row aligned display.
\item[\texttt{annotatedgather}] A centered multi-row display.
\item[\texttt{annotatedmultline}] A long display split across rows.
\end{description}
The wrappers are unnumbered by default. With \texttt{[numbered]}, the entire
block receives one equation number; ordinary \cmd{\label} and \cmd{\ref} work
as usual.

\begin{annotatedalign}[numbered]
r_0 &= \eqmark[blue]{initial}{x_0-y},\\
r_{k+1} &= r_k-\eqmark[orange]{update}{\alpha_k A p_k},\\
x_{k+1} &= x_k+\eqmark[green]{step}{\alpha_k p_k}

\eqannotate{initial}{Initial residual}
\eqannotate{update}{Residual correction}
\eqannotate{step}{State update}
\label{eq:aligned-example}
\end{annotatedalign}
Equation~\ref{eq:aligned-example} is one numbered aligned block.

\begin{annotatedgather}
E(x)=\eqmark[blue]{energy}{D(x)}+R(x),\\
\nabla E(x)=\eqmark[orange]{gradient}{\nabla D(x)+\nabla R(x)}

\eqannotate{energy}{Energy objective}
\eqannotate{gradient}{Objective gradient}
\end{annotatedgather}

\begin{annotatedmultline}
\eqmark[blue]{objective}{\mathcal{L}(\theta)}
=\mathrm{E}_{x\sim p_{\rm data}}\!\left[\ell_{\rm rec}(x;\theta)\right]
+\eqmark[orange]{adversarial}{\lambda_1\mathrm{E}_{z\sim p(z)}\!\left[\ell_{\rm adv}(z;\theta)\right]}\\
{}+\lambda_2\mathcal{L}_{\rm consistency}(\theta)
+\lambda_3\mathrm{E}_{t}\!\left[\|v_\theta(x_t,t)-u_t\|_2^2\right]
+\eqmark[green]{prior}{\lambda_4\mathcal{R}_{\rm prior}(\theta)}

\eqannotate{objective}{Total training objective}
\eqannotate{adversarial}{Adversarial objective}
\eqannotate{prior}{Prior regularizer}
\end{annotatedmultline}
The multline wrapper retains multline-style first/last-row alignment. Use
\texttt{annotatedalign} for short expressions that need aligned rows.
It also supports the native commands \cmd{\shoveleft} and \cmd{\shoveright}.

\section{Automatic layout}
Automatic placement chooses sides, wraps long labels, performs bounded
horizontal de-overlap, allocates lanes, routes connectors, observes the active
local \cmd{\linewidth}, and reserves vertical space.

\begin{annotatedequation}
\mathcal{J}=\eqmark[blue]{data}{\mathcal{L}_{\rm data}}
{}+\eqmark[orange]{regularization}{\lambda\mathcal{L}_{\rm reg}}
{}+\eqmark[green]{auxiliary}{\gamma\mathcal{L}_{\rm aux}}
{}+\eqmark[purple]{prior}{\rho\mathcal{R}(\theta)}

\eqannotate{data}{Data fidelity}
\eqannotate{regularization}{Regularization}
\eqannotate{auxiliary}{Auxiliary objective}
\eqannotate{prior}{Prior term}
\end{annotatedequation}

\section{Themes and callout styles}
\begin{verbatim}
\eqannotatecolortheme{colorful} % or mono
\eqannotatecalloutstyle{leader} % or arrow
\end{verbatim}
In \texttt{colorful}, marked terms have pastel backgrounds and related labels
and connectors share their colors. In \texttt{mono}, term backgrounds are
removed and callouts are black. A \texttt{leader} is a plain connector; an
\texttt{arrow} points toward the target.

\section{Manual placement}
\begin{verbatim}
\eqannotatemanual[<label TikZ options>][<to-path options>]
  {<id>}{<label>}
\end{verbatim}
Use manual placement to set a label position or connector route explicitly:
\begin{annotatedequation}
y=\eqmark[blue]{model}{f_\theta(x)}+\eqmark[orange]{correction}{\lambda g(x)}

\eqannotate{model}{Base model}
\eqannotatemanual[xshift=18mm,yshift=12mm][bend right=18]
  {correction}{Manually positioned correction}
\end{annotatedequation}
The supplied TikZ options set the label position and connector route. Manual
labels use the active theme, callout style, masking, and vertical space
reservation. If automatic and manual declarations target the same ID, the
manual declaration takes precedence and the package emits a warning.

\section{Numbering and references}
Numbered aligned and gathered wrappers give the entire block one equation
number. \texttt{annotatedmultline} follows the same one-number model as
\textsf{amsmath} \texttt{multline}. Place \cmd{\label} inside a numbered
wrapper and reference it normally.

\section{Compilation and convergence}
Use a normal workflow such as:
\begin{verbatim}
latexmk -pdf main.tex
\end{verbatim}
When compiling by hand, rerun while the log reports
\begin{quote}
\ttfamily Rerun LaTeX for optimized annotation spacing.
\end{quote}
The package uses remembered positions and the \texttt{.aux} file, so a fresh
document commonly needs multiple passes.

\section{Diagnostics}
Diagnostics cover a missing mark, duplicate mark, duplicate annotation,
automatic/manual duplication, and commands used outside an EqAnnotate display.
Commands used outside a display produce an explicit package error. Other
authoring mistakes produce warnings.

\section{Current scope}
The current interface supports display equations and excludes inline
annotations, per-row numbering for multi-line wrappers, arbitrary \cmd{\tag},
and \cmd{\intertext}/\cmd{\shortintertext} inside its wrappers. Configure
non-white page backgrounds explicitly:
\begin{verbatim}
\renewcommand\eqannotatebackgroundcolor{<color>}
\end{verbatim}

\section{Complete examples}
The distribution includes the following runnable public-interface examples:
\begin{itemize}
\item \texttt{examples/basic.tex}
\item \texttt{examples/style-gallery.tex}
\item \texttt{examples/amsmath-gallery.tex}
\item \texttt{examples/manual-gallery.tex}
\end{itemize}

\section{License and project links}
EqAnnotate is available under the MIT License. The
\href{https://github.com/intelland/eqannotate}{GitHub repository} hosts source
and releases; report problems through the
\href{https://github.com/intelland/eqannotate/issues}{issue tracker}.
\end{document}