%%
%% This is file `pdfmathaccents-doc.tex', the documentation of the
%% pdfmathaccents package.
%%
%% Copyright 2026 Joris Pinkse
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either
%% version 1.3c of this license or (at your option) any later
%% version. The latest version of this license is in
%%    https://www.latex-project.org/lppl.txt
%% and version 1.3c or later is part of all distributions of
%% LaTeX version 2008 or later.
%%
%% Note: this file contains Unicode combining characters (in
%% decomposed, NFD form).  Editors that normalize to NFC will break
%% the examples; see the Caveats section of the documentation.
%%
% This document must be compiled with pdfLaTeX: it loads and
% demonstrates pdfmathaccents, which is pdfLaTeX-only.  Under any
% other engine, stop before the combining characters below produce
% pages of garbage.
\RequirePackage{iftex}
\makeatletter
\ifPDFTeX\else
  \errhelp{Compile this document with pdflatex.  Under LuaLaTeX, use
    the luamathaccents package and its documentation instead.}%
  \errmessage{pdfmathaccents-doc.tex requires pdfLaTeX}%
  \expandafter\@@end
\fi
\makeatother

\documentclass{article}

\usepackage[margin=3cm]{geometry}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{amsmath}
\usepackage{booktabs}
\usepackage{metalogo}
\usepackage[hidelinks]{hyperref}
\usepackage{pdfmathaccents}

% Combining characters have no text-mode meaning under pdfLaTeX, so
% inside the verbatim listings below we render each one as a mark
% overlaid on the preceding character (the fonts are monospaced, so
% \llap backs up by exactly one character cell).
\newcommand*\CombMark[1]{\llap{#1}}
\DeclareUnicodeCharacter{0302}{\CombMark{\raisebox{0.45ex}{\textasciicircum}}}
\DeclareUnicodeCharacter{0303}{\CombMark{\raisebox{0.85ex}{\textasciitilde}}}
\DeclareUnicodeCharacter{0304}{\CombMark{\raisebox{0.25ex}{\textasciimacron}}}
\DeclareUnicodeCharacter{20D7}{\CombMark{\raisebox{1.25ex}{\scriptsize$\rightarrow$}}}

\title{The \textsf{pdfmathaccents} package\thanks{This document
    describes \textsf{pdfmathaccents} v1.0, released 2026/07/27.}}
\author{Joris Pinkse\\\texttt{pinkse@gmail.com}}
\date{2026/07/27}

\begin{document}

\maketitle

\section{Introduction}

Some editors make it easy to type accented mathematical symbols
directly. For instance, typing \texttt{x\textbackslash hat} followed
by \texttt{Tab} in VS~Code (with the Julia or Unicode Latex extension)
shows an $x$ with a hat on top. What actually ends up in the file is
the letter \texttt{x} followed by the Unicode \emph{combining
  character} U+0302 (combining circumflex accent). \LaTeX{} does not
interpret this two-character sequence: pdf\LaTeX{} stops with an error
because combining characters are not set up at all.

With \textsf{pdfmathaccents} loaded, a base character followed by a
supported combining character is typeset in math mode as the
corresponding accent command: \texttt{x}\,+\,U+0302 becomes
\verb|\hat x|, and likewise for the other combining characters listed
in Section~\ref{sec:supported}.

This package requires pdf\LaTeX{}. It is the pdf\LaTeX{} companion of
the \textsf{luamathaccents} package: under \LuaLaTeX{}, use
\textsf{luamathaccents} instead, which supports more combining
characters and is less invasive (\LuaTeX{} can rewrite the input line
before \TeX{} tokenizes it, which pdf\TeX{} cannot).

\section{Usage}

\begin{verbatim}
\usepackage{pdfmathaccents}
\end{verbatim}

\noindent
The conversion is active from that point on and applies in math mode,
to base characters that are ASCII letters or digits.

\verb|\PdfMathAccentsOff| disables the conversion and
\verb|\PdfMathAccentsOn| re-enables it. Both are local to the current
group.

\section{Example}

The input\footnote{In this listing the combining characters are shown
  as marks over the preceding character, which is also how most
  editors display them.}
\begin{verbatim}
$x̂ + ỹ = z̄$, force $F⃗ = m a⃗$, and average $v̄$.
\end{verbatim}
is typeset as
\begin{quote}
$x̂ + ỹ = z̄$, force $F⃗ = m a⃗$, and average $v̄$.
\end{quote}

\section{Supported combining characters}
\label{sec:supported}

The table below lists the supported combining characters, the accent
command each one is converted to, and the result on the letter~$x$.
The last two require the \textsf{amsmath} package; if
\textsf{amsmath} is not loaded, those two characters are not
converted.

\begin{center}
\begin{tabular}{llll}
\toprule
Code point & Name & Command & Result \\
\midrule
U+0300 & combining grave accent      & \verb|\grave|     & $x̀$ \\
U+0301 & combining acute accent      & \verb|\acute|     & $x́$ \\
U+0302 & combining circumflex accent & \verb|\hat|       & $x̂$ \\
U+0303 & combining tilde             & \verb|\tilde|     & $x̃$ \\
U+0304 & combining macron            & \verb|\bar|       & $x̄$ \\
U+0305 & combining overline          & \verb|\bar|       & $x̅$ \\
U+0306 & combining breve             & \verb|\breve|     & $x̆$ \\
U+0307 & combining dot above         & \verb|\dot|       & $ẋ$ \\
U+0308 & combining diaeresis         & \verb|\ddot|      & $ẍ$ \\
U+030A & combining ring above        & \verb|\mathring|  & $x̊$ \\
U+030C & combining caron             & \verb|\check|     & $x̌$ \\
U+0331 & combining macron below      & \verb|\underline| & $x̱$ \\
U+20D6 & combining left arrow above  & \verb|\overleftarrow| & $x⃖$ \\
U+20D7 & combining right arrow above & \verb|\vec|       & $x⃗$ \\
U+20DB & combining three dots above  & \verb|\dddot|     & $x⃛$ \\
U+20E1 & combining left right arrow above & \verb|\overleftrightarrow| & $x⃡$ \\
\bottomrule
\end{tabular}
\end{center}

\section{How it works, and caveats}

pdf\TeX{} cannot rewrite the input line the way \LuaTeX{} does.
Instead, \textsf{pdfmathaccents} gives every ASCII letter and digit
the math code \verb|"8000|, which makes it behave like an active
character in math mode (the technique used by, for example, the
\textsf{icomma} package). The character then looks at the following
token; if it is the start of a supported combining character, the
accent command is applied, and otherwise the character is typeset
as usual. This has a number of consequences.

\begin{itemize}
\item The conversion applies in math mode only, and the base character
  must be an ASCII letter or digit. A combining character in text, in
  verbatim, or after any other base character produces the standard
  \textsf{inputenc} error (``not set up for use with \LaTeX''), just
  as it would without this package. (This document declares text-mode
  renderings for a few combining characters in its preamble, which is
  how the verbatim listing in the example above is typeset.)

\item Only combining \emph{sequences} (NFD) are recognized. A
  precomposed (NFC) character such as U+0177 (\emph{y with
    circumflex}) is a different, single character and is not
  converted. Beware: some editors silently normalize combining
  sequences to precomposed characters. Because such a character in
  math mode always leads to an error whose message does not mention
  the real cause (either ``Please use \verb|\mathaccent|'' or ``not
  set up for use with \LaTeX''), \textsf{pdfmathaccents} precedes
  that error with a warning pointing at NFC normalization as the
  likely culprit.

\item Only the first combining character after a base character is
  converted; a second one produces the \textsf{inputenc} error
  mentioned above. (\textsf{luamathaccents} passes it through
  instead.)

\item Ten of the combining characters supported by
  \textsf{luamathaccents} are unavailable here (U+0309, U+0310,
  U+0312, U+0315, U+031A, U+20D0, U+20D1, U+20E7, U+20E9, and
  U+20F0), because standard \LaTeX{} math fonts provide no
  corresponding accents.

\item Every letter and digit in math mode is wrapped in a group, as if
  you had typed \verb|{x}| instead of \verb|x|. This is almost always
  invisible; the one observable effect is that a superscript on a
  letter with a large italic correction, such as~$f$, is placed very
  slightly closer to the letter.

\item Packages that assign math codes to letters (for example
  \textsf{mathastext}) will silently undo or be undone by this
  package, depending on load order. Load \textsf{pdfmathaccents}
  last.
\end{itemize}

\section{License}

Copyright 2026 Joris Pinkse. This work may be distributed and/or
modified under the conditions of the \LaTeX{} Project Public License,
either version 1.3c of this license or (at your option) any later
version. This work has the LPPL maintenance status ``maintained''; the
current maintainer is Joris Pinkse (\texttt{pinkse@gmail.com}).

Development happens at
\url{https://github.com/NittanyLion/pdfmathaccents}; please report
bugs there.

\end{document}