% hangulmath-doc.tex -- documentation for the hangulmath package
% Copyright (C) 2026 Inkyu Park <icpark00@gmail.com>
% LaTeX Project Public License 1.3c or later.
%
% Compile with:  xelatex hangulmath-doc  (twice)
% The Korean prose uses the first Korean font found (see below).
\documentclass[11pt,a4paper]{article}
\usepackage[margin=28mm]{geometry}
\usepackage{amsmath,amssymb}
\usepackage{hangulmath}
% 수식 기호(자모) 글꼴을 바꾸려면 위 줄 대신 아래 중 하나를 쓰십시오.
% To change the symbol font itself, use one of these instead:
%\usepackage[font={Nanum Gothic}]{hangulmath}                % 간격은 글꼴 기본값
%\usepackage[font={Nanum Gothic}, metrics=nanum]{hangulmath} % hangulmath-metrics.py로 만든 metrics 사용
% 문서 중간에서 바꾸기: \hangulmathfont{Nanum Gothic}
\usepackage{array,booktabs,longtable}
\usepackage{xcolor}
\usepackage[hidelinks]{hyperref}

% Korean prose font: the first one installed is used. hangulmath itself
% needs none of these (its symbols come from the bundled font).
%   Noto / Source Han: Linux, Overleaf;  AppleMyungjo: macOS;
%   UnBatang, Baekmuk Batang (batang.ttf): TeX Live / MacTeX;  Batang: Windows
% ================================================================
% 한글 본문 글꼴 고르기 / Choosing the Korean prose font
% ----------------------------------------------------------------
% 아래 줄 가운데 하나의 맨 앞 % 를 지우면 그 글꼴을 가장 먼저 씁니다.
% 그 글꼴이 설치되어 있지 않으면 경고 없이 다음 후보로 넘어갑니다.
% Uncomment ONE line to try that font first; if it is not installed,
% the candidate list below is used as before.
%\newcommand\koreanfontchoice{Noto Sans CJK KR}     % 본고딕 (Linux, Overleaf)
%\newcommand\koreanfontchoice{Noto Serif CJK KR}    % 본명조 (Linux, Overleaf)
%\newcommand\koreanfontchoice{Nanum Gothic}         % 나눔고딕
%\newcommand\koreanfontchoice{Nanum Myeongjo}       % 나눔명조
%\newcommand\koreanfontchoice{HCR Batang}           % 함초롬바탕 (한컴)
%\newcommand\koreanfontchoice{Apple SD Gothic Neo}  % 애플 산돌고딕 (macOS)
%\newcommand\koreanfontchoice{AppleMyungjo}         % 애플명조 (macOS)
%\newcommand\koreanfontchoice{Malgun Gothic}        % 맑은 고딕 (Windows)
%\newcommand\koreanfontchoice{Batang}               % 바탕 (Windows)
%\newcommand\koreanfontchoice{MyKoreanFont.otf}     % 문서 폴더에 둔 글꼴 파일
\providecommand\koreanfontchoice{}
% ================================================================
\newcommand\koreanfontcandidates{\koreanfontchoice, Noto Serif CJK KR, Source Han Serif K,
  Source Han Serif KR, AppleMyungjo, Nanum Myeongjo, NanumMyeongjo,
  UnBatang.ttf, batang.ttf, Batang, Malgun Gothic}
\ExplSyntaxOn
\bool_new:N \l__hmdoc_kofont_bool
\clist_set:Nx \l_tmpa_clist { \koreanfontcandidates }
\clist_map_inline:Nn \l_tmpa_clist
  {
    \bool_if:NF \l__hmdoc_kofont_bool
      {
        \IfFontExistsTF {#1}
          {
            \newfontfamily \koreanfont {#1} [ Scale = MatchLowercase ]
            \bool_set_true:N \l__hmdoc_kofont_bool
            \typeout {Korean~prose~font:~#1}
          } { }
      }
  }
\bool_if:NF \l__hmdoc_kofont_bool
  {
    \GenericWarning {} {Warning:~no~Korean~font~found~for~the~prose;~
      Korean~text~will~be~missing.~Install~e.g.~Noto~Serif~CJK~KR}
    \newcommand \koreanfont {}
  }
\ExplSyntaxOff
\newcommand\cs[1]{\texttt{\textbackslash#1}}
\newcommand\meta[1]{\ensuremath{\langle}\textrm{\itshape#1}\ensuremath{\rangle}}
\newcommand\marg[1]{\texttt{\{}\meta{#1}\texttt{\}}}
\newcommand\ko[1]{{\koreanfont #1}}
\newenvironment{koreanpar}
  {\par\koreanfont\sloppy\linespread{1.35}\selectfont}{\par}
\newenvironment{preface}[1]
  {\begin{quote}\setlength\parindent{0pt}\setlength\parskip{0.6ex}%
   #1\linespread{1.3}\selectfont}
  {\end{quote}}
\newenvironment{example}
  {\par\medskip\noindent\begin{minipage}{\linewidth}\small}
  {\end{minipage}\par\medskip}

% --- Code/output example boxes (Section 6) ------------------------
\usepackage{fancyvrb,listings,calc,needspace}
\definecolor{hmcodebg}{HTML}{EEF1F5}
\definecolor{hmrule}{HTML}{AEB8C6}
\definecolor{hmaccent}{HTML}{2F5D9B}
\definecolor{hmlabel}{HTML}{6B7686}
\lstdefinestyle{hmcode}{language=[LaTeX]TeX,
  basicstyle=\ttfamily\footnotesize, texcsstyle=*\color{hmaccent},
  columns=fullflexible, keepspaces, showstringspaces=false,
  breaklines, breakatwhitespace, breakindent=1.5em, aboveskip=0pt, belowskip=0pt,
  xleftmargin=0pt, framesep=0pt,
  moretexcs={aeh,ah,bbiub,bieup,biub,chieut,ciuc,ddiud,digeut,diud,eh,eoh,euh,euih,ggiug,giug,giyeok,hangulint,hangullim,hangulopscale,hangulsum,hieut,hiuh,ieung,ih,iung,jieut,jiuj,jjiuj,kieuk,kiuk,liul,mieum,mium,nieun,niun,oeh,oh,pieup,piup,rieul,siot,sius,ssangbieup,ssangdigeut,ssanggiyeok,ssangjieut,ssangsiot,ssius,tieut,tiut,uaeh,uah,ueh,ueoh,uh,uih,yaeh,yah,yeh,yeoh,yoh,yuh}}
\newlength\hmexlabelw \setlength\hmexlabelw{13mm}
\newcommand\hmexlabel[2]{% #1 colour, #2 text
  \makebox[\hmexlabelw][l]{\hspace{2mm}%
    \textcolor{#1}{\sffamily\scriptsize\bfseries #2}}}
\newcommand\hmexfile{\jobname-ex.tmp}
% #1 = 1: body is math (typeset centred in display style)
% #1 = 0: body is text (typeset as is, e.g. an align* environment)
\newcommand\hmexshow[1]{%
  \par\addvspace{1ex}\noindent
  \begin{minipage}{\linewidth}%
    \setlength\fboxsep{0pt}\setlength\fboxrule{0pt}%
    {\color{hmrule}\hrule height 0.4pt}%
    \colorbox{hmcodebg}{\begin{minipage}{\linewidth}%
      \vspace{0.8ex}%
      \hmexlabel{hmlabel}{LaTeX}%
      \begin{minipage}[t]{\linewidth-\hmexlabelw-2mm}%
        \lstinputlisting[style=hmcode]{\hmexfile}%
      \end{minipage}%
      \vspace{0.6ex}%
    \end{minipage}}\par
    \vspace{0.5ex}%
    \setlength\fboxrule{0.4pt}\setlength\fboxsep{3pt}%
    \hmexlabel{hmaccent}{Output}%
    \begin{minipage}[c]{\linewidth-\hmexlabelw-2mm}%
      \centering
      \ifnum#1=1 $\displaystyle\input{\hmexfile}$\else
        \input{\hmexfile}\fi
    \end{minipage}\par
    \vspace{0.5ex}%
    {\color{hmrule}\hrule height 0.4pt}%
  \end{minipage}\par\addvspace{1ex}}
\newenvironment{hmex}
  {\VerbatimEnvironment\begin{VerbatimOut}{\hmexfile}}
  {\end{VerbatimOut}\hmexshow{1}}
\newenvironment{hmextext}
  {\VerbatimEnvironment\begin{VerbatimOut}{\hmexfile}}
  {\end{VerbatimOut}\hmexshow{0}}

\setlength\parindent{0pt}
\setlength\parskip{0.6ex}

\title{\textsf{hangulmath}\\[0.5ex]
  \large Hangul jamo as mathematical symbols}
\author{Inkyu Park \\ \texttt{icpark00@gmail.com}}
\date{Version 0.7 \quad 2026/10/15}

\begin{document}
\maketitle

\begin{center}
  {\LARGE\koreanfont 訓民正號}\\[0.5ex]
  {\large\koreanfont 훈민정호 \textrm{---} 백성을 가르치는 바른 기호}\\[0.3ex]
  {\itshape The Correct Symbols for the Instruction of the People}
\end{center}

\begin{preface}{\koreanfont\sloppy}
나랏 수식이 로마자와 희랍자에 머물러 그 수가 넉넉디 아니할쎄,
이런 젼차로 어린 수학자가 쓰고져 홀 새 변수가 이셔도
마참내 제 뜨들 시러 펴디 몯할 노미 하니라.

내 이랄 어엿비 너겨 새로 마흔 기호를 맹가노니,
학자마다 수비 니겨 날로 레이텍에 쑤메 편안케 하고져 할 따라미니라.
\[
  \#\{\giug,\ \niun,\ \diud,\ \dots,\ \uih,\ \euih\} = 19 + 21 = 40
\]

\hfill 병오년(2026) 한글날
\end{preface}

\begin{preface}{}
Whereas the symbols of our mathematics remain confined to the Roman and
Greek letters, and their number is not sufficient, many a humble
mathematician, though wishing to write a new variable, has in the end
been unable to express his meaning.

Taking pity on them, I have newly made forty symbols, so that every
scholar may learn them with ease and use them daily in \LaTeX; and this
is all I desire.
\[
  \#\{\giug,\ \niun,\ \diud,\ \dots,\ \uih,\ \euih\} = 19 + 21 = 40
\]

\hfill \textit{Given on Hangul Day, in the year 2026}
\end{preface}

\clearpage
\tableofcontents
\clearpage

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

Mathematical notation draws almost entirely on the Latin and Greek
alphabets, and in a long paper one easily runs out of distinct letters.
The Korean alphabet, Hangul, offers a clean supply of new symbols: its
letters (\emph{jamo}) are built from simple geometric strokes, are
visually distinct from Latin and Greek, and each has a well-established
name.

The \textsf{hangulmath} package makes the 40 jamo of modern Hangul
available in mathematics: 14 basic consonants, 5 double consonants,
10 basic vowels and 11 compound vowels. Each symbol has a command
named after the letter, so $\giyeok$ is \cs{giyeok}, much as $\alpha$
is \cs{alpha}. Consonants also have a four-letter alias that is easy to
remember (\cs{giug}).

\begin{example}
\[
  \hangulsum\tiut_{k=1}^{n} \giug_k^{\,2}
  \;\le\; \Bigl(\hangulsum\tiut_{k=1}^{n} \giug_k\Bigr)^{2},
  \qquad
  \mium^2 \vec{A} = -\mu_0 \vec{J},
  \qquad
  \hangullim\liul_{x\to\infty} f(x) = b.
\]
\end{example}

The symbols are taken from a bundled subset of the Noto Sans CJK KR
typeface, so no Korean font needs to be installed.

% ===================================================================
\section{Requirements and installation}

\textsf{hangulmath} requires \textbf{XeLaTeX or LuaLaTeX} (it uses
\textsf{fontspec}) and a LaTeX kernel from 2022 or later. It does not
work with pdfLaTeX; the package stops with an error if loaded there.

\paragraph{TeX Live and MiKTeX.} Once the package is distributed via
CTAN it is installed with the usual package manager
(\texttt{tlmgr install hangulmath}, or automatically by MiKTeX).

\paragraph{Manual installation.} Copy the following files into the
directory of your document, or into your local \texttt{texmf} tree
(\texttt{tex/latex/hangulmath/} and \texttt{fonts/opentype/public/hangulmath/}),
then run \texttt{mktexlsr} if appropriate:
\begin{quote}\ttfamily
hangulmath.sty\\ hangulmath-metrics.def\\
hangulmath-sans.otf\\ hangulmath-sans-light.otf
\end{quote}

\paragraph{Overleaf.} Upload the four files above into your project
and set the compiler to XeLaTeX (\emph{Menu} $\to$ \emph{Compiler}),
or add a file \texttt{latexmkrc} containing \verb|$pdf_mode = 5;|.

% ===================================================================
\section{Usage}

\begin{verbatim}
\usepackage{hangulmath}
...
$\giyeok + \nieun = \digeut$   or, with aliases,   $\giug + \niun = \diud$
\end{verbatim}

Every symbol command works in math mode and also in running text (it
uses \cs{ensuremath}). The symbols are ordinary math symbols
(\cs{mathord}): they take sub- and superscripts and scale correctly in
script styles. They are always set upright, whatever the surrounding
text font.

\begin{example}
\verb|$\giug_{\ah}(x)$, $\niun^{\ih j}$, $X\giug x\niun$|
\hfill
$\giug_{\ah}(x)$, $\niun^{\ih j}$, $X\giug x\niun$
\end{example}

\subsection{Package options}

\begin{longtable}{@{}>{\ttfamily}l p{0.62\linewidth}@{}}
\toprule
option & meaning\\ \midrule
font=\meta{font} & Font for the symbols, given by name or file name.
  Default: the bundled \texttt{hangulmath-sans.otf}
  (HangulMath Sans DemiLight).\\
opfont=\meta{font} & Font for the large operator forms
  (Section~\ref{sec:operators}). Default: the bundled, lighter
  \texttt{hangulmath-sans-light.otf}.\\
metrics=\meta{file} & Name (without \texttt{.def}) of the metrics file that
  describes the glyphs of \texttt{font}. Default:
  \texttt{hangulmath-metrics}, which matches the bundled font.
  See Section~\ref{sec:fonts}.\\
scale=\meta{number} & Scale factor for the symbol font. Default: taken from the
  metrics file (about 1.24 for the bundled font).\\
sidebearing=\meta{em} & Space, in em, added to the left and right of each
  glyph. Default: \texttt{0.06}.\\
\bottomrule
\end{longtable}

If a requested font is not installed, \textsf{hangulmath} issues a
warning and uses the bundled font instead, so that documents always
compile.

\subsection{Using with kotex}\label{sec:kotex}

\textsf{hangulmath} works together with the Korean typesetting package
\textsf{kotex} (\textsf{xetexko} or \textsf{luatexko}), loaded before or
after it. \textsf{kotex} normally sends every Hangul character to its own
Korean text font; \textsf{hangulmath} switches this off locally inside
its symbols, so they always come from the symbol font, with the same
size and alignment as without \textsf{kotex}.

\textsf{kotex} already uses the command name \cs{rieul} (as a josa
command), so \textsf{hangulmath} leaves that name untouched and prints a
warning. Write \ko{ㄹ} as \cs{liul} instead.

\paragraph{\cs{hangulsym}.} More generally, if any command name is
already taken by another package, \textsf{hangulmath} does not overwrite
it but warns, naming the alternatives. Every symbol can always be reached
by name:
\begin{example}
\verb|$\hangulsym{rieul} = \hangulsym{liul} = \liul$|
\hfill
$\hangulsym{rieul} = \hangulsym{liul} = \liul$
\end{example}

% ===================================================================
\section{The symbols}

\subsection{Naming rules}

\begin{itemize}
\item \textbf{Official names} follow the Revised Romanization of Korean:
  \cs{giyeok}, \cs{nieun}, \dots, \cs{ssanggiyeok}.
\item \textbf{Consonant aliases} have four letters: the consonant,
  \texttt{iu}, and the consonant again, imitating the shape of the
  Korean letter names (\ko{기역} $\to$ \cs{giug}, \ko{니은} $\to$
  \cs{niun}). Their first letters are all different, so the first letter
  alone identifies the consonant. Two adjustments are needed:
  \ko{ㅇ} has no initial sound and is \cs{iung}; \ko{ㅊ} is written
  with \texttt{c} to keep four letters, \cs{ciuc}. \ko{ㄹ} uses
  \texttt{l}, its sound at the end of a syllable.
\item \textbf{Double consonants} double the first letter of the alias:
  \cs{ggiug}, \cs{ddiud}, \cs{bbiub}, \cs{ssius}, \cs{jjiuj}.
\item \textbf{Vowels} are written as pronounced, followed by \texttt{h}:
  \cs{ah}, \cs{eoh}, \cs{ih}. The trailing \texttt{h} avoids clashes
  with existing commands such as \cs{a}, \cs{o}, \cs{u} and \cs{i}.
  In compound vowels the glide \emph{w} is written \texttt{u}
  (\cs{uah} for \ko{ㅘ}). \ko{ㅢ} is \cs{euih} (\ko{ㅡ}+\ko{ㅣ}) to
  distinguish it from \ko{ㅟ}, \cs{uih}.
\end{itemize}

\subsection{Consonants}

\noindent\begin{minipage}[t]{0.49\linewidth}
\begin{tabular}{@{}c>{\ttfamily}l>{\ttfamily}l>{\ttfamily\small}l@{}}
\toprule
 & official & alias & Unicode\\ \midrule
$\giyeok$ & \textbackslash giyeok & \textbackslash giug & U+3131\\
$\nieun$  & \textbackslash nieun  & \textbackslash niun & U+3134\\
$\digeut$ & \textbackslash digeut & \textbackslash diud & U+3137\\
$\rieul$  & \textbackslash rieul  & \textbackslash liul & U+3139\\
$\mieum$  & \textbackslash mieum  & \textbackslash mium & U+3141\\
$\bieup$  & \textbackslash bieup  & \textbackslash biub & U+3142\\
$\siot$   & \textbackslash siot   & \textbackslash sius & U+3145\\
\bottomrule
\end{tabular}
\end{minipage}\hfill
\begin{minipage}[t]{0.49\linewidth}
\begin{tabular}{@{}c>{\ttfamily}l>{\ttfamily}l>{\ttfamily\small}l@{}}
\toprule
 & official & alias & Unicode\\ \midrule
$\ieung$  & \textbackslash ieung  & \textbackslash iung & U+3147\\
$\jieut$  & \textbackslash jieut  & \textbackslash jiuj & U+3148\\
$\chieut$ & \textbackslash chieut & \textbackslash ciuc & U+314A\\
$\kieuk$  & \textbackslash kieuk  & \textbackslash kiuk & U+314B\\
$\tieut$  & \textbackslash tieut  & \textbackslash tiut & U+314C\\
$\pieup$  & \textbackslash pieup  & \textbackslash piup & U+314D\\
$\hieut$  & \textbackslash hieut  & \textbackslash hiuh & U+314E\\
\bottomrule
\end{tabular}
\end{minipage}

\subsection{Double consonants}

\begin{tabular}{@{}c>{\ttfamily}l>{\ttfamily}l>{\ttfamily\small}l@{}}
\toprule
 & official & alias & Unicode\\ \midrule
$\ssanggiyeok$ & \textbackslash ssanggiyeok & \textbackslash ggiug & U+3132\\
$\ssangdigeut$ & \textbackslash ssangdigeut & \textbackslash ddiud & U+3138\\
$\ssangbieup$  & \textbackslash ssangbieup  & \textbackslash bbiub & U+3143\\
$\ssangsiot$   & \textbackslash ssangsiot   & \textbackslash ssius & U+3146\\
$\ssangjieut$  & \textbackslash ssangjieut  & \textbackslash jjiuj & U+3149\\
\bottomrule
\end{tabular}

\subsection{Vowels and compound vowels}

\noindent\begin{minipage}[t]{0.49\linewidth}
\begin{tabular}{@{}c>{\ttfamily}l>{\ttfamily\small}l@{}}
\toprule
 & command & Unicode\\ \midrule
$\ah$   & \textbackslash ah   & U+314F\\
$\yah$  & \textbackslash yah  & U+3151\\
$\eoh$  & \textbackslash eoh  & U+3153\\
$\yeoh$ & \textbackslash yeoh & U+3155\\
$\oh$   & \textbackslash oh   & U+3157\\
$\yoh$  & \textbackslash yoh  & U+315B\\
$\uh$   & \textbackslash uh   & U+315C\\
$\yuh$  & \textbackslash yuh  & U+3160\\
$\euh$  & \textbackslash euh  & U+3161\\
$\ih$   & \textbackslash ih   & U+3163\\
\bottomrule
\end{tabular}
\end{minipage}\hfill
\begin{minipage}[t]{0.49\linewidth}
\begin{tabular}{@{}c>{\ttfamily}l>{\ttfamily\small}l@{}}
\toprule
 & command & Unicode\\ \midrule
$\aeh$  & \textbackslash aeh  & U+3150\\
$\yaeh$ & \textbackslash yaeh & U+3152\\
$\eh$   & \textbackslash eh   & U+3154\\
$\yeh$  & \textbackslash yeh  & U+3156\\
$\uah$  & \textbackslash uah  & U+3158\\
$\uaeh$ & \textbackslash uaeh & U+3159\\
$\oeh$  & \textbackslash oeh  & U+315A\\
$\ueoh$ & \textbackslash ueoh & U+315D\\
$\ueh$  & \textbackslash ueh  & U+315E\\
$\uih$  & \textbackslash uih  & U+315F\\
$\euih$ & \textbackslash euih & U+3162\\
\bottomrule
\end{tabular}
\end{minipage}

% ===================================================================
\section{Operator forms}\label{sec:operators}

The symbol commands produce ordinary symbols. To use a symbol as an
operator, wrap it in one of the following commands. They accept any
math symbol, not only Hangul.

\begin{longtable}{@{}>{\ttfamily}l p{0.62\linewidth}@{}}
\toprule
command & behaviour\\ \midrule
\textbackslash hangulsum\{\meta{sym}\} & Large; in display style, limits
  below and above (like \cs{sum}).\\
\textbackslash hangulint\{\meta{sym}\} & Large; limits at the side
  (like \cs{int}).\\
\textbackslash hangullim\{\meta{sym}\} & Normal size; in display style,
  limits below (like \cs{lim}).\\
\textbackslash hangulopscale\{\meta{d}\}\{\meta{t}\} & Sets the
  magnification of the large forms in display and text style
  (defaults 2.0 and 1.3).\\
\bottomrule
\end{longtable}

The large forms are drawn with the lighter operator font
(\texttt{opfont}), so that magnification does not make their strokes
heavier than those of \cs{sum} and \cs{int}.

\begin{example}
\begin{verbatim}
\[ \hangulsum\tiut_{k=1}^{n} k^2 = \frac{n(n+1)(2n+1)}{6} \]
\end{verbatim}
\[
  \hangulsum\tiut_{k=1}^{n} k^2 = \frac{n(n+1)(2n+1)}{6},
  \qquad
  \hangulsum\tiut_{i=1}^{m}\hangulsum\tiut_{j=1}^{n} a_{ij}
  \quad\text{vs.}\quad
  \sum_{i=1}^{m}\sum_{j=1}^{n} a_{ij}
\]
Inline: $\hangulsum\tiut_{k=1}^{n} \giug_k = \sum_{k=1}^{n} \giug_k$.
\end{example}

\begin{example}
\begin{verbatim}
\[ \hangulint\diud_{x=0}^{x=1} f(x) = a \qquad
   \hangullim\liul_{x\to\infty} f(x) = b \]
\end{verbatim}
\[
  \hangulint\diud_{x=0}^{x=1} f(x) = a
  \qquad
  \hangullim\liul_{x\to\infty} f(x) = b
  \qquad
  \hangullim\liul_{n\to\infty}\Bigl(1+\frac{1}{n}\Bigr)^{n} = e
\]
\end{example}

% ===================================================================
\section{More examples}\label{sec:examples}

Each example below shows the \LaTeX\ input (shaded, labelled
\textsf{LaTeX}) directly above its typeset result (labelled
\textsf{Output}). Unless an example says otherwise, the input is math
and is set in display style. The notations are suggestions, not
standards; define them in your text before using them.

% -------------------------------------------------------------------
\Needspace{12\baselineskip}
\subsection{Vowels as brackets}

The vowels $\eoh$ and $\ah$ are mirror images, with a stroke pointing
outwards like the angle brackets $\langle\ \rangle$. They give a Dirac
notation in which a bra is $\eoh\psi|$ and a ket is $|\phi\ah$. The
vowels with two strokes, $\yeoh$ and $\yah$, give double brackets
$\langle\!\langle\ \rangle\!\rangle$, as used for operators in Liouville
space. Reversed pairs, with the strokes pointing inwards, make further
kinds of bracket. Macros such as
\verb+\newcommand\ket[1]{|#1\ah}+ shorten the input.

\begin{hmex}
\eoh\psi|\phi\ah = \int \psi^*(x)\,\phi(x)\,dx
\end{hmex}

\begin{hmex}
\eoh\phi|\psi\ah = \eoh\psi|\phi\ah^*
\end{hmex}

\begin{hmex}
|\psi\ah = \sum_n c_n\,|n\ah, \qquad c_n = \eoh n|\psi\ah
\end{hmex}

\begin{hmex}
\sum_n |n\ah\eoh n| = \mathbf{1}
\end{hmex}

\begin{hmex}
\eoh A\ah = \eoh\psi|A|\psi\ah, \qquad (\Delta A)^2 = \eoh A^2\ah - \eoh A\ah^2
\end{hmex}

\begin{hmex}
\eoh x|p\ah = \frac{1}{\sqrt{2\pi\hbar}}\,e^{ipx/\hbar}
\end{hmex}

\begin{hmex}
\eoh x|x'\ah = \delta(x - x')
\end{hmex}

\begin{hmex}
\yeoh A|B\yah = \operatorname{Tr}(A^\dagger B)
\end{hmex}

\begin{hmex}
\frac{d}{dt}|\rho\yah = \mathcal{L}\,|\rho\yah
\end{hmex}

\begin{hmex}
\eoh A(t)\ah = \yeoh A|e^{\mathcal{L}t}|\rho_0\yah
\end{hmex}

\begin{hmex}
\ah A, B\eoh = AB + BA, \qquad \ah\psi(x), \psi^\dagger(y)\eoh = \delta(x - y)
\end{hmex}

\begin{hmex}
\yah A|B\yeoh = \int_0^1 \operatorname{Tr}(A^\dagger\rho^{s}B\rho^{1-s})\,ds
\end{hmex}

\begin{hmex}
\aeh P, Q\eh = -(-1)^{(p-1)(q-1)}\,\aeh Q, P\eh, \qquad \aeh\pi, \pi\eh = 0
\end{hmex}

% -------------------------------------------------------------------
\Needspace{12\baselineskip}
\subsection{Consonants as function names}

Followed by an argument, a consonant reads naturally as the name of a
function. Some shapes suggest a meaning: $\giug$ looks like a mirrored
$\Gamma$, and makes a good name for the reciprocal gamma function;
$\mium$ is a box, the rectangle function; $\sius$ is a tent, the
triangle function; and $\iung$ is a disc, the circle function of
optics.

\begin{hmex}
\giug(x),\ \niun(x),\ \diud(x),\ \liul(x),\ \mium(x),\ \biub(x),\ \sius(x)
\end{hmex}

\begin{hmex}
\iung(x),\ \jiuj(x),\ \ciuc(x),\ \kiuk(x),\ \tiut(x),\ \piup(x),\ \hiuh(x)
\end{hmex}

\begin{hmex}
\ggiug(x),\ \ddiud(x),\ \bbiub(x),\ \ssius(x),\ \jjiuj(x)
\end{hmex}

\begin{hmex}
\giug(z) = \frac{1}{\Gamma(z)}, \qquad \giug(z)\,\giug(1-z) = \frac{\sin\pi z}{\pi}
\end{hmex}

\begin{hmex}
\giug(z) = z\,e^{\gamma z}\prod_{n=1}^{\infty}\Bigl(1 + \frac{z}{n}\Bigr)e^{-z/n}
\end{hmex}

\begin{hmex}
\mium(x) = \begin{cases} 1, & |x| < \frac12 \\ 0, & |x| > \frac12 \end{cases}
\end{hmex}

\begin{hmex}
\sius(x) = \max(1 - |x|, 0)
\end{hmex}

\begin{hmex}
\mium * \mium = \sius, \qquad \hat{\mium}(k) = \operatorname{sinc}\frac{k}{2}
\end{hmex}

\begin{hmex}
\hat{\sius}(k) = \operatorname{sinc}^2\frac{k}{2}
\end{hmex}

\begin{hmex}
\iung(r) = \begin{cases} 1, & r < 1 \\ 0, & r > 1 \end{cases}
\end{hmex}

\begin{hmex}
\hat{\iung}(\rho) = \frac{J_1(2\pi\rho)}{\rho}
\end{hmex}

% -------------------------------------------------------------------
\Needspace{12\baselineskip}
\subsection{\texorpdfstring{$\pieup$}{Pieup} the Hamiltonian, \texorpdfstring{$\rieul$}{Rieul} the Lagrangian}

With its two horizontal bars and two posts, $\pieup$ is a sturdy
letter for the Hamiltonian; $\rieul$ is the first consonant of
\ko{라그랑지안}.

\begin{hmex}
\piup\,|\psi\ah = E\,|\psi\ah
\end{hmex}

\begin{hmex}
i\hbar\,\frac{\partial}{\partial t}|\psi(t)\ah = \piup\,|\psi(t)\ah
\end{hmex}

\begin{hmex}
\piup = \frac{p^2}{2m} + V(x), \qquad E_n = \eoh n|\piup|n\ah
\end{hmex}

\begin{hmex}
\frac{dA}{dt} = \frac{i}{\hbar}[\piup, A] + \frac{\partial A}{\partial t}
\end{hmex}

\begin{hmex}
\frac{df}{dt} = \{f, \piup\}
\end{hmex}

\begin{hmex}
Z = \operatorname{Tr} e^{-\beta\piup}, \qquad \rho = \frac{e^{-\beta\piup}}{Z}
\end{hmex}

\begin{hmex}
F = -\frac{1}{\beta}\ln Z
\end{hmex}

\begin{hmex}
\eoh q_f|e^{-i\piup t/\hbar}|q_i\ah = \int \mathcal{D}q\; e^{iS[q]/\hbar}
\end{hmex}

\begin{hmex}
S[q] = \int \liul\,dt
\end{hmex}

\begin{hmex}
\frac{d}{dt}\frac{\partial\liul}{\partial\dot q}=\frac{\partial\liul}{\partial q}
\end{hmex}

\begin{hmex}
\piup = p\,\dot q - \liul
\end{hmex}

\begin{hmex}
\dot q = \frac{\partial\piup}{\partial p}
\end{hmex}

\begin{hmex}
\dot p = -\frac{\partial\piup}{\partial q}
\end{hmex}

\begin{hmex}
\liul = -\tfrac14 F_{\mu\nu}F^{\mu\nu} + \bar\psi\,(i\gamma^\mu D_\mu - m)\,\psi
\end{hmex}

% -------------------------------------------------------------------
\Needspace{12\baselineskip}
\subsection{\texorpdfstring{$\chieut$}{Chieut} as a superscript mark}

Set as a superscript, $\chieut$ joins the prime, the asterisk and the
dagger as a mark for a new kind of conjugate, dual or distinguished
point.

\begin{hmex}
A',\qquad A^*,\qquad A^\dagger,\qquad A^{\ciuc}
\end{hmex}

\begin{hmex}
(AB)^{\ciuc} = B^{\ciuc}A^{\ciuc}, \qquad (A^{\ciuc})^{\ciuc} = A
\end{hmex}

\begin{hmex}
\eoh\psi|A\phi\ah = \eoh A^{\ciuc}\psi|\phi\ah
\end{hmex}

\begin{hmex}
f^{\ciuc}(y) = \sup_x\bigl(xy - f(x)\bigr)
\end{hmex}

\begin{hmex}
f^{\ciuc\ciuc} = f \quad\text{($f$ convex)}
\end{hmex}

\begin{hmex}
\piup(q,p) = \liul^{\ciuc} = \sup_{\dot q}\bigl(p\,\dot q - \liul(q,\dot q)\bigr)
\end{hmex}

\begin{hmex}
x^{\ciuc} = \operatorname*{arg\,min}_x f(x), \qquad \nabla f(x^{\ciuc}) = 0
\end{hmex}

\begin{hmex}
T^{\ciuc},\ p^{\ciuc},\ V^{\ciuc}
\end{hmex}

% -------------------------------------------------------------------
\Needspace{12\baselineskip}
\subsection{\texorpdfstring{$\oh$, $\yoh$, $\uh$, $\yuh$}{O, yo, u, yu} as arrows}

The stroke of $\oh$ points up and that of $\uh$ points down; $\yoh$
and $\yuh$ have two strokes. They serve as arrows: spins up and down,
the electrons of an oxygen atom in its orbitals, gas evolved and precipitate formed, monotone limits, and Knuth's arrow
notation. Wrap them in \cs{mathrel} or \cs{mathbin} where they act as
relations or operations, so that they get the right spacing.

\begin{hmex}
\sigma_z|\oh\ah = +|\oh\ah, \qquad \sigma_z|\uh\ah = -|\uh\ah
\end{hmex}

\begin{hmex}
S_+|\uh\ah = \hbar\,|\oh\ah
\end{hmex}

\begin{hmex}
|\psi^-\ah = \frac{1}{\sqrt{2}}\bigl(|\oh\uh\ah - |\uh\oh\ah\bigr)
\end{hmex}

\begin{hmex}
|\yoh\ah = |\oh\oh\ah,\quad |\yuh\ah = |\uh\uh\ah
\end{hmex}

\begin{hmex}
1s\boxed{\oh\uh}\;\; 2s\boxed{\oh\uh}\;\; 2p\boxed{\oh\uh}\boxed{\oh}\boxed{\oh}
\end{hmex}

\begin{hmex}
\mathrm{CaCO_3 + 2HCl \to CaCl_2 + H_2O + CO_2}\,\oh
\end{hmex}

\begin{hmex}
\mathrm{Ag^+} + \mathrm{Cl^-} \to \mathrm{AgCl}\,\uh
\end{hmex}

\begin{hmex}
\mathrm{Ba^{2+}} + \mathrm{SO_4^{2-}} \to \mathrm{BaSO_4}\,\uh
\end{hmex}

\begin{hmex}
x \mathrel{\uh} 0 \quad (x \downarrow 0)
\end{hmex}

\begin{hmex}
f_n \mathrel{\oh} f \implies \int f_n\,d\mu \mathrel{\oh} \int f\,d\mu
\end{hmex}

\begin{hmex}
a \mathbin{\oh} b = a^b, \qquad 2 \mathbin{\yoh} 4 = 2^{2^{2^{2}}} = 65536
\end{hmex}

% -------------------------------------------------------------------
\Needspace{12\baselineskip}
\subsection{Consonants as element symbols}

With pre-scripts for mass and atomic numbers, consonants become the
symbols of imaginary elements, and enter formulas, equations and
equilibrium constants like real ones.

\begin{hmex}
{}^{298}_{120}\giug \to {}^{294}_{118}\niun + {}^{4}_{2}\mathrm{He}
\end{hmex}

\begin{hmex}
{}^{14}_{6}\ciuc \to {}^{14}_{7}\diud + e^- + \bar\nu_e
\end{hmex}

\begin{hmex}
2\,\giug_2 + \iung_2 \rightleftharpoons 2\,\giug_2\iung
\end{hmex}

\begin{hmex}
K = \frac{[\giug_2\iung]^2}{[\giug_2]^2\,[\iung_2]}
\end{hmex}

\begin{hmex}
\ssius^{2+} + 2\,\diud^- \to \ssius\diud_2\,\uh
\end{hmex}

\begin{hmex}
\biub\liul_3 + 3\,\mathrm{H_2O} \to \biub(\mathrm{OH})_3 + 3\,\mathrm{H}\liul
\end{hmex}

\begin{hmex}
\mathrm{C_6H_{12}O_6} + 6\,\iung_2 \to 6\,\mathrm{C}\iung_2 + 6\,\mathrm{H_2}\iung
\end{hmex}

% -------------------------------------------------------------------
\Needspace{12\baselineskip}
\subsection{Operators}

The shape of $\mieum$ suggests the d'Alembertian (box) operator, and
the operator forms of Section~\ref{sec:operators} give sums, products,
integrals and limits. A large $\giyeok$, the first consonant of
\ko{곱} (product), stands in for $\prod$ (here over primes $p$).

\begin{hmex}
\mium^2 \equiv \nabla^2 - \frac{1}{c^2}\frac{\partial^2}{\partial t^2}
\end{hmex}

\begin{hmex}
\mium^2 A^\mu = -\mu_0 J^\mu, \qquad (\mium^2 - m^2)\,\phi = 0
\end{hmex}

\begin{hmex}
\zeta(s) = \hangulsum\tiut_{n\ge1} n^{-s} = \hangulsum\giug_{p}\,(1 - p^{-s})^{-1}
\end{hmex}

\begin{hmex}
\hangulint\diud_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
\end{hmex}

\begin{hmex}
\hangullim\liul_{n\to\infty}\Bigl(1 + \frac{1}{n}\Bigr)^{n} = e
\end{hmex}

\begin{hmex}
{}_2\biub_1(a,b;c;z) = \hangulsum\tiut_{n\ge0}\frac{(a)_n(b)_n}{(c)_n\,n!}\,z^n
\end{hmex}

% -------------------------------------------------------------------
\Needspace{12\baselineskip}
\subsection{In running text}

The symbol commands also work outside math mode. This input is text,
not math.

\begin{hmextext}
Spin up is $|\oh\ah$, spin down $|\uh\ah$; also in plain text: \oh{} and \uh{}.
\end{hmextext}

% ===================================================================
\section{Using other fonts}\label{sec:fonts}

Hangul compatibility jamo are drawn small and high in the em square of
most Korean fonts, with large side bearings. \textsf{hangulmath}
therefore scales all glyphs by a common factor, lowers them by a common
amount so that consonants sit on the baseline, and trims each glyph to
its ink. These values depend on the font and are stored in a metrics
file.

To use another font, generate a metrics file with the Python script
\texttt{hangulmath-metrics.py} (Python 3.10+, \texttt{pip install
fonttools}):
\begin{verbatim}
python3 hangulmath-metrics.py "Nanum Gothic" -o nanum.def
\end{verbatim}
and load it together with the font:
\begin{verbatim}
\usepackage[font={Nanum Gothic}, metrics=nanum]{hangulmath}
\end{verbatim}
\cs{hangulmathfont}\marg{font} and \cs{hangulmathopfont}\marg{font} change the
fonts later in the preamble.

% ===================================================================
\section{Caveats}

\begin{itemize}
\item \textbf{Look-alikes.} $\euh$ resembles a minus sign and $\ih$ a
  vertical bar. Use them with care, and say in the text which letter
  you mean.
\item \textbf{Engines.} pdfLaTeX is not supported. Check whether your
  publisher or preprint server compiles with XeLaTeX or LuaLaTeX before
  relying on the package for a submission.
\item \textbf{Name clashes.} If another package defines a command with
  the same name as a symbol, the other package wins and
  \textsf{hangulmath} warns; use the alias or \cs{hangulsym}
  (Section~\ref{sec:kotex}).
\item \textbf{Searchability.} The symbols are real Unicode characters in
  the PDF, so they can be copied and searched.
\end{itemize}

% ===================================================================
\section{Korean summary \ko{(한국어 요약)}}

\begin{koreanpar}
hangulmath는 현대 한글 자모 40자(기본 자음 14, 쌍자음 5, 기본 모음 10,
복모음 11)를 수식 기호로 쓸 수 있게 하는 패키지입니다.
XeLaTeX 또는 LuaLaTeX에서 동작하며, 기호용 고딕체 글꼴이 함께 들어 있어
따로 한글 글꼴을 설치할 필요가 없습니다.

명령어는 로마자 표기법에 따른 공식 이름(\cs{giyeok})과 외우기 쉬운 네
글자 약어(\cs{giug})가 있습니다. 약어는 자음, iu, 자음의 순서이며,
쌍자음은 첫 글자를 두 번 씁니다(\cs{ggiug}). 모음은 소리 나는 대로 쓰고
끝에 h를 붙입니다(\cs{ah}, \cs{uah}).

합, 적분, 극한처럼 쓰려면 \cs{hangulsum}, \cs{hangulint},
\cs{hangullim}으로 감쌉니다.
모음은 괄호로도 쓸 수 있습니다. 예컨대 디랙 표기 $\langle\psi|\phi\rangle$를
$\eoh\psi|\phi\ah$로 씁니다. 6절에 예제가 더 있습니다.
\begin{center}\verb|\hangulsum\tiut_{k=1}^{n} a_k|\quad $\Rightarrow$\quad $\displaystyle\hangulsum\tiut_{k=1}^{n} a_k$\end{center}
\end{koreanpar}

% ===================================================================
\section{License}

Copyright \copyright\ 2026 Inkyu Park.
Source code and issue tracker:
\url{https://github.com/krunyx/hangulmath}.

The package files may be distributed and/or modified under the
conditions of the \LaTeX\ Project Public License, version 1.3c or (at
your option) any later version.

The bundled fonts \texttt{hangulmath-sans.otf} and
\texttt{hangulmath-sans-light.otf} are modified (subset and renamed)
versions of Noto Sans CJK KR, copyright 2014--2021 Adobe, and are
distributed under the SIL Open Font License 1.1; see \texttt{OFL.txt}.
They are rebuilt with \texttt{hangulmath-fonts.py}.

\section{Change history}

\begin{description}
\item[v0.7 (2026/10/15)] Works with \textsf{kotex} (\textsf{xetexko} and
  \textsf{luatexko}) in either loading order: the symbols no longer fall
  into kotex's Korean text font. Command names already defined by another
  package (such as kotex's \cs{rieul}) are left alone with a warning
  instead of causing an error. New command \cs{hangulsym}\marg{name}.
  New one-page example \texttt{hangulmath-minimal.tex}.
\item[v0.6 (2026/10/11)] Documentation: Section~\ref{sec:examples}
  greatly expanded, with each example shown as \LaTeX\ input and typeset
  output: vowels as brackets, consonants as function names, $\pieup$
  as the Hamiltonian, $\chieut$ as a superscript mark, $\oh$ and $\uh$
  as arrows, consonants as element symbols. No change to the package
  code. The preface (Korean and English) rewritten as a closer parody
  of the Hunminjeongeum; the document preamble offers commented-out
  lines for choosing another Korean font.
\item[v0.5 (2026/10/10)] First public release.
\end{description}

\end{document}