% Copyright (C) 2026 Quan Sun
% Released under the LaTeX Project Public License, version 1.3c or later.
\documentclass[a4paper,11pt]{article}

\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage[margin=28mm]{geometry}
\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref}
\hypersetup{
  pdftitle={The mathformule Package},
  pdfauthor={Quan Sun},
  pdfsubject={Documentation for a lightweight multiline formula environment},
  pdfkeywords={LaTeX, mathematics, equations, alignment, numbering}}

\newcommand*\pkg{\textsf{mathformule}}
\newcommand*\env{\texttt{formule}}

\title{The \pkg\ Package\\[4pt]
  \large A Lightweight Environment for Single- and Multiline Mathematics}
\author{Quan Sun\\
  \href{mailto:rmm74845@gmail.com}{\texttt{rmm74845@gmail.com}}}
\date{22 July 2026\\Version 0.6}

\begin{document}
\maketitle

\begin{abstract}
The \pkg\ package provides the numbered \env\ display environment for both
single-line and aligned multiline mathematics.  A multiline display may have
one overall equation number or a separate configurable subnumber on each
row.  An extensible brace may surround all rows on either side, and both row
separation and brace spacing can be adjusted.  The package does not explicitly
require or load an auxiliary package; its typesetting core is implemented with
\TeX{} primitives and \LaTeX{} kernel facilities.  It shares \LaTeX's standard
equation counter and works with the usual numbering and cross-reference
mechanisms.  Version 0.6 has been verified with pdf\LaTeX, Xe\LaTeX, and
Lua\LaTeX.
\end{abstract}

\tableofcontents

\section{Overview}

\paragraph{Engines.}
This is a package for current \LaTeXe{} formats.  Version 0.6 has been verified
with pdf\LaTeX, Xe\LaTeX, and Lua\LaTeX.  It is not a plain \TeX{} macro file, and
other engines or formats are outside the currently verified scope.

The same \env\ environment is intended for a short single formula and for a
system of multiline formulas.  Rows without an ampersand share a left edge;
an ampersand requests explicit column alignment, and a double backslash ends a
row.  By default all rows share one equation number.  Optional keys provide
left or right braces, signed spacing corrections, and per-row subnumbers.

The package does not explicitly load \textsf{amsmath} or another auxiliary
package, and it does not wrap \texttt{equation}, \texttt{align}, or
\texttt{aligned}.  It can nevertheless be used in documents that load the AMS
mathematics packages and common reference packages such as \textsf{hyperref}
and \textsf{cleveref}.  It follows the document-wide \texttt{leqno} and
\texttt{fleqn} conventions when they are active.

\section{Installation and loading}

For a local installation, place \texttt{mathformule.sty} in the document
directory and write:

\begin{verbatim}
\usepackage{mathformule}
\end{verbatim}

For equation numbers tied to a document division, use one of the package
options below.  The \texttt{chapter} option requires a class that defines a
\texttt{chapter} counter.

\begin{verbatim}
\usepackage[section]{mathformule}
% or
\usepackage[chapter]{mathformule}
\end{verbatim}

The more general preamble command accepts any existing \LaTeX{} counter:

\begin{verbatim}
\mathformulenumberwithin{subsection}
\end{verbatim}

This setting deliberately changes the shared \texttt{equation} counter, so
native equations and \env\ displays retain a single numbering scheme.

\section{Basic displays}

\subsection{A single formula}

The simplest use is equivalent in purpose to a numbered display equation:

\begin{verbatim}
\begin{formule}\label{eq:energy}
  E=mc^2
\end{formule}
\end{verbatim}

The contents are already in display math mode; dollar signs must not be added.

\subsection{Multiline rows and alignment}

If the environment contains no top-level \verb|&|, all rows occupy one
left-aligned formula column.  Formulas of different widths therefore share
their left edge:

\begin{verbatim}
\begin{formule}
  f(x)=a+b \\
  abc=cd
\end{formule}
\end{verbatim}

Once a top-level \verb|&| is present, columns before an alignment point are
right aligned and columns after it are left aligned.  Use \verb|\\| for a row
break:

\begin{verbatim}
\begin{formule}\label{eq:identities}
  (a+b)^2 &= a^2+2ab+b^2 \\
  (a-b)^2 &= a^2-2ab+b^2 \\
  (a+b)(a-b) &= a^2-b^2
\end{formule}
\end{verbatim}

All three rows receive one overall number.  A final \verb|\\| is optional;
if supplied, it is ignored and creates neither an empty row nor an additional
number.  A leading ampersand is valid: it leaves the first column empty and
places the formula in the left-aligned second column.  For example:

\begin{verbatim}
\begin{formule}[multnum={arabic-roman},lbrace,lineskip=0pt]
  &f(x)=a+b \\
  &abc=cd
\end{formule}
\end{verbatim}

Several alignment pairs may be placed on one row:

\begin{verbatim}
\begin{formule}
  a_1 &= b_1 & c_1 &= d_1 \\
  a_2 &= b_2 & c_2 &= d_2
\end{formule}
\end{verbatim}

Only top-level ampersands select this alignment behaviour.  Ampersands inside
a braced argument or a nested environment such as \texttt{array} do not alter
the outer \env\ alignment.  For predictable columns, use explicit ampersands
consistently throughout one environment.

\section{Row separation}

The default multiline setting opens the normal formula-row baseline distance
by \texttt{3pt}.  All spacing values described here are signed corrections to
that default, not absolute baseline distances.

\subsection{Document-wide correction}

Use \verb|\formuleskip| in the preamble to modify all multiline \env\
environments.  Positive values loosen the rows and negative values tighten
them.

\begin{verbatim}
\formuleskip{1pt}   % add 1pt to the default in every formule
% \formuleskip{-1pt} would subtract 1pt
\end{verbatim}

The command expects a \TeX{} dimension.  It has no visible effect on a
single-line display because such a display has no inter-row separation.

\subsection{Correction for one environment}

The \texttt{lineskip} key replaces the global \verb|\formuleskip| correction
for that environment:

\begin{verbatim}
\formuleskip{1pt}

\begin{formule}[lineskip=-2pt]
  a &= b \\
  c &= d
\end{formule}
\end{verbatim}

Here the local correction is \texttt{-2pt}; it is not added to the global
\texttt{1pt} correction.

The prototype shorthand \verb|[dimen]| remains accepted and has the same
meaning and precedence as \verb|[lineskip=dimen]|.  The explicit key form is
recommended for new documents.

\subsection{Correction after one row}

An optional dimension after a row break applies an additional local vertical
adjustment after that row only:

\begin{verbatim}
\begin{formule}
  a &= b \\[2pt]
  c &= d \\[-1pt]
  e &= f
\end{formule}
\end{verbatim}

The vertical space outside the complete display is not controlled by these
interfaces.  It remains the class-defined rubber display space based on:

\begin{verbatim}
\abovedisplayskip        \abovedisplayshortskip
\belowdisplayskip        \belowdisplayshortskip
\end{verbatim}

\section{Braces around a multiline display}

\subsection{Left and right braces}

The bare \texttt{lbrace} and \texttt{rbrace} keys place an extensible brace
around the complete group of rows:

\begin{verbatim}
\begin{formule}[lbrace]
  x+y &= 3 \\
  x-y &= 1
\end{formule}

\begin{formule}[rbrace]
  p &= q \\
  r &= s
\end{formule}
\end{verbatim}

The brace is produced by \TeX's standard extensible math-delimiter mechanism,
the same mechanism used by \verb|\left\{| and \verb|\right\}|.  The two brace
keys are mutually exclusive.

\subsection{Material outside the brace}

A key value is placed in display math mode before a left brace or after a
right brace:

\begin{verbatim}
\begin{formule}[lbrace={f(x)=}]
   x^2, & x\geq 0 \\
  -x,   & x<0
\end{formule}

\begin{formule}[rbrace={=G(t)}]
  p(t) &= t^2+1 \\
  q(t) &= 2t-3
\end{formule}
\end{verbatim}

No relation symbol or spacing is inserted automatically.  Braces around the
value are recommended when it contains a comma or an equals sign.

\subsection{Brace-spacing corrections}

\texttt{lbraceskip} and \texttt{rbraceskip} apply signed horizontal
corrections between the selected brace and the aligned rows:

\begin{verbatim}
\begin{formule}[lbrace={F(x)=},lbraceskip=2pt]
  a &= b \\
  c &= d
\end{formule}

\begin{formule}[rbrace={=S},rbraceskip=-1pt]
  u+v &= 7 \\
  2u-v &= 5
\end{formule}
\end{verbatim}

A brace-spacing key has no output effect unless its matching brace is active.

\section{Equation numbers and references}

\subsection{The standard equation sequence}

Every \env\ display advances \LaTeX's standard \texttt{equation} counter once.
Consequently native \texttt{equation} displays and \env\ displays interleave
without a separate sequence.  Existing definitions of \verb|\theequation|
are retained unless the user requests division-based numbering through this
package.

For an overall number, place \verb|\label| in the environment and use the
ordinary reference commands:

\begin{verbatim}
\begin{formule}\label{eq:sum}
  \sum_{k=1}^{n} k = \frac{n(n+1)}{2}
\end{formule}

See equation~\ref{eq:sum}.
\end{verbatim}

When their packages are loaded, \verb|\eqref|, \verb|\autoref|, and
\verb|\cref| use the same stored number and hyperlink target.

With the document-wide \texttt{leqno} setting, overall and per-row tags follow
the class's left-numbering convention.  With \texttt{fleqn}, the formulas use
the class's display-math indentation.

\subsection{One subnumber per row}

For a genuinely multiline display, the bare \texttt{multnum} key changes one
overall tag into a tag on each numbered row:

\begin{verbatim}
\begin{formule}[multnum]
  x+y &= 8 \label{eq:system-a} \\
  x-y &= 2 \label{eq:system-b} \\
\end{formule}
\end{verbatim}

If the main equation number is \texttt{3}, these rows are numbered
\texttt{3.1} and \texttt{3.2}.  The complete group consumes only main number
\texttt{3}; the next standard equation is \texttt{4}.  A \verb|\label| for a
row should be placed on that numbered row.

The four explicit styles are:

\begin{center}
\begin{tabular}{lll}
\hline
Key value & First two tags & Second component \\
\hline
\texttt{arabic.arabic} & \texttt{3.1}, \texttt{3.2} & Arabic \\
\texttt{arabic-arabic} & \texttt{3-1}, \texttt{3-2} & Arabic \\
\texttt{arabic.roman}  & \texttt{3.i}, \texttt{3.ii} & lower-case Roman \\
\texttt{arabic-roman}  & \texttt{3-i}, \texttt{3-ii} & lower-case Roman \\
\hline
\end{tabular}
\end{center}

The aliases \texttt{arabic} and \texttt{roman} are accepted for
\texttt{arabic.arabic} and \texttt{arabic.roman}, respectively.

For example:

\begin{verbatim}
\begin{formule}[multnum={arabic-roman}]
  a &= b \label{eq:roman-a} \\
  c &= d \label{eq:roman-b}
\end{formule}
\end{verbatim}

The first component is always the complete current main equation number.  If
equations are numbered by section, main number \texttt{2.3} therefore gives
row numbers \texttt{2.3-i} and \texttt{2.3-ii}.  A single-row display ignores
\texttt{multnum} and uses the ordinary overall equation number.

\subsection{Suppressing individual row numbers}

In \texttt{multnum} mode, \verb|\notag| and \verb|\nonumber| suppress the tag
on one row.  A suppressed row does not consume a subnumber.

\begin{verbatim}
\begin{formule}[multnum={arabic.roman}]
  a_1 &= b_1 \label{eq:first} \\
  a_2 &= b_2 \notag \\
  a_3 &= b_3 \nonumber \\
  a_4 &= b_4 \label{eq:second}
\end{formule}
\end{verbatim}

Do not attach a label to a suppressed row, because that row intentionally has
no independent reference target.

\section{Combined example}

The following example combines a left brace, material before the brace,
global and local row spacing, Roman row subnumbers, a brace-spacing correction,
row-number suppression, references, and a harmless final row break.

\begin{verbatim}
\usepackage[section]{mathformule}
\formuleskip{1pt}

\begin{formule}[
  lbrace={F(x)=},
  lbraceskip=1pt,
  lineskip=-1pt,
  multnum={arabic-roman}]
   x^2, & x>0 \label{eq:case-positive} \\
   0,   & x=0 \notag \\
  -x,   & x<0 \label{eq:case-negative} \\
\end{formule}

See \ref{eq:case-positive} and \ref{eq:case-negative}.
\end{verbatim}

In \texttt{multnum} mode, at most four alignment pairs (eight formula
columns) are supported on each row.

\section{Option summary}

\begin{center}
\begin{tabular}{p{0.30\linewidth}p{0.61\linewidth}}
\hline
Interface & Meaning \\
\hline
\verb|\formuleskip{dimen}| & Global signed correction to multiline row
separation. \\
\verb|lineskip=dimen| & Local signed correction; replaces
\verb|\formuleskip| for one environment. \\
\verb|[dimen]| & Prototype shorthand for \verb|[lineskip=dimen]|. \\
\verb|\\[dimen]| & Additional correction after one row. \\
\verb|lbrace|, \verb|rbrace| & Extensible brace around all rows. \\
\verb|lbrace={math}| & Math material before a left brace. \\
\verb|rbrace={math}| & Math material after a right brace. \\
\verb|lbraceskip=dimen| & Signed left-brace spacing correction. \\
\verb|rbraceskip=dimen| & Signed right-brace spacing correction. \\
\verb|multnum| & Arabic row subnumbers separated by a dot. \\
\verb|multnum={style}| & Explicit row-number style. \\
\verb|\notag|, \verb|\nonumber| & Suppress one row tag in multiline
\texttt{multnum} mode. \\
\hline
\end{tabular}
\end{center}

\section{Compatibility and limitations}

The package does not explicitly require or load a supporting package; its
typesetting core uses \TeX{} primitives and \LaTeX{} kernel facilities.  It has
been tested with pdf\LaTeX, Xe\LaTeX, and Lua\LaTeX, as well as with commonly
used AMS mathematics packages and cross-reference packages.  These supporting
packages are optional.  No conflict is currently known from the tested combinations,
but behaviour in an arbitrary document can still depend on the document
class, package versions, and loading order.

An \env\ environment must be used in text mode and cannot be nested inside
another mathematics environment.  The keys \texttt{lbrace} and
\texttt{rbrace} cannot be combined.  In \texttt{multnum} mode the current
limit is four alignment pairs per row.  The package refuses to overwrite a
pre-existing environment named \env\ and reports a package error instead.

\section{Development, acknowledgements, and license}

The design was informed by established \LaTeX{} display-math conventions and by
the user interfaces of environments such as \texttt{equation},
\texttt{align}, and \texttt{aligned}.  The implementation is independently
structured around \TeX{} primitives and \LaTeX{} kernel facilities.  It uses
established public \TeX{} programming idioms for safe alignment and delimiter
handling; it neither wraps nor reproduces an existing display environment as
its implementation.  Thanks are due to the \TeX{} and \LaTeX{} communities
whose documented conventions made compatible behaviour possible.

Copyright \copyright\ 2026 Quan Sun.  This work is distributed under the
\LaTeX{} Project Public License, version 1.3c or later.  It is provided without
warranty, to the extent permitted by applicable law.  Its LPPL maintenance
status is \emph{maintained}; the Current Maintainer is Quan Sun.  Bug reports
may be sent to
\href{mailto:rmm74845@gmail.com}{\texttt{rmm74845@gmail.com}}.

\end{document}