%!TEX engine = lualatex

% ##############################################################################
% math-shorthandz.tex — manual of the math-shorthandz package
%
% Copyright (C) 2025-2026 Tiago Pomella Lobo
% LPPL 1.3c or later, author-maintained; see math-shorthandz.sty for the full notice.
%
% Compiling (LuaLaTeX or XeLaTeX, required by unicode-math; no -shell-escape):
%   lualatex math-shorthandz
%   makeindex -s gind.ist math-shorthandz.idx   % gind.ist is required (\CodelineIndex)
%   lualatex math-shorthandz
%   lualatex math-shorthandz                    % final pass: contents, references, index
% or `l3build doc`, or `latexmk -lualatex math-shorthandz` with this line in a latexmkrc:
%   $makeindex = 'makeindex -s gind.ist %O -o %D %S';
%
% Notes:
%   - math-shorthandz.sty and math-shorthandz-listings.tex must be found by TeX
%     (same folder, or installed). math-shorthandz-listings.tex only styles the
%     example boxes.
%   - \RecordChanges writes math-shorthandz.glo, which is unused: the change
%     history is typed by hand, so no glossary pass is needed.
% ##############################################################################
\documentclass[a4paper]{ltxdoc}

\usepackage{math-shorthandz}
%\usepackage[zarg-kern=3mu]{math-shorthandz}          % Test setkeys

\usepackage{hypdoc}     \hypersetup{hidelinks}
\usepackage{listings}
\usepackage{booktabs}
\usepackage{xcolor}
\usepackage{ulem}
\usepackage{microtype}
\usepackage{enumitem}
\usepackage{parskip}
\usepackage{geometry}
\usepackage{metalogo}
\usepackage{tabularx}
\usepackage{tcolorbox}
\usepackage{subcaption}
\usepackage{xspace}
\usepackage{tikz}       \usetikzlibrary{arrows.meta}

\geometry{top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm}

% Chose syntax highlighter
  \input{math-shorthandz-listings.tex}
  %\input{math-shorthandz-minted.tex}

% ---- helpers for this doc ----
\newcommand{\nl}[1][1]{%
  \ifmmode  \expandafter\\[#1\baselineskip]%
  \else     \par\vspace{#1\baselineskip}%
  \fi
}
\newcommand{\eg}{\textit{e.g.}\xspace}
\newcommand{\ie}{\textit{i.e.}\xspace}
\newcommand{\etc}{\textit{etc.}\xspace}
\newcommand{\pkg}[1]{\textsf{#1}}
\newcommand{\opt}[1]{\texttt{#1}}
\newcommand{\macroDescription}[1]{\DescribeMacro{#1}}
\newcommand{\macroMeta}[1]{\textit{\textlangle#1\textrangle}}
\newcommand{\macroArg}[1]{\texttt{\{}\macroMeta{#1}\texttt{\}}}
\newcommand{\macroOpt}[1]{\texttt{[}\macroMeta{#1}\texttt{]}}
\newcommand{\macroBar}[1]{\texttt{\textbackslash #1\textbar}}
\newcommand{\macroKey}[2]{\texttt{#1-}\macroMeta{mode}\texttt{-#2}} % \macroKey{zint}{after} -> zint-<mode>-after
\newcommand{\macroSpan}[1]{\multicolumn{2}{c}{#1}}                  % one value shared by the Math and Text columns
\newcommand{\macroStar}{\texttt{*}}
\newcommand{\macroPlus}{\texttt{+}}
\newenvironment{syntax}
  {\begin{tcolorbox}[
    enhanced,
    colback=gray!10,
    colframe=black,
    boxrule=0.5pt,
    arc=1.5mm,
    left=6pt,
    right=6pt,
    top=4pt,
    bottom=4pt
  ]\ttfamily}
  {\end{tcolorbox}}
\makeatletter
  \newcommand{\macroRow}[1]{%
    \addlinespace[0.3em]%
    \multicolumn{\macroTable@columns}{l}{\underline{#1}} \\
    \addlinespace[0.4em]%
  }
  \NewDocumentCommand{\macroDisp}{s m}{% \macroDisp{x}: inline output; \macroDisp*{x}: display output
    \IfBooleanTF{#1}{$ \displaystyle #2 $}{$ #2 $}%
  }
  \newcolumntype{C}[1]{>{\centering\arraybackslash}p{#1}}
  \newcolumntype{E}{p{2.5cm} C{2cm} C{2cm} X}
  \newlength{\macroTable@width}
  \NewDocumentCommand{\macroWidth}{s}{%
    \IfBooleanTF{#1}
      {\setlength{\macroTable@width}{0.85\textwidth}}
      {\setlength{\macroTable@width}{\textwidth}}%
  }
  \def\macroTable@cnt#1&#2\@nil{% counts the cells of a header: 1 + number of & in it
    \ifx\relax#2\relax\else\advance\@tempcnta\@ne\macroTable@cnt#2\@nil\fi
  }
  \NewDocumentCommand{\macroTable@build}{m m m m +m}{%
    % \macroTable@build{columns}{colspec}{header}{stretch}{rows}
    \begingroup
    \def\macroTable@columns{#1}%
    \IfBlankTF{#4}{}{\renewcommand{\arraystretch}{#4}}%
    \begin{tabularx}{\macroTable@width}{#2}
    \hline\hline
    \addlinespace[0.3em]
    #3 \\
    \midrule
    #5
    \addlinespace[0.3em]%
    \hline\hline
    \end{tabularx}%
    \endgroup
  }
  \NewDocumentEnvironment{macroTable}{O{Option & Default & Description} m m +b}
    {% \begin{macroTable}[headers]{label}{caption}; first column left, last one X, the rest centred
      \begingroup
      \macroWidth
      \@tempcnta\@ne \macroTable@cnt#1&\@nil
      \@tempcntb\@tempcnta \advance\@tempcntb-\tw@
      \def\macroTable@spec{l}%
      \@whilenum\@tempcntb>\z@\do{\edef\macroTable@spec{\macroTable@spec c}\advance\@tempcntb\m@ne}%
      \edef\macroTable@call{\noexpand\macroTable@build{\the\@tempcnta}{\macroTable@spec X}}%
      \begin{center}
      \captionof{table}{#3}\label{#2}
      \macroTable@call{#1}{}{#4}
      \end{center}
      \endgroup
    }
    {}
  \NewDocumentEnvironment{macroTable*}{O{} +b} %\begin{macroTable*}[stretch]
    {%
      \begingroup
      \macroWidth*
      \begin{center}
      \macroTable@build{4}{E}{Source & Inline & Display & Meaning}{#1}{#2}
      \end{center}
      \endgroup
    }
    {}
  \newcommand{\optval}[1]{{\def\@{@}\csname msz@#1\endcsname}}
\makeatother

% ---- schematic figure styles (shared by all option drawings) ----
\tikzset{
  zmglyph/.style = {draw=black, thin, fill=black!7},
  zmlim/.style   = {draw=black!55, thin, fill=black!18, inner sep=2pt, font=\scriptsize},
  zmframe/.style = {draw=black, very thick},
  zmunion/.style = {draw=black!70, dashed},
  zmref/.style   = {dashed, gray},
  zmext/.style   = {dashed, gray},
  zmdim/.style   = {<->, red!70!black},
  zmlbl/.style   = {font=\scriptsize\ttfamily, red!70!black, fill=white, inner sep=1pt}
}

\EnableCrossrefs
\CodelineIndex
\RecordChanges



% ---- document ----
\begin{document}

\title{The \pkg{math-shorthandz} Package\\[4pt]
       \large Smart Shorthands for Math Typesetting}
\author{Tiago Pomella Lobo}
\date{\today\quad v1.0.0}
\maketitle

\begin{abstract}
  The \pkg{math-shorthandz} package has shorthand macros for typesetting the most common mathematical expressions in \LaTeX. It provides compact commands to construct symbols with features such as multi-underlines, pre- and succeeding scripts, fractions, differentials and derivatives, and integrals, with highly customizable positioning and (auto-)scaling. All commands are safe in text, and distinguish their customization between display, inline, script and scriptscript contexts.
\end{abstract}

\tableofcontents
\clearpage

% ==============================================================================
\section{Introduction}
% ==============================================================================

Classical \LaTeX\ math commands such as \cs{int}, \cs{frac}, and \cs{underbrace} are powerful but low-level. Writing readable source for an equation requires manual spacing kerns, sizing primitives, and mode switches that clutter the source and make it hard to refactor. As an alternative, I have been using several macros intermittently since 2020 to hide much of this complexity. Now, I have merged and expanded these macros into the \pkg{math-shorthandz} package that introduces many semantic shorthands. In this new version, the consolidated commands handle both display and inline modes, respect the ambient math style, and expose their tunable parameters as package options so the same source adapts to different fonts and house styles without changes to individual call sites. You can see some examples below:
\begin{tcblisting}{
    math-shorthandz-tex,
    %halign lower=center,
    lefthand width=0.6\linewidth
  }
  Show case with Equation~\ref{eq:example}:
  \begin{equation}
    \label{eq:example}
    \zint[0][T] f\zarg{t}\zdiff+{t} = \zfrac[\beta+1]
    \zpunct{.}
  \end{equation}
\end{tcblisting}

The package is built on \pkg{expl3} and \pkg{xparse}, which are part of the \LaTeX\ kernel since 2020 and require no extra \cs{usepackage} declarations. The integral commands use XITS~Math glyphs for the integral symbols (loaded automatically at \cs{begin}\texttt{\{document\}}); the remainder of the math font is left to the user. I personally like:
\begin{syntax}
  \cs{setmathfont}\texttt{\{TeX Gyre DejaVu Math\}[Scale=0.85]}
\end{syntax}

The package automatically loads \pkg{amsmath}, \pkg{unicode-math}, \pkg{graphicx}, \pkg{nicefrac}, \pkg{xkeyval}. Because \pkg{unicode-math} is loaded, \textbf{the document engine must be} \LuaLaTeX\ or \XeLaTeX. Import it with:
\begin{syntax}
  \cs{usepackage}\macroOpt{options}\texttt{\{math-shorthandz\}}
\end{syntax}

The package name has a playful "z" ending to emphasize the unified naming style for all commands, that also distinguishes them (\eg \cs{zdot} instead of \cs{cdot}). The package was originally named \pkg{zmath}, but was renamed upon its first public release to address requests from CTAN and \TeX\ Live.

% ------------------------------------------------------------------------------
\subsection{About this documentation}
% ------------------------------------------------------------------------------

The local macro \cs{nl} is used to add line breaks in the example boxes, so it has been colored grey to reduce visual impact. Every option's key name is prefixed with the full public command name it belongs to (\eg{} \opt{zint-}, \opt{zdiff-}), so key names are unambiguous even when taken out of context. The environment \texttt{macroTable} typesets the captioned option table that follows the syntax of each command, with standard columns "Option", "Default" and "Description". Other headers can be optionally passed, and the starred form \texttt{macroTable*} prduces example tables with the columns "Source", "Output" and "Meaning". 

% ------------------------------------------------------------------------------
\subsection{License and support}
% ------------------------------------------------------------------------------

Copyright \textcopyright{} 2020--2026 Tiago Pomella Lobo. This work may be distributed and/or modified under the conditions of the \LaTeX\ Project Public License, version 1.3c or later (\url{https://www.latex-project.org/lppl.txt}), and has the maintenance status "author-maintained". Source code, issues and releases: \url{https://github.com/tplobo/math-shorthandz}.

% ==============================================================================
\section{User Interface}
% ==============================================================================

% ------------------------------------------------------------------------------
\subsection{Package options}
% ------------------------------------------------------------------------------

All tunable constants are exposed as key--value options via a unified interface. All keys belong to the family \texttt{shorthand}, so that is the first argument of \cs{setkeys} (not the package name). Every option is a plain macro read at call time, so it may be given to \cs{usepackage}, changed at any point with \cs{setkeys}\texttt{\{shorthand\}\{key=value\}}, or overridden for a single call by doing so inside a \TeX\ group. The table that follows the syntax of each command lists its options, default values and their effect(s); captions explain eventual placeholders.

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zpunct} — punctuation at the end of a display line}
% ------------------------------------------------------------------------------

\macroDescription{\zpunct}
The \cs{zpunct} command provides a semantic hook to end a line of a mathematical display with a punctuation mark \macroMeta{punct}. Rather than dropping the token right at the end of the math expression—which can cause awkward line breaks or misaligned punctuation tracking—this utility moves it to the right end of the line, where the equation number goes. It works with and without equation numbers. It has no package options.

\begin{syntax}
  \cs{zpunct}\macroArg{punct}
\end{syntax}

In a numbered equation, the punctuation rests immediately before the number, separated from it by a space. In an unnumbered equation (\eg \texttt{equation*}, \texttt{gather*}, \texttt{flalign*}, \dots), the punctuation is flushed right to where the numbering would stand. This is done with the \texttt{\textbackslash tag*} command of \texttt{amsmath}, so \cs{zpunct} cannot be combined with \cs{tag} in the same unnumbered equation. A row suppressed with \texttt{\textbackslash notag} or \texttt{\textbackslash nonumber} inside a numbered environment discards the punctuation. Place the command in the line it ends, before a newline command (\eg \texttt{\textbackslash\textbackslash}).

The following example punctuates the equations in a numbered block:
\begin{tcblisting}{
    math-shorthandz-tex,
    %halign lower=center,
    lefthand width=0.6\linewidth
  }
  Equations \ref{eq:energy} and \ref{eq:force}
  show important results:
  \begin{gather}
    \label{eq:energy}
    E = mc^2                        \zpunct{,}
    \\
    \label{eq:force}
    \vec{F} = m \cdot \vec{a}       \zpunct{.}
  \end{gather}
\end{tcblisting}

while this example shows how to complement text within an unnumbered block, where punctuation is flushed right without requiring the numbering:
\begin{tcblisting}{
    math-shorthandz-tex,
    %halign lower=center,
    lefthand width=0.6\linewidth
  }
  The following equations show important results:
  \begin{flalign*}
    & E = mc^2                      \zpunct{, and}
    \\
    & \vec{F} = m \cdot \vec{a}     \zpunct{.}
  &\end{flalign*}
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zline} — arbitrary underline stacking}
% ------------------------------------------------------------------------------

\macroDescription{\zline}
The \cs{zline} utility structurally attaches an arbitrary \macroMeta{count} of horizontal underline rules beneath a target \macroMeta{symbol}. By default, omitting the optional parameter draws a single line. The execution engine dynamically computes the natural horizontal bounding box of the input \macroMeta{symbol}, ensuring that the rule widths match the content exactly without leaking into adjacent characters. It is safe for direct deployment in both text and math modes. Its options are listed in Table~\ref{tb:zline}.

\begin{syntax}
  \cs{zline}\macroOpt{count}\macroArg{symbol}
\end{syntax}

\begin{macroTable}{tb:zline}{Options for \cs{zline}, \cs{zvec} and \cs{zmat}.}

    \opt{zline-depth}
        & \optval{line\@depth}
        & Vertical gap from the symbol's bottom edge to the first rule (Figure~\ref{fig:zline}).
    \\

    \opt{zline-thickness}
        & \optval{line\@thickness}
        & Absolute typographic thickness of each individual underline rule.
    \\

    \opt{zline-separation}
        & \optval{line\@separation}
        & Vertical gap between consecutive stacked rules.
    \\

\end{macroTable}

The macro was inspired by the popular \textsf{ulem} package, but alters some of its functionalities: instead of line weights that depend on ambient font sizes (which may cause layout collisions), \cs{zline} enforces a fixed baseline and thickness alignment. The absolute vertical layout dimensions of rule thickness, clearances from the symbol's bottom edge, and relative gaps between stacked lines are governed by the \opt{zline-thickness}, \opt{zline-depth}, and \opt{zline-separation} package options (Figure~\ref{fig:zline}). The symbol box is typeset once with \cs{mathsurround} suppressed.

\begin{figure}[htbp]
  \centering
  \begin{tikzpicture}[scale=1.25, >=Stealth]
    % symbol box and baseline
    \draw[zmglyph] (0,-0.3) rectangle (1.6,1.5);
    \node at (0.8,0.6) {\Large $u$};
    \draw[zmref] (-0.5,0) -- (2.2,0) node[right, font=\scriptsize\itshape, gray] {baseline};
    % two stacked rules
    \fill (0,-1.2) rectangle (1.6,-1.0);
    \fill (0,-1.9) rectangle (1.6,-1.7);
    % vertical dimensions
    \draw[zmext] (1.6,-0.3) -- (2.9,-0.3);
    \draw[zmext] (1.6,-1.0) -- (2.9,-1.0);
    \draw[zmext] (1.6,-1.2) -- (2.9,-1.2);
    \draw[zmext] (1.6,-1.7) -- (2.9,-1.7);
    \draw[zmdim] (2.7,-0.3) -- node[zmlbl, right] {line-depth}     (2.7,-1.0);
    \draw[zmdim] (2.7,-1.0) -- node[zmlbl, right] {line-thickness} (2.7,-1.2);
    \draw[zmdim] (2.7,-1.2) -- node[zmlbl, right] {line-sep}       (2.7,-1.7);
    % width
    \draw[zmext] (0,-1.9) -- (0,-2.6);
    \draw[zmext] (1.6,-1.9) -- (1.6,-2.6);
    \draw[zmdim] (0,-2.5) -- node[font=\scriptsize, below] {natural width of the symbol} (1.6,-2.5);
  \end{tikzpicture}
  \caption{Schematic of the \cs{zline} options (here two rules, as in \cs{zmat}). The shaded box is the symbol's box; the rules are drawn filled, with the same width. Distances are exaggerated for legibility.}
  \label{fig:zline}
\end{figure}

\macroDescription{\zvec}
\macroDescription{\zmat}
For convenience in physics and engineering notation, the package provides the secondary shorthand macros \cs{zvec} and \cs{zmat} to standardize vector and matrix underline conventions, as an alternative to bold fonts, \cs{vec}, \cs{overleftrightarrow} and others, that can lead to dense notation. Both commands call \cs{zline}, generating one and two underlines respectively.

\begin{syntax}
  \cs{zvec}\macroArg{symbol} \qquad \cs{zmat}\macroArg{symbol}
\end{syntax}

The following example compares \cs{zvec} and \cs{zmat} with the \textsf{ulem} and accent alternatives, and shows a triple underline and the difference between underlining an expression and a symbol:

\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.8\linewidth
  }
  $\zvec{u} = \vec{u} \ne \uline{u}$                  % zvec vs ulem command
  \nl
  $\zmat{A} = \overleftrightarrow{A} \ne \uuline{A}$  % zmat vs ulem command
  \nl
  \zline[3]{W}                                        % triple underline
  \nl
  $\zline{x^2} \ne \zline{x}^2$                       % composition
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zfrac} — flexible fraction}
% ------------------------------------------------------------------------------

\macroDescription{\zfrac}
The \cs{zfrac} utility typesets a fraction whose visual style and argument parenthesisation are controlled independently, by stars and by the choice of delimiter around each argument. If only one argument is supplied, it is treated as the denominator and the numerator defaults to \texttt{1}. The entire output is always wrapped in \cs{ensuremath}, so \cs{zfrac} is safe in text, inline and display mode to contain math symbols (\eg{} Greek letters, radicals). It has no package options.

\begin{syntax}
  \cs{zfrac}\macroStar\macroStar\macroOpt{num}\macroArg{num}\macroOpt{den}\macroArg{den}
\end{syntax}

Starring:
\begin{itemize}[nosep]
  \item \textbf{none (-)} — standard \cs{frac} layout.
  \item \textbf{one (\macroStar)} — oblique \cs{nicefrac} layout, suited to inline use.
  \item \textbf{two (\macroStar\macroStar)} — slash notation, \macroMeta{num}\texttt{/}\macroMeta{den}.
\end{itemize}

Each argument may be given in braces (\macroArg{x}, plain) or in brackets (\macroOpt{x}, parenthesised, \ie{} wrapped in \cs{left(}\,\ldots\,\cs{right)}). The two delimiter choices are independent, so \eg{} only the denominator may be parenthesised while the numerator is left plain. The following table lists every delimiter combination:

\begin{macroTable*}[2]
    \cs{zfrac}\texttt{\{n\}\{d\}}
        & \macroDisp{ \zfrac{n}{d} }
        & \macroDisp*{ \zfrac{n}{d} }
        & plain numerator, plain denominator
    \\

    \cs{zfrac}\texttt{\{n\}[d]}
        & \macroDisp{ \zfrac{n}[d] }
        & \macroDisp*{ \zfrac{n}[d] }
        & parenthesised denominator
    \\

    \cs{zfrac}\texttt{[n]\{d\}}
        & \macroDisp{ \zfrac[n]{d} }
        & \macroDisp*{ \zfrac[n]{d} }
        & parenthesised numerator
    \\

    \cs{zfrac}\texttt{[n][d]}
        & \macroDisp{ \zfrac[n][d] }
        & \macroDisp*{ \zfrac[n][d] }
        & both parenthesised
    \\

    \cs{zfrac}\texttt{\{d\}}
        & \macroDisp{ \zfrac{d} }
        & \macroDisp*{ \zfrac{d} }
        & single arg $\implies$ numerator = 1
    \\

    \cs{zfrac}\texttt{[d]}
        & \macroDisp{ \zfrac[d] }
        & \macroDisp*{ \zfrac[d] }
        & parenthesised, with numerator = 1
    \\
\end{macroTable*}

and here are some accompanying examples:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.8\linewidth
  }
  \zfrac{\alpha}{\beta}                 % standard frac
  \nl
  \zfrac*{x}{y}                         % nicefrac
  \nl
  \zfrac**{x}{y}                        % slash
  \nl
  $\zfrac{\alpha}[\beta+1]$             % parenthesise denominator
  \nl
  $\zfrac[\alpha+1]{\beta}$             % parenthesise numerator
  \nl
  $\zfrac{\lambda}$                     % inverse
  \nl
  $e^{-\zfrac{x}} \ne e^{-\zfrac*{x}}$  % context aware
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zscale} — uniform content scaling}
% ------------------------------------------------------------------------------

\macroDescription{\zscale}
The \cs{zscale} utility scales an arbitrary \macroMeta{math} token vector uniformly by a given \macroMeta{factor}. If the optional modifier is omitted, the engine defaults to the package option of the math style in which \cs{zscale} is called (\opt{scale-display}, \opt{scale-text}, \opt{scale-script} or \opt{scale-scriptscript}); an explicit \macroMeta{factor} overrides the factor in whichever style the call sits. With \opt{scale-absolute} set to \opt{true} (the default), the content is set to text size and the factor is subsequently applied. With \opt{false}, the content is set in the math style of the surrounding context \textit{before} being scaled, so scaling compounds with \TeX's own shrinking factor. Its options are listed in Table~\ref{tb:zscale}.

\begin{syntax}
  \cs{zscale}\macroOpt{factor}\macroArg{math}
\end{syntax}

\begin{macroTable}{tb:zscale}{Options for \cs{zscale}.}

    \opt{scale-absolute}
        & \optval{scale\@absolute}
        & \opt{true}: the factors multiply the content set in the \textit{normal} size (display style in display context, text style otherwise).
        \opt{false}: the factors multiply the content set in the ambient style, as \TeX\ would, so both factors stack (all factors $1$ gives plain \LaTeX scaling).
        In both cases, \opt{scale-scriptscript} is set as the lower bound and nested calls do not scale below that (unless set explicitly).
    \\

    \opt{scale-display}
        & \optval{scale\@display}
        & Scale factor applied by \cs{zscale} in display style.
    \\

    \opt{scale-text}
        & \optval{scale\@text}
        & As \opt{scale-display}, in text style.
    \\

    \opt{scale-script}
        & \optval{scale\@script}
        & As \opt{scale-display}, in script style.
    \\

    \opt{scale-scriptscript}
        & \optval{scale\@scriptscript}
        & As \opt{scale-display}, in scriptscript style.
    \\

\end{macroTable}

The macro is inherently safe for direct deployment across both math configurations and ambient text strings via an internal \cs{ensuremath} boundary context. The following example compares factors, call contexts and a plain subscript:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.72\linewidth
  }
  $A_{XYZ} \ne A_{\zscale{XYZ}}$            % default scaling
  \nl
  $A_{XYZ} \ne A_{\zscale[0.6]{XYZ}}$       % 60% scaling
  \nl
  $e^{A_{XYZ}} \ne e^{A_{\zscale{XYZ}}}$    % context-aware scaling
\end{tcblisting}

Since a scaled box is invisible to \TeX's math styles, an explicit guard is set for nested calls (\eg \cs{zscale\{\cs{zscale\{\macroArg{math}\}}\}}) to avoid illegible symbols. The size of scriptscript style, \ie{} \opt{scale-scriptscript}, is a lower bound for scaling. However, a factor that is already smaller than that (passed as an argument or set as an option) is still accepted:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.75\linewidth
  }
  \[
    X \to \zscale{X} \ne \zscale[0.4]{X}                % display
  \]
  $ X \to \zscale{X} \ne \zscale[0.4]{X} $              % text
  \nl
  $ X^X \to X^{\zscale{X}} \ne X^{\zscale[0.4]{X}} $    % script
  \nl
  $ X^{X^X} \to X^{X^{\zscale{X}}} $                    % scriptscript
\end{tcblisting}

Other commands that scale content using \cs{zscale} have four scale options, one per math style, and a switch analogous to \opt{scale-absolute}, so scaling choices remain independent. The reference is the style of the call for \cs{zscale}, as well as \cs{zdot}, \cs{zarg} and \cs{zprime}. But the reference is the script style of the nucleus, one level below it and never below scriptscript, for \cs{zscript}, \cs{zlim} and \cs{zint}.

\textbf{Choosing scaling factors.} Factors can be chosen by deciding how large the output should be compared to standard \TeX\ behavior. If that reference size relative to the normal size is $r$, and the wanted fraction is $k$, then:
\begin{itemize}[nosep]
  \item when \opt{scale-absolute} is set to \opt{true}, the factor multiplies the normal size, so the output is scaled to $k \times r$;
  \item when \opt{scale-absolute} is set to \opt{false}, the content is already set at the reference size, so the output is scaled to $k$.
\end{itemize}
Most math fonts shrink script and scriptscript style to about $70\%$ and $50\%$ of the normal size, \ie{} $r \approx 0.7$ and $r \approx 0.5$. So, the factor for a script-size symbol must be $k \times r$ in absolute mode, or $k$ in relative mode; \eg{} $0.9 \times 0.7 = 0.63$ in absolute mode (or $0.9$ in relative mode) makes it $90\%$ of the standard script-size symbol. The following examples show relative scaling set with \cs{setkeys}. They compare unscaled output against the default scaling (absolute), against a relative scaling with unchanged factors, and against a relative scaling with all factors changed to $0.8$:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.8\linewidth
  }
  $X \; X^X \; X^{X^X}$                                   % TeX
  \nl
  $\zscale{X} \; X^{\zscale{X}} \; X^{X^{\zscale{X}}}$    % zscale
  \nl[3]
  {
    \setkeys{shorthand}{scale-absolute=false}
    $\zscale{X} \; X^{\zscale{X}} \; X^{X^{\zscale{X}}}$  % relative
  }
  \nl[10]
  {
    \setkeys{shorthand}{
      scale-absolute=false,
      scale-display=0.8,
      scale-text=0.8,
      scale-script=0.8,
      scale-scriptscript=0.8
    }
    $\zscale{X} \; X^{\zscale{X}} \; X^{X^{\zscale{X}}}$  % relative, k = 0.8
  }
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zdot} — bold dot-product operator}
% ------------------------------------------------------------------------------

\macroDescription{\zdot}
The \cs{zdot} command produces a visually heavier centred dot for use as a vector or tensor dot-product operator, offering a clear typographic distinction from the standard \cs{cdot}. The \cs{zdot} command takes no arguments. Place it between operands exactly as you would \cs{cdot} or \cs{times}. Its options are listed in Table~\ref{tb:zdot}.

\begin{syntax}
  \cs{zdot}
\end{syntax}

\begin{macroTable}{tb:zdot}{Options for \cs{zdot}.}

    \opt{zdot-scale-absolute}
        & \optval{dot\@scale\@absolute}
        & As \opt{scale-absolute}, for \cs{zdot}.
    \\

    \opt{zdot-scale-display}
        & \optval{dot\@scale\@display}
        & Scale factor applied to \cs{cdot} when \cs{zdot} is typeset in display style. Increase for a heavier dot, decrease to bring it closer to \cs{cdot}.
    \\

    \opt{zdot-scale-text}
        & \optval{dot\@scale\@text}
        & As \opt{zdot-scale-display}, in text style.
    \\

    \opt{zdot-scale-script}
        & \optval{dot\@scale\@script}
        & As \opt{zdot-scale-display}, in script style (\eg{} inside an exponent).
    \\

    \opt{zdot-scale-scriptscript}
        & \optval{dot\@scale\@scriptscript}
        & As \opt{zdot-scale-display}, in scriptscript style.
    \\

\end{macroTable}

The glyph is constructed by scaling \cs{cdot} with the \opt{zdot-scale-}\macroMeta{style} option of the ambient math style (see \opt{zscale}) and moving it vertically so that it sits exactly on the axis of the ambient style, which compensates for the baseline drift that \cs{scalebox} introduces in math mode, in any scale. The command is declared as \cs{mathbin} so that surrounding spacing follows binary-operator conventions. If the dot looks too close in weight to \cs{cdot}, or too heavy inside exponents, adjust the scale of the corresponding style.

The following example contrasts \cs{zdot} with the regular \cs{cdot} between vectors and shows the output in different font sizes:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.75\linewidth
  }
  \[
    W = \vec{F} \zdot \vec{d}                           % display
  \]
  \nl
  $u \cdot v \ne \vec{u} \zdot \vec{v}$                 % text
  \nl
  $e^{u \cdot v} \ne e^{\vec{u} \zdot \vec{v}}$         % script
  \nl
  $e^{A_{u \cdot v}} \ne e^{A_{\vec{u} \zdot \vec{v}}}$ % scriptscript
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zarg} — scaled function argument}
% ------------------------------------------------------------------------------

\macroDescription{\zarg}
The \cs{zarg} utility typesets an expression \macroMeta{expr} inside parentheses, scaled, and inserting a small kern immediately before the opening delimiter. This is useful to distinguish function arguments from other uses of parentheses. Its options are listed in Table~\ref{tb:zarg}.

\begin{syntax}
  \cs{zarg}\macroArg{expr}
\end{syntax}

\begin{macroTable}{tb:zarg}{Options for \cs{zarg}.}

    \opt{zarg-scale-absolute}
        & \optval{arg\@scale\@absolute}
        & As \opt{scale-absolute}, for \cs{zarg}.
    \\

    \opt{zarg-scale-display}
        & \optval{arg\@scale\@display}
        & Scale factor applied to the parenthesised argument block when \cs{zarg} is typeset in display style.
    \\

    \opt{zarg-scale-text}
        & \optval{arg\@scale\@text}
        & As \opt{zarg-scale-display}, in text style.
    \\

    \opt{zarg-scale-script}
        & \optval{arg\@scale\@script}
        & As \opt{zarg-scale-display}, in script style (\eg{} inside an exponent).
    \\

    \opt{zarg-scale-scriptscript}
        & \optval{arg\@scale\@scriptscript}
        & As \opt{zarg-scale-display}, in scriptscript style.
    \\

    \opt{zarg-kern}
        & \optval{arg\@kern}
        & Horizontal kern inserted immediately before the opening parenthesis; its sign and size fine-tune the gap after the function name.
    \\

\end{macroTable}

The scale factors (\opt{zarg-scale-}\macroMeta{style}, see \opt{zscale}) and horizontal kern (\opt{zarg-kern}) options fine-tune the size and gap between a parent function identifier and its target argument block. It adds no space of its own, so any spacing around it comes from the surrounding source and math atoms alone. It is compatible with text, inline and display modes, and ensures consistent visual density across different font families. Options are governed dynamically, so changes mid-document are supported.

The following examples show a simple argument in math mode, a larger expression as function argument, and the same command used both in text and in math modes:

\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.62\linewidth
  }
  $f(x) \ne f\zarg{x}$    % comparison against parentheses
  \nl
  \[
    f\left( x^2 - \frac{1}{x} + 1 \right) % dynamic delim.
    \ne
    f\zarg{x^2 - \frac{1}{x} + 1} 
  \]
  \nl
  sin\zarg{\theta/2} $ = \text{sin}\zarg{\theta/2}$
\end{tcblisting}

The scaling follows the math style of the call, so the argument shrinks inside an exponent, and a larger kern opens the gap after the function name:

\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.62\linewidth
  }
  $e^{f(x)} \ne e^{f\zarg{x}}$    % context aware
  \nl[2]
  {
    \setkeys{shorthand}{zarg-kern=3mu}
    $f\zarg{x}$                   % wider gap
  }
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zdiff} — differential or derivative}
% ------------------------------------------------------------------------------

\macroDescription{\zdiff}
The \cs{zdiff} utility typesets either a differential or a derivative operator with respect to \macroMeta{var}, optionally raised to a given \macroMeta{order} (default 1). It is compatible with text, inline and display modes, wrapping its output in \cs{ensuremath}. Its options are listed in Table~\ref{tb:zdiff}.

\begin{syntax}
  \cs{zdiff}\macroPlus\macroStar\macroStar\macroOpt{order}\macroArg{var}
\end{syntax}

Starring:
\begin{itemize}[nosep]
  \item \textbf{none (-)} — differential, $\text{d}^{\macroMeta{order}}\macroMeta{var}$, set as a \cs{mathinner} atom: \TeX\ itself supplies the usual thin space against neighbouring ordinary atoms (\eg{} right after \cs{zarg}) in display and text style, none in script styles, and the regular binary or relation spacing after operators such as \cs{zdot}.
  \item \textbf{one (\macroStar)} — derivative, as a standard \cs{frac}, followed by a larger space (\opt{zdiff-kern}).
  \item \textbf{two (\macroStar\macroStar)} — derivative, as an oblique \cs{nicefrac}.
\end{itemize}

\begin{macroTable}{tb:zdiff}{Options for \cs{zdiff}.}

    \opt{zdiff-math-separation}
        & \optval{diff\@math\@separation}
        & Extra kern inserted before "d" in differential form when \cs{zdiff} is called with a leading \macroPlus\ in display math style. It is \textit{added} to the thin space that \TeX\ already applies.
    \\

    \opt{zdiff-text-separation}
        & \optval{diff\@text\@separation}
        & Same as \opt{zdiff-math-separation}, applied automatically instead whenever \cs{zdiff} is typeset in text, script, or scriptscript style.
    \\

    \opt{zdiff-kern}
        & \optval{diff\@kern}
        & Kern inserted after the fraction in derivative form, separating it from the following operand.
    \\

\end{macroTable}

The following example prints a differential, a higher-order differential, and the two derivative layouts:

\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.7\linewidth,
    halign lower=center,
  }
  \zdiff{x}                                 % differential
  \nl
  \zdiff[2]{x}                              % differential, order 2
  \nl
  $\zdiff*{x}f \ne \zdiff*[2]{x}f$          % derivative, \frac
  \nl
  $\zdiff**{x}(f) \ne \zdiff**[2]{x}(f)$    % derivative, \nicefrac
\end{tcblisting}

Leaving the bare form free of extra kerns also keeps it usable as an operand. The following example shows that a hand-built derivative of two differentials reproduces the same spacing as writing the fraction out by hand:
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.7\linewidth,
    halign lower=center,
  }
  \[
  \frac{\zdiff{f}}{\zdiff{x}}
  =
  \frac{\text{d}f}{\text{d}x}
  \]
\end{tcblisting}

A leading \macroPlus, meaningful only in differential form, adds a kern before the "d" on top of the spacing \TeX\ already provides (\opt{zdiff-math-separation} in display style, \opt{zdiff-text-separation} in text/script/scriptscript style; chosen automatically to match the ambient math style, similarly to \cs{zint}'s math/text split). Intended to be used when clear visual separation is needed. The following example compares the default and increased spacing in potential use cases:
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
    halign lower=center,
  }
  \begin{gather*}
    \int \vec{u} \zdot \zdiff{\vec{A}}    % default
    \quad \ne \quad
    \int f\zarg{\vec{x}} \zdiff+[2]{x}    % spaced
  \end{gather*}
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zcond} — bar to represent evaluation conditions}
% ------------------------------------------------------------------------------

\macroDescription{\zcond}
The \cs{zcond} utility typesets a vertical bar to represent evaluation conditions, with \macroMeta{condition} as a subscript. When \macroMeta{expr} is supplied and no stars are given, the bar auto-sizes via \cs{left.}\,\macroMeta{expr}\,\macroBar{right}, tracking \macroMeta{expr}'s height. Each star instead selects a fixed bar size, in which case \macroMeta{expr} is printed as-is, without \cs{left}/\cs{right} wrapping. It is compatible with text, inline and display modes, wrapping its output in \cs{ensuremath}. It has no package options.

\begin{syntax}
  \cs{zcond}\macroStar\macroStar\macroStar\macroStar\macroOpt{expr}\macroArg{condition}
\end{syntax}

Starring:
\begin{itemize}[nosep]
  \item \textbf{none (-)} — auto-sized bar.
  \item \textbf{one (\macroStar)} — fixed \macroBar{big}.
  \item \textbf{two (\macroStar\macroStar)} — fixed \macroBar{Big}.
  \item \textbf{three (\macroStar\macroStar\macroStar)} — fixed \macroBar{bigg}.
  \item \textbf{four (\macroStar\macroStar\macroStar\macroStar)} — fixed \macroBar{Bigg}.
\end{itemize}

The following example prints the five bar sizes side by side:

\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.7\linewidth,
    halign lower=center,
  }
  \zcond{x=0}\zcond*{x=0}\zcond**{x=0}\zcond***{x=0}\zcond****{x=0}
\end{tcblisting}

The \macroMeta{condition} subscript is scaled by \cs{zscale} only in the auto-sized (no-star) path; it is printed at full size whenever any star is given. The following example shows the bar after a derivative, with an auto-sized bar around \macroMeta{expr}, and with a fixed-size bar:

\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.7\linewidth,
    halign lower=center,
  }
  $\zdiff**{x}g \zcond{x=0}$         % default size
  \nl
  $\zcond[\zdiff*{x}g]{x=0}$         % auto-sized
  \nl
  $\zcond**[\zdiff*{x}g]{x=0}$       % fixed \Big|
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zscript} — four-way sub/superscripts}
% ------------------------------------------------------------------------------

\macroDescription{\zscript}
The \cs{zscript} engine attaches up to four independent scripts to a central \macroMeta{nucleus}. It simultaneously handles leading (pre-indexed) subscripts \macroMeta{ll} and superscripts \macroMeta{ul}, alongside conventional trailing subscripts \macroMeta{lr} and superscripts \macroMeta{ur}. Omitting any optional script completely suppresses its rendering footprint. The command is compatible with text, inline and display modes. Its options are listed in Table~\ref{tb:zscript}.

\begin{syntax}
  \cs{zscript}\macroPlus\macroStar\macroOpt{ll}\macroStar\macroOpt{ul}\macroArg{nucleus}\macroStar\macroOpt{lr}\macroStar\macroOpt{ur}
\end{syntax}

\begin{macroTable}[Option & Math & Text & Description]{tb:zscript}{Options for \cs{zscript}. The \macroMeta{mode} is \opt{math} (display) or \opt{text} (text, script and scriptscript).}

    \macroRow{Pre-rendering}
    \opt{zscript-adaptative}
        & \macroSpan{\optval{script\@adaptative}}
        & \opt{true}: scripts are offset from nucleus edges. \opt{false}: \TeX's classical placement (position and frame options are ignored). A leading \macroPlus\ modifier locally flips this.
    \\
    \opt{zscript-wrapper}
        & \macroSpan{\cs{symup}}
        & Single-argument macro applied to every script.
    \\

    \macroRow{Starred Scripts}
    \opt{zscript-scale-absolute}
        & \macroSpan{\optval{script\@scale\@absolute}}
        & As \opt{scale-absolute}, for starred scripts.
    \\
    \opt{zscript-scale-display}
        & \macroSpan{\optval{script\@scale\@display}}
        & Factor by which a starred script is scaled according to an unstarred one, for a nucleus in display style.
    \\
    \opt{zscript-scale-text}
        & \macroSpan{\optval{script\@scale\@text}}
        & As \opt{zscript-scale-display}, for text style.
    \\
    \opt{zscript-scale-script}
        & \macroSpan{\optval{script\@scale\@script}}
        & As \opt{zscript-scale-display}, for script style.
    \\
    \opt{zscript-scale-scriptscript}
        & \macroSpan{\optval{script\@scale\@scriptscript}}
        & As \opt{zscript-scale-display}, for scriptscript style.
    \\

    \macroRow{Frame}
    \macroKey{zscript}{before}
        & \optval{script\@math\@before} & \optval{script\@text\@before}
        & Extra width reserved before the output.
    \\
    \macroKey{zscript}{after}
        & \optval{script\@math\@after} & \optval{script\@text\@after}
        & Extra width reserved after the output.
    \\
    \macroKey{zscript}{above}
        & \optval{script\@math\@above} & \optval{script\@text\@above}
        & Extra height reserved above the output.
    \\
    \macroKey{zscript}{below}
        & \optval{script\@math\@below} & \optval{script\@text\@below}
        & Extra depth reserved below the output.
    \\

    \macroRow{Trailing Scripts}
    \macroKey{zscript}{ur-v}
        & \optval{script\@math\@ur\@v} & \optval{script\@text\@ur\@v}
        & Nucleus \emph{top} edge to upper-right script \emph{bottom} edge.
    \\
    \macroKey{zscript}{ur-h}
        & \optval{script\@math\@ur\@h} & \optval{script\@text\@ur\@h}
        & Nucleus \emph{right} edge to upper-right script \emph{left} edge.
    \\
    \macroKey{zscript}{lr-v}
        & \optval{script\@math\@lr\@v} & \optval{script\@text\@lr\@v}
        & Nucleus \emph{bottom} edge to lower-right script \emph{top} edge.
    \\
    \macroKey{zscript}{lr-h}
        & \optval{script\@math\@lr\@h} & \optval{script\@text\@lr\@h}
        & Nucleus \emph{right} edge to lower-right script \emph{left} edge.
    \\

    \macroRow{Leading Scripts}
    \macroKey{zscript}{ul-v}
        & \optval{script\@math\@ul\@v} & \optval{script\@text\@ul\@v}
        & Nucleus \emph{top} edge to upper-left script \emph{bottom} edge.
    \\
    \macroKey{zscript}{ul-h}
        & \optval{script\@math\@ul\@h} & \optval{script\@text\@ul\@h}
        & Nucleus \emph{left} edge to upper-left script \emph{right} edge.
    \\
    \macroKey{zscript}{ll-v}
        & \optval{script\@math\@ll\@v} & \optval{script\@text\@ll\@v}
        & Nucleus \emph{bottom} edge to lower-left script \emph{top} edge.
    \\
    \macroKey{zscript}{ll-h}
        & \optval{script\@math\@ll\@h} & \optval{script\@text\@ll\@h}
        & Nucleus \emph{left} edge to lower-left script \emph{right} edge.
    \\

\end{macroTable}

Script placement is determined by the \opt{zscript-adaptative} option, to either use the standard \TeX\ engine or a dedicated internal engine with high customizability. The employment of a \macroPlus\ modifier directly following \cs{zscript} flips this placement choice. For both engines, applying a \macroStar\ modifier immediately before any script argument scales that script by the \opt{zscript-scale-}\macroMeta{style} option, where \macroMeta{style} is the math style of the nucleus (using \opt{zscale}, so nesting cannot bring a size below \opt{zscript-scale-scriptscript}). When using the dedicated engine, scripts are explicitly positioned boxes rather than using \TeX's script machinery, so they may freely overlap the nucleus (Figure \ref{fig:zscript}). All positions use one Cartesian system ($x$ positive right, $y$ positive up) and are measured from a \textit{nucleus edge} to the \textit{nearest script edge} as dimensionless ratios. Vertical options (\opt{v}, \opt{above}, \opt{below}) are relative to the x-height, and horizontal ones (\opt{h}, \opt{before}, \opt{after}) to the quad, both in the nucleus's math style. So, the same settings work for nuclei and scripts of any size, and rescaling a script moves its outer edge away from the nucleus without changing its anchor. The output is a single box whose height and depth encompass the nucleus and all scripts, preventing collisions with adjacent lines and exposing its true dimensions to subsequent commands (\eg{} further scripts or \cs{left}/\cs{right}, as shown below). The \opt{before}, \opt{after}, \opt{above} and \opt{below} options add (or remove, when negative) clearance around it.

\begin{figure}[htbp]
  \centering
  \begin{tikzpicture}[scale=0.7, >=Stealth]
    % output frame, union of nucleus and scripts, nucleus and scripts
    \draw[zmframe] (-1.7,-1.0) rectangle (4.8,3.0);
    \draw[zmunion] (-1.3,-0.5) rectangle (4.3,2.5);
    \draw[zmglyph] (0,0) rectangle (3,2);
    \node at (1.5,1) {\Large $M$};
    \draw[zmlim] (3.3,1.6) rectangle (4.3,2.5)  node[midway] {ur};
    \draw[zmlim] (3.2,-0.5) rectangle (4.2,0.4) node[midway] {lr};
    \draw[zmlim] (-1.3,1.6) rectangle (-0.3,2.5) node[midway] {ul};
    \draw[zmlim] (-1.2,-0.5) rectangle (-0.2,0.4) node[midway] {ll};
    % nucleus edges
    \draw[zmref] (-2.4,2) -- (5.5,2);
    \draw[zmref] (-2.4,0) -- (5.5,0);
    \draw[zmref] (0,-1.9) -- (0,3.7);
    \draw[zmref] (3,-1.9) -- (3,3.7);
    % vertical options, right
    \draw[zmext] (4.3,1.6) -- (5.5,1.6);
    \draw[zmdim] (5.3,2.0) -- node[zmlbl, right] {ur-v} (5.3,1.6);
    \draw[zmext] (4.2,0.4) -- (5.5,0.4);
    \draw[zmdim] (5.3,0.0) -- node[zmlbl, right] {lr-v} (5.3,0.4);
    % vertical options, left
    \draw[zmext] (-1.3,1.6) -- (-2.4,1.6);
    \draw[zmdim] (-2.3,2.0) -- node[zmlbl, left] {ul-v} (-2.3,1.6);
    \draw[zmext] (-1.2,0.4) -- (-2.4,0.4);
    \draw[zmdim] (-2.3,0.0) -- node[zmlbl, left] {ll-v} (-2.3,0.4);
    % horizontal options, top
    \draw[zmext] (3.3,2.5) -- (3.3,3.7);
    \draw[zmdim] (3,3.6) -- node[zmlbl, above] {ur-h} (3.3,3.6);
    \draw[zmext] (-0.3,2.5) -- (-0.3,3.7);
    \draw[zmdim] (0,3.6) -- node[zmlbl, above] {ul-h} (-0.3,3.6);
    % horizontal options, bottom
    \draw[zmext] (3.2,-0.5) -- (3.2,-1.9);
    \draw[zmdim] (3,-1.8) -- node[zmlbl, below] {lr-h} (3.2,-1.8);
    \draw[zmext] (-0.2,-0.5) -- (-0.2,-1.9);
    \draw[zmdim] (0,-1.8) -- node[zmlbl, below] {ll-h} (-0.2,-1.8);
    % frame clearances
    \draw[zmdim] (1.5,2.5) -- node[zmlbl, right] {above} (1.5,3.0);
    \draw[zmdim] (1.5,-0.5) -- node[zmlbl, right] {below} (1.5,-1.0);
    \draw[zmdim] (-1.3,1.0) -- node[zmlbl, above] {before} (-1.7,1.0);
    \draw[zmdim] (4.3,1.0) -- node[zmlbl, above] {after} (4.8,1.0);
  \end{tikzpicture}
  \caption{Schematic of the \cs{zscript} options, written without the \opt{zscript-}\macroMeta{mode}\opt{-} prefix. Each script is anchored by its nearest edge to an edge of the nucleus (dashed references), at a distance given as a ratio of the x-height (vertical) or quad (horizontal) of the nucleus' style. The thick frame is the box \cs{zscript} hands to \TeX; the dashed rectangle is the union of nucleus and scripts, extended by the frame options. Distances are exaggerated for legibility.}
  \label{fig:zscript}
\end{figure}

The following examples show scripts in text and math modes, with and without scaling, inside an exponent, and demonstrate its spacing:
\begin{tcblisting}{
    math-shorthandz-tex,
    %halign lower=center,
    lefthand width=0.65\linewidth
  }
  $\zscript[I][K]{M}[J][L]$               % Default scripts
  \nl
  $\zscript*[I]*[K]{M}*[J]*[L]$           % Scaled scripts
  \nl
  $e^{-\zscript{x}[J]} \ne e^{-\zscript{x}*[J]}$
  \nl
  \[
    \left( \zscript{\sum}[a][b] \right)   % Output size
  \]
  \nl
  \zscript{A}[i][2]                       % Safe in text
  \nl
  Previous line, no overlap.\\
  Tall inline output: \zscript[I][K]{\sum}[J][L]. \\
  Subsequent line, no overlap.
\end{tcblisting}

Every script is wrapped in \opt{zscript-wrapper}, which may be any macro taking one argument (\eg{} \cs{textit}). The nucleus is never wrapped. Three settings for the option are recommended; they differ in usage procedure for each type of script (variables, math symbols, labels, un/signed numbers):
\begin{itemize}[nosep]
  \item \cs{symup} (default, compact) — math symbols, digits and signs are allowed and do not require \texttt{\$}\ldots\texttt{\$} wrapping, since the script is already in math mode. Variables must be written as \cs{symit}\macroArg{variable} to not show as text. Some labels must be written as \cs{text}\macroArg{label} (since, without it, \eg spaces are ignored, hyphens become minus signs, \etc). This is the default because descriptive labels tend to be the most common type of script.
  \item \cs{text} (standard) — all labels are allowed (with spaces, hyphens, \etc). Variables, math symbols and signs must be wrapped by \texttt{\$}\ldots\texttt{\$}, exactly as inside \cs{text}. This may become cumbersome when scripts tend to show math symbols and signs (\eg exponents).
  \item empty (plain) — scripts are set in the ambient math alphabet, as plain \TeX\ does, for full control. All labels must be written \cs{text}\macroArg{label}.
\end{itemize}

The following examples demonstrate the outputs for each recommendation, and comment on what is unwanted in each application:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.72\linewidth
  }
  \[
    \zscript[\mu][\symit{p}]{R}[pre\text{-}ion][-1]
    \ne
    \zscript[\mu][p]{R}[pre-ion][-1]        % variable, hyphen
  \]
  \nl[3]
  \[
    \setkeys{shorthand}{zscript-wrapper=\text}
    \zscript[$\mu$][$p$]{R}[pre-ion][$-1$]
    \ne
    \zscript[\mu][p]{R}[pre-ion][-1]        % greek, variable, minus
  \]
  \nl[3]
  \[
    \setkeys{shorthand}{zscript-wrapper=}
    \zscript[\mu][p]{R}[\text{pre-ion}][-1]
    \ne
    \zscript[\mu][p]{R}[pre-ion][-1]        % label
  \]
\end{tcblisting}

It should also be emphasized that the placement of scripts with the dedicated engine adapts to the size of the nucleus. For example, a script follows the nucleus's height (since positions are measured from its edges), whereas the \TeX\ engine applies a font-dependent shift from the baseline (which is enforced even for symbols like \cs{int} and \cs{sum}). The following examples compare the placement for nuclei of different shapes with both engines:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.72\linewidth
  }
  \begin{gather*}
    \zscript{k}[T] \ne k_{\text{T}} = \zscript+{k}[T]
    \nl[0.5]
    \zscript{g}[T] \ne g_{\text{T}} = \zscript+{g}[T]
    \nl[0.5]
    \zscript{\sum}[T] \ne \sum_{\text{T}} \ne \zscript+{\sum}[T]
  \end{gather*}
  \nl[2]
  {
    \setkeys{shorthand}{zscript-adaptative=false}
    \begin{gather*}
      \zscript{k}[T] = k_{\text{T}} \ne \zscript+{k}[T]
      \nl[0.5]
      \zscript{g}[T] = g_{\text{T}} \ne \zscript+{g}[T]
      \nl[0.5]
      \zscript{\sum}[T] \ne \sum_{\text{T}} \ne \zscript+{\sum}[T]
  \end{gather*}
  }
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zprime} — prime accents}
% ------------------------------------------------------------------------------

\macroDescription{\zprime}
The \cs{zprime} utility adorns a target \macroMeta{symbol} with a specified number \macroOpt{n} of prime marks (default $n=1$). Its size automatically tracks the math style of the symbol being primed, through one scale factor per style (\opt{zprime-scale-}\macroMeta{style}, see \opt{zscale}), so primes shrink when the symbol already sits inside a script — \ie{} an exponent, a subscript, and so on. This makes \cs{zprime} safe to nest inside other scripts without looking oversized, and lets \cs{left}/\cs{right} delimiters around a primed expression size correctly, since the output box covers both the symbol and the primes. Its options are listed in Table~\ref{tb:zprime}.

\begin{syntax}
  \cs{zprime}\macroStar\macroOpt{n}\macroOpt{v}\macroOpt{h}\macroArg{symbol}
\end{syntax}

Starring:
\begin{itemize}[nosep]
  \item \textbf{none (-)} — superscript-style layout, primes flush to the symbol's right edge.
  \item \textbf{one (\macroStar)} — accent-style layout, primes centered above the symbol as a group, regardless of the number of marks.
\end{itemize}

\begin{macroTable}[Option & Math & Text & Description]{tb:zprime}{Options for \cs{zprime}. The \macroMeta{mode} is \opt{math} (display) or \opt{text} (text, script and scriptscript).}

    \macroRow{Cluster}
    \opt{zprime-separation}
        & \macroSpan{\optval{prime\@sep}}
        & Mu-unit kern inserted between consecutive prime glyphs, scaled together with them. Fine-grained; use a few mu to get a visible change.
    \\
    \opt{zprime-scale-absolute}
        & \macroSpan{\optval{prime\@scale\@absolute}}
        & As \opt{scale-absolute}, for the prime cluster.
    \\
    \opt{zprime-scale-display}
        & \macroSpan{\optval{prime\@scale\@display}}
        & Scale factor applied to the prime cluster when the symbol being primed sits in display style.
    \\
    \opt{zprime-scale-text}
        & \macroSpan{\optval{prime\@scale\@text}}
        & As \opt{zprime-scale-display}, in text style.
    \\
    \opt{zprime-scale-script}
        & \macroSpan{\optval{prime\@scale\@script}}
        & As \opt{zprime-scale-display}, in script style.
    \\
    \opt{zprime-scale-scriptscript}
        & \macroSpan{\optval{prime\@scale\@scriptscript}}
        & As \opt{zprime-scale-display}, in scriptscript style.
    \\

    \macroRow{Frame}
    \macroKey{zprime}{before}
        & \optval{prime\@math\@before} & \optval{prime\@text\@before}
        & Extra width reserved before the output.
    \\
    \macroKey{zprime}{after}
        & \optval{prime\@math\@after} & \optval{prime\@text\@after}
        & Extra width reserved after the output.
    \\
    \macroKey{zprime}{above}
        & \optval{prime\@math\@above} & \optval{prime\@text\@above}
        & Extra height reserved above the output.
    \\
    \macroKey{zprime}{below}
        & \optval{prime\@math\@below} & \optval{prime\@text\@below}
        & Extra depth reserved below the output.
    \\

    \macroRow{Superscript Form}
    \macroKey{zprime}{script-v}
        & \optval{prime\@math\@script\@v} & \optval{prime\@text\@script\@v}
        & Symbol \emph{top} edge to  prime cluster \emph{bottom} edge.
    \\
    \macroKey{zprime}{script-h}
        & \optval{prime\@math\@script\@h} & \optval{prime\@text\@script\@h}
        & Symbol \emph{right} edge to prime cluster \emph{left} edge.
    \\

    \macroRow{Accent Form}
    \macroKey{zprime}{accent-v}
        & \optval{prime\@math\@accent\@v} & \optval{prime\@text\@accent\@v}
        & Symbol \emph{top} edge to prime cluster \emph{bottom} edge.
    \\
    \macroKey{zprime}{accent-h}
        & \optval{prime\@math\@accent\@h} & \optval{prime\@text\@accent\@h}
        & Shift of the cluster from its centred position.
    \\

\end{macroTable}

All positions share one Cartesian system ($x$ positive to the right, $y$ positive upward) and are measured from the \emph{edges of the symbol} to the \emph{nearest edge} of the prime cluster: the vertical position is the $y$ coordinate of the cluster's bottom edge, so negative values lower the primes into the symbol, while the horizontal position is the cluster's shift from its reference (the symbol's right edge for \opt{script}, centred for \opt{accent}). All values are \textit{dimensionless ratios}, with vertical options (\opt{v}, \opt{above}, \opt{below}) relative to the x-height and horizontal ones (\opt{h}, \opt{before}, \opt{after}) to the quad, both in the symbol's math style, so the same values remain visually consistent across styles and scales, including exponents. The optional \macroMeta{v} and \macroMeta{h} (default: empty, \ie{} the package setting for the chosen form and mode) \textit{replace} the corresponding \opt{zprime-}\macroMeta{mode}\opt{-script-v/h} or \opt{zprime-}\macroMeta{mode}\opt{-accent-v/h} setting for the current call, providing local corrections especially useful for tall or wide nuclei such as \cs{int} or \cs{sum}, with or without their own limits (Figure~\ref{fig:zprime}); the examples below illustrate both layouts, script sizing, math-style adaptation, and use inside \cs{left}/\cs{right} delimiters:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.72\linewidth
  }
  \zprime{x} $\ne$ \zprime*{x}              % superscript vs accent
  \nl
  $\zprime[2]{y} \ne \zprime*[2]{y}$        % double primes
  \nl
  $e^{-\zprime{x}} \ne e^{-\zprime*{x}}$    % context aware
  \nl
  \[
    \left(1 - \zprime{x}\right)^2           % \left and \right
    \ne
    \left(1 - \zprime*{x}\right)^2
  \]
\end{tcblisting}

\begin{figure}[htbp]
  \centering
  \begin{subfigure}[b]{0.48\linewidth}
    \centering
    \begin{tikzpicture}[scale=0.8, >=Stealth]
      % output frame, nucleus, reference lines and prime cluster
      \draw[zmframe] (-0.3,-0.5) rectangle (3.8,3.2);
      \draw[zmglyph] (0,0) rectangle (2,2);
      \node at (1,0.8) {\Large $x$};
      \draw[zmref] (2,-0.3) -- (2,3.6);
      \draw[zmref] (-0.5,2) -- (4.9,2);
      \draw[zmlim] (2.5,1.4) rectangle (3.5,2.6);
      \node at (3,2.05) {$\prime\prime$};
      % vertical: nucleus top edge to cluster bottom edge
      \draw[zmext] (3.5,1.4) -- (5.0,1.4);
      \draw[zmdim] (4.9,2.0) -- node[zmlbl, right] {script-v} (4.9,1.4);
      % horizontal: nucleus right edge to cluster left edge
      \draw[zmext] (2.5,2.6) -- (2.5,3.4);
      \draw[zmdim] (2,3.3) -- node[zmlbl, above] {script-h} (2.5,3.3);
      % output frame clearances
      \draw[zmext] (3.5,2.6) -- (4.3,2.6);
      \draw[zmext] (3.8,3.2) -- (4.3,3.2);
      \draw[zmdim] (4.2,2.6) -- node[zmlbl, right] {above} (4.2,3.2);
      \draw[zmext] (2,0) -- (4.3,0);
      \draw[zmext] (3.8,-0.5) -- (4.3,-0.5);
      \draw[zmdim] (4.2,0) -- node[zmlbl, right] {below} (4.2,-0.5);
      \draw[zmext] (-0.3,-0.5) -- (-0.3,-1.2);
      \draw[zmext] (0,0) -- (0,-1.2);
      \draw[zmdim] (0,-1.1) -- node[zmlbl, below] {before} (-0.3,-1.1);
      \draw[zmext] (3.5,1.4) -- (3.5,-1.2);
      \draw[zmext] (3.8,-0.5) -- (3.8,-1.2);
      \draw[zmdim] (3.5,-1.1) -- node[zmlbl, below] {after} (3.8,-1.1);
    \end{tikzpicture}
    \caption{Superscript form (unstarred). Reference: right edge.}
  \end{subfigure}
  \hfill
  \begin{subfigure}[b]{0.48\linewidth}
    \centering
    \begin{tikzpicture}[scale=0.8, >=Stealth]
      % output frame, nucleus, reference lines and prime cluster
      \draw[zmframe] (-0.3,-0.5) rectangle (2.4,3.2);
      \draw[zmglyph] (0,0) rectangle (2,2);
      \node at (1,0.8) {\Large $x$};
      \draw[zmref] (1,-0.3) -- (1,3.6);
      \draw[zmref] (-0.5,2) -- (4.2,2);
      \draw[zmunion] (0.5,1.4) rectangle (1.5,2.6);
      \draw[zmlim] (1.1,1.4) rectangle (2.1,2.6);
      \node at (1.6,2.05) {$\prime\prime$};
      % vertical: nucleus top edge to cluster bottom edge
      \draw[zmext] (2.1,1.4) -- (4.6,1.4);
      \draw[zmdim] (3.4,2.0) -- node[zmlbl, right] {accent-v} (3.4,1.4);
      % horizontal: centred position to actual position
      \draw[zmext] (1.6,2.6) -- (1.6,3.4);
      \draw[zmdim] (1,3.3) -- node[zmlbl, above] {accent-h} (1.6,3.3);
      % output frame clearances
      \draw[zmext] (2.1,2.6) -- (4.6,2.6);
      \draw[zmext] (2.4,3.2) -- (4.6,3.2);
      \draw[zmdim] (4.4,2.6) -- node[zmlbl, right] {above} (4.4,3.2);
      \draw[zmext] (2,0) -- (4.6,0);
      \draw[zmext] (2.4,-0.5) -- (4.6,-0.5);
      \draw[zmdim] (4.4,0) -- node[zmlbl, right] {below} (4.4,-0.5);
      \draw[zmext] (-0.3,-0.5) -- (-0.3,-1.2);
      \draw[zmext] (0,0) -- (0,-1.2);
      \draw[zmdim] (0,-1.1) -- node[zmlbl, below] {before} (-0.3,-1.1);
      \draw[zmext] (2.1,1.4) -- (2.1,-1.2);
      \draw[zmext] (2.4,-0.5) -- (2.4,-1.2);
      \draw[zmdim] (2.1,-1.1) -- node[zmlbl, below] {after} (2.4,-1.1);
    \end{tikzpicture}
    \caption{Accent form (\macroStar). Dashed box: centred position.}
  \end{subfigure}
  \caption{Schematic of the \cs{zprime} options, written without the \opt{zprime-}\macroMeta{mode}\opt{-} prefix. Each vertical option is the distance from the symbol's top edge to the cluster's bottom edge (negative values lower the primes into the symbol); each horizontal option is the shift of the cluster from its dashed reference. All are ratios of the x-height (vertical) or quad (horizontal) of the symbol's style. The thick frame is the box \cs{zprime} hands to \TeX: it covers the \textit{union} of the symbol and the cluster, extended by the signed \opt{before}, \opt{after}, \opt{above} and \opt{below} margins, so neighbouring lines are pushed away. The kern \opt{zprime-separation} between consecutive primes is not drawn; distances are exaggerated for legibility.}
  \label{fig:zprime}
\end{figure}

This example shows how primes do not overlap with adjacent lines:
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.55\linewidth,
  }
  Previous line, does not overlap.\\
  Tall nucleus: $\zprime*{\int} f \zdiff{x}$.\\
  Subsequent line, does not overlap.
\end{tcblisting}

The primes are scaled as a whole by the factor of the style of the symbol, so a larger factor enlarges the cluster together with the kern between its marks, which can also be tuned on its own:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.55\linewidth
  }
  \[
    \setkeys{shorthand}{zprime-scale-display=1.8}
    \setkeys{shorthand}{zprime-separation=-3mu}
    \zprime*[2]{\prod} \ne \zprime[2]{\prod}
  \]
\end{tcblisting}

These examples show how primes can be moved out of their default position:
\begin{tcblisting}{
    math-shorthandz-tex,
    halign lower=center,
    lefthand width=0.72\linewidth
  }  
  \nl
  \begin{gather*}
    \zprime*[1][][-0.06]{\int^{\infty}}     % pushed left
    \ne
    \zprime*{\int^{\infty}}
    \ne
    \zprime*{\int}^{\infty}
    \nl[3]
    \zprime*[3][][0.06]{\int^{\infty}}      % pushed right
    \ne
    \zprime*[3]{\int^{\infty}}
    \ne
    \zprime*[3]{\int}^{\infty}
    \nl[3]
    \zprime[2][-2.2][0.03]{\sum_j^{\infty}} % pushed down and right
    \ne
    \zprime{\sum_j^{\infty}}
  \end{gather*}
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zlim} — limit with variable and value}
% ------------------------------------------------------------------------------

\macroDescription{\zlim}
The \cs{zlim} utility typesets the operator \cs{lim} with the script \macroMeta{var}$\,\to\,$\macroMeta{limit} built from its two arguments. Without a leading \macroPlus, the script is centred below the operator in every math style; with it, the script hangs to the lower right of the operator, like a subscript, which is the compact choice inline. One-sided limits are written in \macroMeta{limit} itself, \eg $0^{+}$. The output is a single box whose height and depth encompass the operator and its script, so adjacent lines are pushed apart. The output is wrapped in \cs{ensuremath}, so it is safe in text, inline and display mode. Its options are listed in Table~\ref{tb:zlim}.

\begin{syntax}
  \cs{zlim}\macroPlus\macroStar\macroArg{var}\macroStar\macroArg{limit}
\end{syntax}

Starring and optional arguments:
\begin{itemize}[nosep]
  \item \textbf{none (-)} — script centred below the operator;
  \item \textbf{plus (\macroPlus)} — script hanging to the lower right of the operator;
  \item a \macroStar\ immediately before \macroMeta{var} or \macroMeta{limit} scales that part in its normal (script) size, but additionally scales it by \opt{zlim-scale-}\macroMeta{style}, where \macroMeta{style} is the math style of the operator (see \opt{zlim-scale-absolute}); the two parts are scaled independently.
\end{itemize}

\begin{macroTable}[Option & Math & Text & Description]{tb:zlim}{Options for \cs{zlim}. The \macroMeta{mode} is \opt{math} (display) or \opt{text} (text, script and scriptscript).}

    \macroRow{Starred Parts}
    \opt{zlim-scale-absolute}
        & \macroSpan{\optval{lim\@scale\@absolute}}
        & As \opt{scale-absolute}, for starred parts.
    \\
    \opt{zlim-scale-display}
        & \macroSpan{\optval{lim\@scale\@display}}
        & Factor by which a starred part is scaled according to an unstarred one, for an operator in display style.
    \\
    \opt{zlim-scale-text}
        & \macroSpan{\optval{lim\@scale\@text}}
        & As \opt{zlim-scale-display}, in text style.
    \\
    \opt{zlim-scale-script}
        & \macroSpan{\optval{lim\@scale\@script}}
        & As \opt{zlim-scale-display}, in script style.
    \\
    \opt{zlim-scale-scriptscript}
        & \macroSpan{\optval{lim\@scale\@scriptscript}}
        & As \opt{zlim-scale-display}, in scriptscript style.
    \\

    \macroRow{Frame}
    \macroKey{zlim}{before}
        & \optval{lim\@math\@before} & \optval{lim\@text\@before}
        & Extra width reserved before the output.
    \\
    \macroKey{zlim}{after}
        & \optval{lim\@math\@after} & \optval{lim\@text\@after}
        & Extra width reserved after the output.
    \\
    \macroKey{zlim}{above}
        & \optval{lim\@math\@above} & \optval{lim\@text\@above}
        & Extra height reserved above the output.
    \\
    \macroKey{zlim}{below}
        & \optval{lim\@math\@below} & \optval{lim\@text\@below}
        & Extra depth reserved below the output.
    \\

    \macroRow{Below Form}
    \macroKey{zlim}{below-v}
        & \optval{lim\@math\@below\@v} & \optval{lim\@text\@below\@v}
        & Operator \emph{bottom} edge to script \emph{top} edge.
    \\
    \macroKey{zlim}{below-h}
        & \optval{lim\@math\@below\@h} & \optval{lim\@text\@below\@h}
        & Shift of the script from its centred position.
    \\

    \macroRow{Subscript Form}
    \macroKey{zlim}{script-v}
        & \optval{lim\@math\@script\@v} & \optval{lim\@text\@script\@v}
        & Operator \emph{bottom} edge to script \emph{top} edge.
    \\
    \macroKey{zlim}{script-h}
        & \optval{lim\@math\@script\@h} & \optval{lim\@text\@script\@h}
        & Operator \emph{right} edge to script \emph{left} edge.
    \\

\end{macroTable}

As in \cs{zscript}, the script is an explicitly positioned box rather than a product of \TeX's limits machinery, so it may overlap the operator. All positions use one Cartesian system ($x$ positive to the right, $y$ positive upward) and are measured from the \emph{edges of the operator} to the \emph{nearest edge} of the script: the vertical position is the $y$ coordinate of the script's top edge, so negative values lower it below the operator, while the horizontal position is the shift from the reference (centred for the below form, the operator's right edge for the subscript form). All values are \textit{dimensionless ratios}, with vertical options (\opt{v}, \opt{above}, \opt{below}) relative to the x-height and horizontal ones (\opt{h}, \opt{before}, \opt{after}) to the quad, both in the operator's math style. A negative \opt{zlim-}\macroMeta{mode}\opt{-after} pulls the following term closer to the operator, \eg{} a derivative.

The following example compares the two layouts, a one-sided limit, and scaled parts:
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.65\linewidth,
    halign lower=center,
  }
  \begin{gather*}
    \zlim{x}{0}                             % below
    \zfrac{\sin x}{x} = 1
    \nl
    \zlim+{x}{0}                            % subscript
    \zfrac{\sin x}{x} = 1
    \nl
    \zlim{x}{0^+}                           % one-sided limit
    \zfrac{x} = +\infty
    \nl[2]
    \zlim{A}{B} f\zarg{A}
    \ne
    \zlim*{A}*{B} f\zarg{A}                 % scaled
  \end{gather*}
\end{tcblisting}

The output box keeps neighbouring lines apart in text and inline math, and the plus keeps the operator compact there; the following example shows a derivative defined as a limit, tightened with a negative \opt{zlim-math-after}:
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.65\linewidth,
  }
  Previous line, no overlap.\\
  Below, inline: $\zlim{n}{\infty} a_n$.\\
  Subscript, inline: $\zlim+{n}{\infty} a_n$.\\
  Subsequent line, no overlap.
  \nl[2]
  {
    \setkeys{shorthand}{zlim-math-after=0.5}
    \[
      \zdiff*{x}f =
      \zlim{h}{0} \zfrac{f\zarg{x+h} - f\zarg{x}}{h}
    \]
  }
\end{tcblisting}

% ------------------------------------------------------------------------------
\clearpage
\subsection{\cs{zint} — configurable integral}
% ------------------------------------------------------------------------------

\macroDescription{\zint}
The \cs{zint} engine renders a configurable integral operator: like \cs{int} itself, it takes no body argument and is simply placed immediately before the integrand. The argument \macroMeta{type} selects the glyph cluster; \macroMeta{lower} and \macroMeta{upper} are its limits, each independently omittable to suppress that limit entirely. It is compatible with text, inline and display modes. Its options are listed in Table~\ref{tb:zint}.

\begin{syntax}
  \cs{zint}\macroStar\macroOpt{lower}\macroStar\macroOpt{upper}\macroStar\macroStar\macroOpt{type}
\end{syntax}

Starring and optional arguments:
\begin{itemize}[nosep]
  \item a \macroStar\ immediately before \macroMeta{lower} or \macroMeta{upper} scales that limit in its normal (script) size, but additionally scales it by \opt{zint-scale-}\macroMeta{style}, where \macroMeta{style} is the math style of the integral (see \opt{zint-scale-absolute});
  \item the (up to two) stars immediately before \macroMeta{type} select the \textit{placement class}, independently of math or text mode — \textbf{none} gives \opt{slant} (the default: limits lean diagonally off the glyph), \textbf{one} gives \opt{stack} (limits stacked below/above the glyph, as in \cs{sum}), \textbf{two} gives \opt{right} (limits stacked to the glyph's right side, the most compact option, well suited to inline use);
  \item \macroMeta{type} (default \texttt{1}) selects the glyph cluster:
    \begin{itemize}[nosep]
      \item \texttt{1} — a single $\int$;
      \item \texttt{2}, \texttt{3},~\ldots — $n$ tightly-kerned integrals, for surface, volume, \ldots\ integration;
      \item \texttt{o} — a closed-path $\oint$;
      \item anything else (\eg{} \texttt{n}) — a bridged $\int\!\cdots\!\int$, for a symbolic order.
    \end{itemize}
\end{itemize}

The most common variations of the command are identified in the following table:
\begin{macroTable*}[1.7]
    \cs{zint}\texttt{[a][b]}
        & \macroDisp{ \zint[a][b] }
        & \macroDisp*{ \zint[a][b] }
        & single, slant limits (default)
    \\

    \cs{zint}\texttt{[a][b]*}
        & \macroDisp{ \zint[a][b]* }
        & \macroDisp*{ \zint[a][b]* }
        & single, stacked limits
    \\

    \cs{zint}\texttt{[a][b]**}
        & \macroDisp{ \zint[a][b]** }
        & \macroDisp*{ \zint[a][b]** }
        & single, right-side limits
    \\

    \cs{zint}\texttt{[a][b][2]}
        & \macroDisp{ \zint[a][b][2] }
        & \macroDisp*{ \zint[a][b][2] }
        & double, slant limits
    \\

    \cs{zint}\texttt{[a][b]**[o]}
        & \macroDisp{ \zint[a][b]**[o] }
        & \macroDisp*{ \zint[a][b]**[o] }
        & closed path, right-side limits
    \\

    \cs{zint}\texttt{[a][b][n]}
        & \macroDisp{ \zint[a][b][n] }
        & \macroDisp*{ \zint[a][b][n] }
        & bridged cluster, slant limits
    \\
\end{macroTable*}

\textbf{Integration limits positions.} Both limits are always explicitly typeset as boxes one size below the integral's own (script size in display and text style), in every mode and for every type; either may be omitted, and they may freely overlap the glyph. The complete \cs{zint} output remains a single box whose height and depth encompass the glyph and both limits, preventing collisions with adjacent lines. Positions are measured from the glyph, so one setting works for limits of any size, using a single Cartesian convention ($x$ right, $y$ up) whose origin is the placement class's \textit{reference point}. For vertical measurements, the vertical centre of the glyph cluster (\ie approximately the math axis), with a vertical option specifying the $y$ of the limit's \emph{nearest edge} (bottom edge of the upper limit, top edge of the lower), hence positive \opt{top} and negative \opt{bottom} values. For horizontal measurements, the option specifies the $x$ of the limit's \emph{anchor}, which depends on the positioning class.

Three placement classes are defined (Figures~\ref{fig:zint-limits}~and~\ref{fig:zint-frame}):
\begin{itemize}[nosep]
  \item \textbf{slant} (no star before \macroMeta{type}): the reference point \emph{differs per limit}, so that a cluster's limits stay fixed relative to its outer silhouette no matter how many glyphs it has — the lower limit's \emph{right} edge is anchored relative to the cluster's \emph{left} edge, and the upper limit's \emph{left} edge is anchored relative to the cluster's \emph{right} edge;
  \item \textbf{stack} (one star before \macroMeta{type}): the reference is the horizontal centre of the whole cluster and the \emph{centre} of each limit is anchored, so a single value suits narrow and wide limits alike;
  \item \textbf{right} (two stars before \macroMeta{type}): the reference is the \emph{centre of the rightmost glyph} (the glyph centre for a single integral, so it does not depend on the number of integrals), and the \emph{left} edge of both limits is anchored, so wider limits grow away from the glyph.
\end{itemize}

\begin{figure}[ht]
  \centering
  \begin{subfigure}[b]{0.32\linewidth}
    \centering
    \begin{tikzpicture}[scale=0.5, >=Stealth]
      % output box, two-glyph cluster and limits
      \draw[zmframe] (-2.2,-1.7) rectangle (3.6,1.7);
      \draw[zmglyph] (-0.8,-1.5) rectangle (0.6,1.5);
      \draw[zmglyph] (0.8,-1.5) rectangle (2.2,1.5);
      \node at (-0.1,0) {$\displaystyle\int$};
      \node at (1.5,0)  {$\displaystyle\int$};
      \draw[zmlim] (2.6,1.0) rectangle (3.6,1.7) node[midway] {$b$};
      \draw[zmlim] (-2.2,-1.7) rectangle (-1.2,-1.0) node[midway] {$a$};
      % reference lines (cluster left/right edges, vertical centre)
      \draw[zmref] (-0.8,-2.6) -- (-0.8,2.5);
      \draw[zmref] (2.2,-2.6) -- (2.2,2.5);
      \draw[zmref] (-3.1,0) -- (4.3,0);
      % vertical options
      \draw[zmext] (3.6,1.0) -- (4.5,1.0);
      \draw[zmdim] (4.4,0) -- node[zmlbl, right] {top-v} (4.4,1.0);
      \draw[zmext] (-2.2,-1.0) -- (-2.9,-1.0);
      \draw[zmdim] (-2.8,0) -- node[zmlbl, left] {bottom-v} (-2.8,-1.0);
      % horizontal options (from cluster right edge / left edge)
      \draw[zmext] (2.6,1.7) -- (2.6,2.4);
      \draw[zmdim] (2.2,2.3) -- node[zmlbl, above] {top-h} (2.6,2.3);
      \draw[zmext] (-1.2,-1.7) -- (-1.2,-2.4);
      \draw[zmdim] (-0.8,-2.3) -- node[zmlbl, below] {bottom-h} (-1.2,-2.3);
    \end{tikzpicture}
    \caption{\opt{slant}}
  \end{subfigure}
  \hfill
  \begin{subfigure}[b]{0.32\linewidth}
    \centering
    \begin{tikzpicture}[scale=0.5, >=Stealth]
      % output box, two-glyph cluster and limits
      \draw[zmframe] (-1.0,-1.7) rectangle (2.2,1.7);
      \draw[zmglyph] (-0.8,-1.5) rectangle (0.6,1.5);
      \draw[zmglyph] (0.8,-1.5) rectangle (2.2,1.5);
      \node at (-0.1,0) {$\displaystyle\int$};
      \node at (1.5,0)  {$\displaystyle\int$};
      \draw[zmlim] (0.2,1.0) rectangle (1.4,1.7) node[midway] {$b$};
      \draw[zmlim] (-1.0,-1.7) rectangle (0.2,-1.0) node[midway] {$a$};
      % reference lines (cluster centre, vertical centre)
      \draw[zmref] (0.7,-2.6) -- (0.7,2.5);
      \draw[zmref] (-1.6,0) -- (2.9,0);
      % vertical options
      \draw[zmext] (2.2,1.0) -- (2.9,1.0);
      \draw[zmdim] (2.8,0) -- node[zmlbl, right] {top-v} (2.8,1.0);
      \draw[zmext] (0.2,-1.0) -- (2.9,-1.0);
      \draw[zmdim] (2.8,0) -- node[zmlbl, right] {bottom-v} (2.8,-1.0);
      % horizontal options (limit centres, from cluster centre)
      \draw[zmext] (0.8,1.7) -- (0.8,2.4);
      \draw[zmdim] (0.7,2.3) -- node[zmlbl, above] {top-h} (0.8,2.3);
      \draw[zmext] (-0.4,-1.7) -- (-0.4,-2.4);
      \draw[zmdim] (0.7,-2.3) -- node[zmlbl, below] {bottom-h} (-0.4,-2.3);
    \end{tikzpicture}
    \caption{\opt{stack}}
  \end{subfigure}
  \hfill
  \begin{subfigure}[b]{0.32\linewidth}
    \centering
    \begin{tikzpicture}[scale=0.5, >=Stealth]
      % output box, two-glyph cluster and limits
      \draw[zmframe] (-1.6,-1.7) rectangle (3.1,1.7);
      \draw[zmglyph] (-1.6,-1.5) rectangle (-0.2,1.5);
      \draw[zmglyph] (0.0,-1.5) rectangle (1.4,1.5);
      \node at (-0.9,0) {$\displaystyle\int$};
      \node at (0.7,0)  {$\displaystyle\int$};
      \draw[zmlim] (1.9,1.0) rectangle (3.1,1.7) node[midway] {$b$};
      \draw[zmlim] (1.7,-1.7) rectangle (2.9,-1.0) node[midway] {$a$};
      % reference lines (rightmost glyph centre, vertical centre)
      \draw[zmref] (0.7,-2.6) -- (0.7,2.5);
      \draw[zmref] (-1.9,0) -- (3.9,0);
      % vertical options
      \draw[zmext] (3.1,1.0) -- (3.9,1.0);
      \draw[zmdim] (3.8,0) -- node[zmlbl, right] {top-v} (3.8,1.0);
      \draw[zmext] (2.9,-1.0) -- (3.9,-1.0);
      \draw[zmdim] (3.8,0) -- node[zmlbl, right] {bottom-v} (3.8,-1.0);
      % horizontal options (limits' left edges, from rightmost glyph centre)
      \draw[zmext] (1.9,1.7) -- (1.9,2.4);
      \draw[zmdim] (0.7,2.3) -- node[zmlbl, above] {top-h} (1.9,2.3);
      \draw[zmext] (1.7,-1.7) -- (1.7,-2.4);
      \draw[zmdim] (0.7,-2.3) -- node[zmlbl, below] {bottom-h} (1.7,-2.3);
    \end{tikzpicture}
    \caption{\opt{right}}
  \end{subfigure}
  \caption{Schematic of the limit placement options for each class. A two-glyph cluster is shown throughout to make each class's reference line explicit. The vertical reference line is the cluster center for every class. The horizontal reference lines are: (\textbf{a}) the rightmost/leftmost edges of the cluster for \opt{slant}; (\textbf{b}) the center of the cluster for \opt{stack}; and (\textbf{c}) the center of the rightmost glyph for \opt{right}. The thick black frame represents the output box of \cs{zint}. The light shade backgrounds represent glyph boxes, while dark shade represents the limits boxes. Distances in red indicate main package options without the prefix \opt{zint-}\macroMeta{mode}\opt{-}\macroMeta{class}\opt{-} (\macroMeta{mode} is \opt{math} or \opt{text}); distances are exaggerated for legibility.}
  \label{fig:zint-limits}
\end{figure}

\begin{figure}[ht]
  \centering
  \begin{subfigure}[b]{0.48\linewidth}
    \centering
    \begin{tikzpicture}[scale=0.75, >=Stealth]
      % two-integral cluster
      \draw[zmglyph] (0,-1.2) rectangle (1.4,1.2);
      \draw[zmglyph] (1.9,-1.2) rectangle (3.3,1.2);
      \node at (0.7,0) {$\displaystyle\int$};
      \node at (2.6,0) {$\displaystyle\int$};
      \draw[zmext] (1.4,-1.2) -- (1.4,-1.9);
      \draw[zmext] (1.9,-1.2) -- (1.9,-1.9);
      \draw[zmdim] (1.4,-1.8) -- node[zmlbl, below] {separation} (1.9,-1.8);
      % bridged cluster
      \draw[zmglyph] (0,-5.7) rectangle (1.4,-3.3);
      \draw[zmglyph] (4.4,-5.7) rectangle (5.8,-3.3);
      \draw[zmlim] (2.3,-5.0) rectangle (3.5,-4.0) node[midway] {$\cdots$};
      \node at (0.7,-4.5) {$\displaystyle\int$};
      \node at (5.1,-4.5) {$\displaystyle\int$};
      \draw[zmext] (1.4,-5.7) -- (1.4,-6.4);
      \draw[zmext] (2.3,-5.0) -- (2.3,-6.4);
      \draw[zmdim] (1.4,-6.3) -- node[zmlbl, below] {dots-left} (2.3,-6.3);
      \draw[zmext] (3.5,-5.0) -- (3.5,-6.4);
      \draw[zmext] (4.4,-5.7) -- (4.4,-6.4);
      \draw[zmdim] (3.5,-6.3) -- node[zmlbl, below] {dots-right} (4.4,-6.3);
    \end{tikzpicture}
    \caption{Cluster kerns}
  \end{subfigure}
  \hfill
  \begin{subfigure}[b]{0.48\linewidth}
    \centering
    \begin{tikzpicture}[scale=1.1, >=Stealth]
      % glyph, one limit, union and output box (frame widened by `after`)
      \draw[zmunion] (0,-1.2) rectangle (1.6,1.6);
      \draw[zmglyph] (0,-1.2) rectangle (1.6,1.2);
      \node at (0.8,0) {$\displaystyle\int$};
      \draw[zmlim] (0.6,0.9) rectangle (1.2,1.6) node[midway] {$b$};
      \draw[zmframe] (0,-1.7) rectangle (1.0,2.1);
      % vertical clearances
      \draw[zmext] (-0.7,1.6) -- (0,1.6);
      \draw[zmext] (-0.7,2.1) -- (0,2.1);
      \draw[zmdim] (-0.6,1.6) -- node[zmlbl, left] {above} (-0.6,2.1);
      \draw[zmext] (-0.7,-1.2) -- (0,-1.2);
      \draw[zmext] (-0.7,-1.7) -- (0,-1.7);
      \draw[zmdim] (-0.6,-1.2) -- node[zmlbl, left] {below} (-0.6,-1.7);
      % after kern: union's right edge to the frame's right edge
      \draw[zmext] (1.0,-1.7) -- (1.0,-2.4);
      \draw[zmext] (1.6,-1.2) -- (1.6,-2.4);
      \draw[zmdim] (1.6,-2.3) -- node[zmlbl, below] {after<0} (1.0,-2.3);
    \end{tikzpicture}
    \caption{Output box}
  \end{subfigure}
  \caption{Schematic of the output of \cs{zint} valid for any class: (\textbf{a}) cluster kerns: \opt{separation} between consecutive glyphs, and \opt{dots-left} and \opt{dots-right} on the left and right of the interior \cs{cdots}; (\textbf{b})  thick frame represents the box that \cs{zint} hands to \TeX. The dashed rectangle is the union of glyph and limits, \opt{above} and \opt{below} extend it vertically and (a negative) \opt{after} shifts the frame's right edge (inward) from the union's own right edge. Distances in red indicate main package options without the prefix \opt{zint-}\macroMeta{mode}\opt{-}; distances are exaggerated for legibility.}
  \label{fig:zint-frame}
\end{figure}

Between consecutive glyphs and around the \cs{cdots} bridge, only the cluster kerns \opt{zint-}\macroMeta{mode}\opt{-separation}, \opt{-dots-left} and \opt{-dots-right} apply; \opt{zint-}\macroMeta{mode}\opt{-before} and \opt{-after} control the space before the integral and between it and the integrand, while \opt{-above} and \opt{-below} add or, when negative, remove clearance around the output box. All positions and frame values are dimensionless \emph{ratios} of the integral's math-style x-height (vertical) or quad (horizontal), so they scale automatically, including in exponents; only the \opt{separation}, \opt{dots-left} and \opt{dots-right} kerns remain lengths. The star scaling options \opt{zint-scale-}\macroMeta{style} are independent of mode, class and limit: \macroMeta{style} is \opt{display}, \opt{text}, \opt{script} or \opt{scriptscript}, identifying the integral's style, and the same four factors apply to both limits; \opt{zint-scale-absolute} determines whether they multiply the unstarred limit size (\opt{false}) or the normal size (\opt{true}), as with \opt{scale-absolute}.

\clearpage
\begin{macroTable}[Option & Math & Text & Description]{tb:zint}{Options for \cs{zint}. The \macroMeta{mode} is \opt{math} (display) or \opt{text} (text, script and scriptscript).}

    \macroRow{Starred Limits}
    \opt{zint-scale-absolute}
        & \macroSpan{\optval{int\@scale\@absolute}}
        & As \opt{scale-absolute}, for starred limits.
    \\
    \opt{zint-scale-display}
        & \macroSpan{\optval{int\@scale\@display}}
        & Factor by which a starred limit is scaled according to an unstarred one, for an integral in display style.
    \\
    \opt{zint-scale-text}
        & \macroSpan{\optval{int\@scale\@text}}
        & As \opt{zint-scale-display}, in text style.
    \\
    \opt{zint-scale-script}
        & \macroSpan{\optval{int\@scale\@script}}
        & As \opt{zint-scale-display}, in script style.
    \\
    \opt{zint-scale-scriptscript}
        & \macroSpan{\optval{int\@scale\@scriptscript}}
        & As \opt{zint-scale-display}, in scriptscript style.
    \\

    \macroRow{Cluster and Frame}
    \macroKey{zint}{separation}
        & \optval{int\@math\@separation} & \optval{int\@text\@separation}
        & Kern between consecutive \cs{intop} glyphs.
    \\
    \macroKey{zint}{dots-left}
        & \optval{int\@math\@dots\@left} & \optval{int\@text\@dots\@left}
        & Kern \emph{before} the interior \cs{cdots} bridge.
    \\
    \macroKey{zint}{dots-right}
        & \optval{int\@math\@dots\@right} & \optval{int\@text\@dots\@right}
        & Kern \emph{after} the interior \cs{cdots} bridge.
    \\
    \macroKey{zint}{before}
        & \optval{int\@math\@before} & \optval{int\@text\@before}
        & Extra width reserved before the whole output.
    \\
    \macroKey{zint}{after}
        & \optval{int\@math\@after} & \optval{int\@text\@after}
        & Extra width reserved after the whole output.
    \\
    \macroKey{zint}{above}
        & \optval{int\@math\@above} & \optval{int\@text\@above}
        & Extra height reserved above the output.
    \\
    \macroKey{zint}{below}
        & \optval{int\@math\@below} & \optval{int\@text\@below}
        & Extra depth reserved below the output.
    \\

    \macroRow{Slant Limits}
    \macroKey{zint}{slant-top-v}
        & \optval{int\@math\@slant\@top\@v} & \optval{int\@text\@slant\@top\@v}
        & Cluster centre to upper limit \emph{bottom} edge.
    \\
    \macroKey{zint}{slant-top-h}
        & \optval{int\@math\@slant\@top\@h} & \optval{int\@text\@slant\@top\@h}
        & Cluster \emph{right} edge to upper limit \emph{left} edge.
    \\
    \macroKey{zint}{slant-bottom-v}
        & \optval{int\@math\@slant\@bottom\@v} & \optval{int\@text\@slant\@bottom\@v}
        & Cluster centre to the \emph{top} edge of the lower limit.
    \\
    \macroKey{zint}{slant-bottom-h}
        & \optval{int\@math\@slant\@bottom\@h} & \optval{int\@text\@slant\@bottom\@h}
        & Cluster \emph{left} edge to lower limit \emph{right} edge.
    \\

    \macroRow{Right Limits}
    \macroKey{zint}{right-top-v}
        & \optval{int\@math\@right\@top\@v} & \optval{int\@text\@right\@top\@v}
        & Glyph centre to upper limit \emph{bottom} edge.
    \\
    \macroKey{zint}{right-top-h}
        & \optval{int\@math\@right\@top\@h} & \optval{int\@text\@right\@top\@h}
        & Centre of rightmost glyph to upper limit \emph{left} edge.
    \\
    \macroKey{zint}{right-bottom-v}
        & \optval{int\@math\@right\@bottom\@v} & \optval{int\@text\@right\@bottom\@v}
        & Glyph centre to lower limit \emph{top} edge.
    \\
    \macroKey{zint}{right-bottom-h}
        & \optval{int\@math\@right\@bottom\@h} & \optval{int\@text\@right\@bottom\@h}
        & Centre of rightmost glyph to lower limit \emph{left} edge.
    \\

    \macroRow{Stacked Limits}
    \macroKey{zint}{stack-top-v}
        & \optval{int\@math\@stack\@top\@v} & \optval{int\@text\@stack\@top\@v}
        & Glyph centre to upper limit \emph{bottom} edge.
    \\
    \macroKey{zint}{stack-top-h}
        & \optval{int\@math\@stack\@top\@h} & \optval{int\@text\@stack\@top\@h}
        & Cluster centre to upper limit \emph{centre}.
    \\
    \macroKey{zint}{stack-bottom-v}
        & \optval{int\@math\@stack\@bottom\@v} & \optval{int\@text\@stack\@bottom\@v}
        & Glyph centre to lower limit \emph{top} edge.
    \\
    \macroKey{zint}{stack-bottom-h}
        & \optval{int\@math\@stack\@bottom\@h} & \optval{int\@text\@stack\@bottom\@h}
        & Cluster centre to lower limit \emph{centre}.
    \\

\end{macroTable}

The following examples compare default and scaled limits, cluster and closed-path integrals with a single lower limit, and show a vectorial integral:
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
    halign lower=center,
  }
  \begin{gather*}
    \zint[a][b] f \zarg{x} \zdiff+{x}     % default
    \ne
    \zint*[a]*[b] f \zarg{x} \zdiff+{x}   % scaled
    \nl[1.5]
    \zint[A][B] f \zarg{x} \zdiff+{x}     % default
    \ne
    \zint*[A]*[B] f \zarg{x} \zdiff+{x}   % scaled
    \nl[1.5]
    \zint[\mathcal{S}][][2] f \zdiff+{A}  % cluster
    \ne
    \zint[\partial\mathcal{V}][][o]       % closed path
    \zvec{u} \zdot \zdiff{\zvec{A}}
    \nl[1.5]
    \zint[-\infty][\infty][n]             % n-dimensional
    f\zarg{\zvec{x}} \zdiff+{\zvec{x}}
  \end{gather*}
\end{tcblisting}

With a single star before \macroMeta{type}, the \opt{stack} class is applied. Since the limits are anchored by their own centre, narrow and wide limits such as $\mathcal{S}$ and $\partial\mathcal{V}$ share the same defaults, and a correction is only needed for exceptional cases. The following example shows stacked limits, a stacked cluster, and a comparison between the default stacked closed-path integral and a nudged version:
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.75\linewidth,
    halign lower=center,
  }
  \begin{gather*}
    \zint[a][b]*
    f\zarg{x} \zdiff{x}                               % stacked limits
    \nl
    %
    \zint[\mathcal{S}][]*[2]
    f \zdiff{A}                                       % stacked cluster
    \nl[1.5]
    %
    \zint[\lim\limits_{V\to 0}\partial{V}][]*[o]
    \zvec{u} \zdot \zdiff{\zvec{A}}                   % stacked path
    \nl
    {
    \setkeys{shorthand}{zint-math-stack-bottom-h=-1}
    \zint[\lim\limits_{V\to 0}\partial{V}][]*[o]
    \zvec{u} \zdot \zdiff{\zvec{A}}                   % shifted limit
    }
  \end{gather*}
\end{tcblisting}

The default vertical distances suit typical limit heights; a visually taller limit — a fraction, a stacked symbol, a large integrand — may need extra clearance. The following example shows a compact expression and the same one with the upper limit raised and the integrand pulled closer:
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
    halign lower=center,
  }
  \begin{gather*}
    % more compact expression
    \zint[0][{+\infty}] \sum_x \zfrac{x} \zdiff+{x}
    \nl
    {
    \setkeys{shorthand}{zint-math-after=-0.7}
    \setkeys{shorthand}{zint-math-slant-top-v=2.5}
    \zint[0][{+\infty}] \sum_x \zfrac{x} \zdiff+{x}
    }
  \end{gather*}
\end{tcblisting}

With two stars before \macroMeta{type}, the \opt{right} class is applied for a more compact look. The output box includes the limits, so they clear adjacent text lines instead of colliding with them; decreasing a vertical distance — even below zero — pulls the limit toward the glyph, increasing it pushes the limit further away, without ever affecting the line spacing protection. The following examples show inline right-side limits, inline stacked limits between two regular lines, the same stacked limits with a larger vertical distance, and a comparison between inline clusters using the default and an increased spacing:

\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
  }
  Inline right-side limits:
  $\zint[a][b]** f\zarg{x} \zdiff{x}$.
  \nl[2]
  Previous line does not overlap.\\
  Inline stacked limits:
  $\zint[a][b]* f\zarg{x} \zdiff{x}$.\\
  Subsequent line does not overlap.
  \nl[4]
  {
    \setkeys{shorthand}{zint-text-stack-top-v=2.2}
    \setkeys{shorthand}{zint-text-stack-bottom-v=-2.2}
    Previous line does not overlap.\\
    Increased spacing:
    $\zint[a][b]* f\zarg{x} \zdiff{x}$. \\
    Subsequent line does not overlap.
  }
  \nl[2]
  Inline cluster: $\zint[][][2] f \zdiff{A}$.
  \nl[3]
  {
    \setkeys{shorthand}{zint-text-separation=-5mu}
    Increased spacing: $\zint[][][2] f \zdiff{A}$.
  }
\end{tcblisting}

% ==============================================================================
\clearpage
\section{Combined Examples}
% ==============================================================================

\subsection{Fundamental theorem of calculus}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
    halign lower=center,
  }
  \begin{gather*}
    \zint[a][b] f(x) \, \zdiff{x} =
    F(x)\zcond**{x=b} - F(x)\zcond**{x=a}
  \end{gather*}
\end{tcblisting}

\subsection{Tensor with four-way scripts and evaluation bar}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
  }
  Ricci tensor components, evaluated at the origin:
  \[
    \zscript[\mu][\nu]{Ri}[\alpha][\beta]
    \zcond**[\,]{x=0}
    = \zfrac[\zscript{Ri}[\mu\nu]]{\kappa}
  \]
\end{tcblisting}

\subsection{Divergence theorem}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
  }
  \[
    \zint[\partial\mathcal{V}][][2]
    \zvec{u} \zdot \hat{n} \zdiff+{A}
    =
    \zint[\mathcal{V}][][3]
    \nabla \zdot \zvec{u} \zdiff+{V}
  \]
  The flux of a vector field through a closed surface equals the divergence integrated over the enclosed volume.
\end{tcblisting}

\subsection{Multi-dimensional integration}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
  }
  Integration in multiple dimensions:
  \begin{gather*}
    \zint[a][b] f(x) \zdiff+{x}
    \\
    \zint[\mathcal{S}][][2] f \zdiff+{A}
    \\
    \zint[V][][3] \rho \zdiff+{V}
    \\
    \zint[\mathbb{R}^n][][n] g \zdiff+[n]{x}
  \end{gather*}
\end{tcblisting}

\subsection{Gaussian integral}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
    halign lower=center,
  }
  \[
    \zint[-\infty][{+\infty}]
    e^{-x^2} \, \zdiff{x} = \sqrt{\pi}
  \]
\end{tcblisting}

\subsection{Circulation of a vector field}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
  }
  \[
    \zint[\partial\mathcal{S}][][o]
    \vec{F} \zdot \zdiff{\vec{r}}
    =
    \zint[\mathcal{S}][][2]
    \left( \vec{\nabla} \times \vec{F} \right)
    \zdot \zdiff{\vec{A}}
  \]
  Stokes' theorem relates the circulation around a closed curve to the flux of the curl through any bounded surface.
\end{tcblisting}

\subsection{Arc length of a parametrised curve}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
  }
  If \zprime{\zvec{r}}\zarg{s} is the tangent
  vector with respect to arc length $s$ of curve
  vector position \zvec{r}, then:
  \begin{gather*}
    \zprime{\zvec{r}} = \zdiff*{s}\zvec{r}
    \quad \implies
    \nl
    L = \zint[0][\ell]
    \left\| \zprime{\zvec{r}}\zarg{s} \right\|
    \zdiff+{s} \zpunct{.}
  \end{gather*}
\end{tcblisting}

\subsection{Moment of inertia of spherical shell}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.6\linewidth,
  }
  The moment of inertia of a thin spherical shell is:
  \[
    I = \zint[0][\pi][2]
    \zfrac{2}{3} m r^2 \sin^3\zarg{\theta}
    \zdiff+{\theta} \zpunct{.}
  \]
\end{tcblisting}

\subsection{Heat equation solution}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.45\linewidth,
    %halign lower=center,
  }
  Equation \ref{eq:green} applies the Green
  function for the heat equation:
  \begin{equation}
    \label{eq:green}
    u\zarg{x,t} =
    \zfrac{\sqrt{4\pi\kappa t}}
    \zint[-\infty][{+\infty}]
    u_0\zarg{\zprime{x}}
    \cdot e^{
        -\zfrac
        {\left( x-\zprime{x} \right)^2}
        {4\kappa t}
    }
    \zdiff+{\zprime{x}}
    \zpunct{.}
  \end{equation}
\end{tcblisting}

\subsection{Beer--Lambert law}
\begin{tcblisting}{
    math-shorthandz-tex,
    lefthand width=0.62\linewidth,
  }
  Light crossing a medium of non-uniform density obeys the
  generalised Beer--Lambert law:
  \begin{gather*}
    I\zarg{L}
    = I_0 \, e^{-\zint[0][{L}]{\kappa\zarg{x}} \zdiff+{x}}
    \zpunct{.}
  \end{gather*}
\end{tcblisting}

% ==============================================================================
\section{Change History}
% ==============================================================================

\begin{description}[style=nextline, leftmargin=2cm, labelwidth=!]

  \item[v1.0.0 (2026/10/14)] Package renamed to \pkg{math-shorthandz}. First public release.
    \begin{itemize}[nosep]

      \item \textbf{Package name.} Renamed from \pkg{zmath} to \pkg{math-shorthandz} (files, \cs{usepackage} and repository). The final "z" keeps the name consistent with the \cs{z...} command prefix. Commands and option keys are unchanged.

      \item \textbf{Key family.} The keyval family was renamed from \opt{zmath} to \opt{shorthand}: replace \cs{setkeys}\texttt{\{zmath\}\{...\}} by \cs{setkeys}\texttt{\{shorthand\}\{...\}}; no alias is kept. Options given to \cs{usepackage} are unaffected.

      \item \textbf{Release numbering.} The package was intended to be released as v1.0.0 under the name \pkg{zmath}. Since CTAN and \TeX\ Live required a less generic name, the first public tag was moved to this release, and the former \pkg{zmath} releases are recorded as v0.12.0 and v0.13.0.

    \end{itemize}

  \item[v0.13.0 (2026/10/12)] Per-call control of the placement of scripts. Option rename.
    \begin{itemize}[nosep]

      \item \cs{zscript}: the switch \opt{zscript-adaptative} (which was missing from v0.12.0) selects between the placement from the edges of the nucleus and \TeX's own placement, and a leading \macroPlus\ flips it for a single call, whatever its value.

      \item \cs{zscript}: the option \opt{zscript-font} was renamed \opt{zscript-wrapper}, since it selects a macro applied to every script rather than a font. Replace \opt{font} by \opt{wrapper} in the key; its meaning and values are unchanged, and no alias is kept.

    \end{itemize}

  \item[v0.12.0 (2026/10/09)] Every command was rewritten on a common footing and shared naming convention (\cs{z...}). New commands added. Last major rewrite under the name \pkg{zmath}, originally intended as v1.0.0.
    \begin{itemize}[nosep]

      \item \textbf{All commands.} Every tunable constant is now a key--value option, read at call time and settable globally or locally with \cs{setkeys}, replacing fixed constants and hard-coded kerns. All commands are safe in text, inline and display mode, and adapt to the math style of the call.
      
      \item \textbf{Scaling.} Scaling follows the math style of the call through one shared mechanism with four factors per command (display, text, script, scriptscript), an absolute or relative reading of these factors, and a guard that stops nested scaled content from shrinking below scriptscript size.
      
      \item \textbf{Positions.} Distances are dimensionless ratios of the x-height and quad of the style, so one setting stays valid in exponents. Commands that place parts explicitly return a single box whose height and depth cover all of them, so neighbouring lines no longer collide.
      
      \item \cs{zpunct} (supersedes \cs{eqpunct}): works both in unstarred and starred environments through \cs{tag*}, and discards the punctuation on \cs{notag}/\cs{nonumber} rows so it cannot leak into a later number or \cs{eqref}.
      
      \item \cs{zfrac}: the layout is now always wrapped in \cs{ensuremath}, so operands may contain math even when called from text, and parentheses are always \cs{left}\,\cs{right} delimiters; the text-mode \cs{mbox} workaround is gone.
      
      \item \cs{zscale}: the single fixed factor became four per-style factors, with the absolute/relative switch and the nesting guard above.
      
      \item \cs{zdiff} (supersedes \cs{diff}): the differential is a \cs{mathinner} atom, so \TeX\ supplies the spacing instead of a fixed \texttt{10mu} kern, which also removes double spacing after operators such as \cs{zdot}; a leading \macroPlus\ adds extra separation, chosen by math style, and the derivative kern is an option.
      
      \item \cs{zscript}: the four scripts are explicitly placed boxes with per-style, per-mode ratio options instead of \TeX's script machinery, so they may overlap the nucleus; a star scales a script by the style factors; and every script is wrapped in the new \opt{zscript-font} option, by default \cs{symup}.
      
      \item \cs{zprime} (supersedes \cs{primed}): primes scale with the math style of the symbol, so they are safe in exponents; the accent form is placed explicitly rather than through \cs{accentset}, with the cluster centred as a group; the vertical and horizontal positions are options, replaceable per call, instead of a single manual \cs{raisebox} offset; and the output box covers symbol and primes, so \cs{left}/\cs{right} and later scripts see the true height, replacing the \cs{vphantom} and \cs{smash} workarounds.
      
      \item \cs{zint}: the display and inline constants were merged into options for two modes and three placement classes (\opt{slant}, \opt{stack}, \opt{right}), selected by zero, one or two stars before the type; limits are always explicit boxes with independent anchors, so one geometry serves all types; and the frame (\opt{before}, \opt{after}, \opt{above}, \opt{below}) and the cluster kerns are options.
      
      \item New commands: \cs{zline} (with \cs{zvec} and \cs{zmat}), \cs{zdot}, \cs{zarg}, \cs{zcond} and \cs{zlim}.
      
    \end{itemize}

  \item[v0.11.0 (2025)] Flexible fraction incorporated into the package.
    \begin{itemize}[nosep]

      \item \cs{zfrac}: stars select \cs{frac}, \cs{nicefrac} or slash form; braces or brackets select plain or parenthesised operands; a single argument is the denominator. Math or text mode is detected at the call site.
    
    \end{itemize}

  \item[v0.10.0 (2022-2025)] Single macro for integrals with slant/stack limits.
    \begin{itemize}[nosep]

      \item \cs{zint}: single, multiple, closed-path and bridged integrals, with "side" or "stack" limits (one star before the type) chosen separately for display and inline style, using named spacing constants.
    
    \end{itemize}

  \item[v0.9.0 (2023-2025)] First consolidated package for personal use.
    \begin{itemize}[nosep]

      \item Shared scale coefficient.
      
      \item \cs{zscale}: uniform scaling of math content.
      
      \item \cs{zscript} (supersedes \cs{varsubsup}): pre- and post-scripts, with optional scaling per script by starring (rather than suppressed scaling, as in \cs{varsubsup})
    
    \end{itemize}

  \item[v0.8.0 (2024-2025)] Single macro for sub/superscripts.
    \begin{itemize}[nosep]
      
      \item \cs{varsubsup}: shorthand for trailing scripts, scaled by default.
    
    \end{itemize}

  \item[v0.7.0 (2021-2024)] Single macro for prime marks as accent or superscripts.
    \begin{itemize}[nosep]
      
      \item \cs{primed}: prime accent via \cs{accentset}, or \cs{superscript}; optional number of primes and manual height offset.
    
    \end{itemize}

  \item[v0.6.0 (2020-2023)] Single macro for differentials and derivatives.
    \begin{itemize}[nosep]
      
      \item \cs{diff}: differential or derivative, with one star (\cs{frac}) or two (\cs{nicefrac}), with an optional order and fixed kerns around the output.
    
    \end{itemize}

  \item[v0.5.0 (2020-2022)] Equation punctuation for numbered equations. Shortcut for function arguments.
    \begin{itemize}[nosep]
      
      \item \cs{eqpunct}: adds punctuation mark to numbered equations through a redefined \cs{tagform@} hook.
      
      \item \cs{arg}: automatic \cs{left(}/\cs{right)} wrapping of arguments for functions.
    
    \end{itemize}

  \item[v0.0.0-v0.4.0] \ldots

\end{description}

\clearpage
\PrintIndex

\end{document}