\DocumentMetadata{
	lang        = en-US,
	tagging     = on,
	%testphase   = {latest,math,firstaid},% NO LONGER NEEDED! :)
%	tagging-setup = {math/setup={mathml-SE,mathml-AF},
	tagging-setup = {math/setup={mathml-SE},
			extra-modules={verbatim-mo}}, % Optional?? Unclear if still needed
	pdfstandard = ua-2,
	pdfstandard = a-4f,
	uncompress
}

\documentclass[doublespace, 11pt]{article}
\usepackage[margin=0.75in]{geometry}

\usepackage[hidelinks, pdfusetitle]{hyperref}
\title{Custom Alternative Text For LaTeX Math Symbols in PDFs}
%\usepackage{accsupp} % NEEDED FOR THE FIRST ATTEMPTS BELOW, BUT NOT NEEDED FOR FINAL SOLUTION

\usepackage{fontspec}
\usepackage{utfsym} % for an example symbol with no unicode alternative (see below)

\usepackage{amsmath}
\usepackage{unicode-math}
%\setmathfont{Latin Modern Math} % This is loaded automatically as the default by unicode-math
%\setmathfont{STIXTwoMath-Regular.otf}%{STIX Two Math} % a common alternative

\usepackage{graphicx}
\usepackage{parskip}

%% Goals:  A \hammerwrenchof{} function (see the symbol) similar in usage to \sqrt{}
         % A \hammerwrench symbol similar in usage to \pi, etc.

% OPTION A: None of these four options gives a readable symbol/function
%\newcommand{\hammerwrench}[1]{% hammer-X-wrench symbol
	%	\BeginAccSupp{ActualText={hammer wrench}}%
	%%	\BeginAccSupp{method=pdfstringdef,ActualText={hammer wrench}}%
	%	\usym{1F6E0}(#1)%
	%%	\ensuremath{\usym{1F6E0}(#1)}%
	%	\EndAccSupp{}%
	%}


% OPTION B: These also failed to give a readable symbol/function
%\newcommand{\hammerwrenchop}{%
	%	\mathop{%
		%		\BeginAccSupp{method=pdfstringdef,ActualText={hammer wrench}}%
		%		\text{\usym{1F6E0}}%
		%		\EndAccSupp{}%
		%	}\nolimits
	%}
%\newcommand{\hammerwrench}[1]{%
	%	\BeginAccSupp{method=pdfstringdef,ActualText={hammer wrench of #1}}%
	%	\hammerwrenchop\!\left(#1\right)%
	%	\EndAccSupp{}%
	%}


% OPTION C: THESE WORK!!! Uses \MathMLintent{alt MathML text}{math symbol/expression}
\newcommand{\hammerwrenchof}[1]{% Function of one argument
	\MathMLintent{hammer-wrench($x)}%
	{{\usym{1F6E0}\!\left(\MathMLarg{x}{#1}\right)}}%
}
\newcommand{\hammerwrench}{% Symbol only
	\MathMLintent{hammer-wrench}% Next line coerces the text into needing a MathML tag... 
	{{\,\cdot\!\!\!\text{\usym{1F6E0}}}}%  by hiding a well-placed cdot under the symbol.
	% The use of thin space \, and negative thin space \! are for the overall alignment 
	% relative to the preceding symbol, and the amount of overlap of the cdot, respectively.
	% For other glyphs, that don't scale correctly, see \mathchoice{}{}{}{}.
}
% These provide alternate text for symbols that WOULD have readable default MathML tags
\newcommand{\Jac}{%
	\MathMLintent{Jacobian-J}%
	{\mathbf{J}}%
}
\newcommand{\J}{%
	\MathMLintent{Poisson-matrix-J}%
	{J}%
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
\raggedright
\begin{center}% Title
%\tagpdfparaOff
\tagstructbegin{tag=Title}% Start tag structure
\tagmcbegin{tag=Title}% Start marked content
\Large\bfseries Custom Alternative Text For \LaTeX{} Math Symbols in PDFs
\tagmcend\tagstructend% The next line must be blank before \tagpdfparaOn, for some reason.
%
%\tagpdfparaOn
\end{center}\begin{center}% Author & date
	by Paul Hurtado \textemdash{} Last updated \textit{\today}
\end{center}

The purpose of this document is to help \LaTeX{} users create accessible PDFs with screen readable mathematical expressions, specifically in scenarios with: \begin{itemize}\item[(i) ] math symbols with problematic MathML-based alt text (as read by a screen reader, like NVDA) given the context of their usage, or \item[(ii)] symbols that have no MathML encoding and thus ignored by the screen reader. \end{itemize}
	
Here we override MathML derived alt text using \verb|\MathMLintent{}| that was introduced in early 2026 (however, expect many changes over 2026-2027 as the new \LaTeX{} tagging functionality is rolled out). 
	
\textbf{Note:} This document assumes that you are reading the PDF along side the \LaTeX{} source file. You are also strongly encouraged to setup the NVDA screen reader (e.g., see \url{https://accessibility.huit.harvard.edu/nvda}) to hear these expressions read out loud.
	
\textbf{Example 1:} A custom ``hammer-wrench'' function has been implemented in this document using the symbol \verb|\usym{1F6E0}|=\usym{1F6E0} from the \texttt{utfsym} package. This was done using two macros: \begin{itemize}
	\item \verb|\hammerwrench|$\;=\hammerwrench$ for just the symbol (used like \verb|\Phi|$\;=\Phi$), and 
	\item \verb|\hammerwrenchof{x}|$\;=\hammerwrenchof{x}$ for a function (used like \verb|\sqrt{x}|$\;=\sqrt{x}$).
\end{itemize}

These macros specify alt text for how the screen reader should read these symbols (``\textit{hammer wrench}'' and ``\textit{hammer wrench of}'', respectively). Here are example equations for each macro:
\begin{equation}
	\sin\big(\sqrt{\hammerwrenchof{x}}\big)
\end{equation}
\begin{equation}
	\frac{d\hammerwrench}{dt} + \frac{d}{dt}\!\Big[\mathbf{A}\,\hammerwrench\,\mathbf{A}^{-1}\Big] + e^{\hammerwrench} = 0.
\end{equation} 
	
If you don't have a good (MathML capable) screen reader handy, here is how the above is read using the latest beta version of the NVDA screen reader with Adobe Acrobat:
	
\begin{quote}
	Here are example equations for each macro. One line, with label, one. Sine of, open paren, the square root of, hammer-wrench of x, close paren. One line with label, two. The fraction with numerator d hammer-wrench and denominator dt, plus, the fraction with numerator d and denominator dt, times open bracket A hammerwrench A to the negative one power, close bracket, is equal to zero.
\end{quote}
 
\textbf{Important note:} Unfortunately, while it's straightforward to implement these macros to redefine the alt text for an existing math symbol (or for the function-like use of math and non-math symbols alike), \emph{the symbol-only macro for a non-math symbol does not work!}. Why? In order for there to by MathML-based text field to modify, a base math structure must exist to get parsed by the internal mathml-SE tagging routine. Short of declaring a new math symbol, the crude workaround I used was overlay the new symbol on a small math symbol like \verb|\cdot|, thereby coercing the expression to be parsed as math. 
	
\textbf{Example 2:} Often, identical letters with different fonts represent distinct quantities, and this isn't always read correctly. To illustrate overriding autogenerated MathML, this document also uses some macros that display \verb|\Jac=$\mathbf{J}$| with alt text ``Jacobian J'', and \verb|\J=$J$| with alt text ``Poisson Matrix J''. Here they are in an expression along with a standard \verb|$J$| (third J): \[\Jac \neq \J \neq J.\] Again, if you do not have a screen reader setup to read this for you, the above equation is read aloud as ``Jacobian J is not equal to Poisson Matrix J is not equal to J.'' 
\pagenumbering{gobble}
\end{document}
