\documentclass[luatex,fontsize=8pt,paper=b5,twoside]{jlreq}%
\usepackage{amsmath,amssymb}
\usepackage{booktabs,caption}
\usepackage{luwa-ul, KKluaverb}
\usepackage[most]{tcolorbox}
\usepackage{luatexja-ruby,lltjext}
\usepackage{modernruler}

% You can omit these font settings.
\makeatletter
\RequirePackage[no-math]{fontspec}
\RequirePackage[no-math,match,scale=1]{luatexja-fontspec}
\RequirePackage[hiragino-pro,deluxe,expert]{luatexja-preset}
\setmainfont{HiraMinPro-W3}[BoldFont=HiraMinPro-W6]
\setmainjfont{HiraMinPro-W3}[BoldFont=HiraMinPro-W6]
\newfontfamily{\sfhira@pre}{HiraKakuPro-W3}[BoldFont=HiraKakuPro-W6]
\newjfontfamily{\sfhiraj@pre}{HiraKakuPro-W3}[BoldFont=HiraKakuPro-W6]
\newfontfamily{\mchira@pre}{HiraMinPro-W3}[BoldFont=HiraMinPro-W6]
\newjfontfamily{\mchiraj@pre}{HiraMinPro-W3}[BoldFont=HiraMinPro-W6]
\newfontfamily{\gthira@pre}{HiraKakuPro-W3}[BoldFont=HiraKakuPro-W6,FontFace={eb}{\shapedefault}{HiraKakuStd-W8}]
\newjfontfamily{\gthiraj@pre}{HiraKakuPro-W3}[BoldFont=HiraKakuPro-W6,FontFace={eb}{\shapedefault}{HiraKakuStd-W8}]
\newfontfamily{\mghira@pre}{HiraMaruPro-W4}
\newjfontfamily{\mghiraj@pre}{HiraMaruPro-W4}
\renewcommand{\sffamily}{\sfhira@pre\sfhiraj@pre}
\renewcommand{\mcfamily}{\mchira@pre\mchiraj@pre}
\renewcommand{\gtfamily}{\gthira@pre\gthiraj@pre}
\renewcommand{\mgfamily}{\mghira@pre\mghiraj@pre}
\makeatother
%%%


\usepackage{hyperref} 
\hypersetup{
  luatex, pdfencoding=auto, 
  colorlinks=true,
  linkcolor=black,     
  citecolor=black,     
  urlcolor=DeepSkyBlue3,      
  pdfborder={0 0 0}, 
}

\colorlet{grayLight}{white!80!black} 

\NewTCBListing{SourceCode}{ m m !o !O{DeepSkyBlue3} }{%
  enhanced, colback=black!70, colframe=Snow4,
  toptitle=-1mm, bottomtitle=-1mm,
  righttitle=-1mm, lefttitle=-1mm,
  arc=.5mm, 
  title={\tcbox[on line, arc=.5mm, boxsep=0pt, boxrule=0pt, top=1mm, bottom=0.8mm, left=2mm, right=2.2mm, colback=gray!80, coltext=white]{\raisebox{-0.1ex}{\vphantom{羅}\vphantom{j}#1}}},fonttitle=\gtfamily\footnotesize,boxrule=0.8pt,
  breakable,before upper={\color{white}},top=-0.5mm,bottom=-0.5mm,
  after title=\IfNoValueTF{#3}{}{{\hfill\tcbox[on line, arc=.5mm, boxsep=0pt, boxrule=0pt, top=1mm, bottom=0.8mm, left=2mm, right=2.2mm, colback=white!80!black, coltext=#4]{\raisebox{-0.1ex}{\vphantom{羅}\vphantom{j}#3}}}},
  listing only,
  listing options={
    language={#2},
    basicstyle=\ttfamily,
    keywordstyle=\ttfamily\color{white},
    stringstyle=\itshape\color{white},
    commentstyle=\small\gtfamily\color{DeepSkyBlue2},
    showspaces=false,showtabs=false,
    breaklines=true,breakindent=0pt,
    showstringspaces=false,
    columns=fullflexible,
    tabsize=2,
    numbers=left,numbersep=1.5pt,
    numberstyle=\scriptsize\gtfamily\color{gray},
  }
}

\NewTColorBox{OutPut}{ m !o !O{DeepSkyBlue3} }{%
  enhanced, colframe=Snow4,
  toptitle=-1mm, bottomtitle=-1mm,
  righttitle=-1mm, lefttitle=-1mm,
  arc=.5mm, colback=white, 
  title={\tcbox[on line, arc=.5mm, boxsep=0pt, boxrule=0pt, top=1mm, bottom=0.8mm, left=2mm, right=2.2mm, colback=gray!40, coltext=DeepSkyBlue3]{\raisebox{-0.1ex}{\vphantom{羅}\vphantom{j}#1}}},fonttitle=\gtfamily\footnotesize,boxrule=0.8pt,
  breakable,top=-0.5mm,bottom=-0.5mm,
  after title=\IfNoValueTF{#2}{}{{\hfill\tcbox[on line, arc=.5mm, boxsep=0pt, boxrule=0pt, top=1mm, bottom=0.8mm, left=2mm, right=2.2mm, colback=white!80!black, coltext=#3]{\raisebox{-0.1ex}{\vphantom{羅}\vphantom{j}#2}}}}, bottom=2mm, top=2mm, 
}


\title{\texttt{modernruler} Package Documentation}
\author{Kosei Kawaguchi a.k.a. KKTeX}
\date{Version 2.2.0 (2026/05/19)}

\begin{document}
\begin{titlepage}
  \maketitle
\end{titlepage}
\newpage
\tableofcontents
\newpage

\section{Outline}
This package provides modern hrule (\KKverb|\mruleth|), vrule (\KKverb|\mruletv|), and \undernote*{\KKverb|\undernote|}{Used like this!\\ It is the main function provided by this package.} internally uses the two commands.

\begin{SourceCode}{Intput}{TeX}
  % normal rule
  \mruleth[height=1pt, width=5cm, color=blue]

  % dashed rule
  \mruleth[height=2pt, width=8cm, color=red, dash=true, dash-len=5pt, gap-len=3pt]

  % inline rule
  This is \mruletv[height=\zw, depth=1.5\zw, width=1pt, color=green] a modern vrule.

  % inline dashed rule
  This is \mruletv[height=2\zw, width=1.5pt, color=orange, dash=true, dash-len=2pt, gap-len=1pt] a dashed modern vrule.

  % undernote
  This is under note. This uses \undernote{these commands}{\texttt{\textbackslash mruleh} and \texttt{\textbackslash mrulev}} internally and enables make flexible outputs.
\end{SourceCode}
\begin{OutPut}{Output}
  % normal rule
  \mruleth[height=1pt, width=5cm, color=blue]

  % dashed rule
  \mruleth[height=2pt, width=8cm, color=red, dash=true, dash-len=5pt, gap-len=3pt]

  % inline rule
  This is \mruletv[height=\zw, depth=1.5\zw, width=1pt, color=green] a modern vrule.

  % inline dashed rule
  This is \mruletv[height=2\zw, width=1.5pt, color=orange, dash=true, dash-len=2pt, gap-len=1pt] a dashed modern vrule.

  % undernote
  This is under note. This uses \undernote{these commands}{\texttt{\textbackslash mruleh} and \texttt{\textbackslash mrulev}} internally and enables make flexible outputs.
\end{OutPut}

\section{Acknowledgements / Credits}
This package was inspired by discussions on TeX Forum concerning
undernote-like constructions using rules.

An improved approach was later presented by Mr.~Yusuke~Terada,
which clarified several implementation details.

The present package is a complete reimplementation and extension,
introducing a generalized rule-based engine, redesigned control flow,
and additional features such as modern ruler integration and
\texttt{tcolorbox}-based abstractions.

Any remaining errors or design decisions are entirely the
responsibility of the author.

\section{Note}
\textbf{This package only supports LuaLaTeX.}

In this package, a unit \verb|\zw| is used in many parts. It is Japanese standard unit, but it's not normal outside of Japan. When you encounter \verb|\zw| in documemntations, please understand it as \verb|1em|. In detail, \verb|\zw| and \verb|1em| is differnt when you use Japanese characters. But only when you use alphabetic characters and numbers, the difference doesn't matter. 

\section{Installation}
\begin{SourceCode}{Intput}{TeX}
  \usepackage[<options>]{modernruler}
\end{SourceCode}

Detailed information regarding the options will be provided in a later section, specifically during the explanation of the \verb|\undernote| command.

\section{Commands}
\subsection{\texttt{\textbackslash mruleth, \textbackslash mruletv}}
\subsubsection{Basic Usage}
In the first place, \verb|\mruleth| and \verb|mruletv| are extended \verb|\hrule| and \verb|\vrule|. You can use them like this:

\begin{SourceCode}{Intput}{TeX}
  \mruleth[<keyvaloptions>]
  \mruletv[<keyvaloptions>]
\end{SourceCode}

These commands share the same keys.\bigskip

\begin{center}
  \begin{tabular}{llll}
    \toprule
    \textbf{Key} & \textbf{Type} & \textbf{Default} & \textbf{Description} \\ \midrule
    width & dim & 0pt & Width of the rule \\
    height & dim & 0pt & Height above the baseline \\
    depth & dim & 0pt & Depth below the baseline \\
    color & tl & black & Color of the rule \\
    gap-color & tl & white & Color of the gap segments \\
    dash & bool & false & Enables dashed line if true \\
    dash-len & dim & 3pt & Length of the dash segment \\
    gap-len & dim & 2.5pt & Length of the gap between dashes \\
    \bottomrule
  \end{tabular}
\end{center}\bigskip

The outputs are as follows:

\begin{SourceCode}{Intput}{TeX}
  \fboxsep=0pt\fboxrule=.1pt%

  % horizontal rule
  \fbox{\mruleth[height=1pt, width=55pt, color=blue]}
  \fbox{\mruleth[height=1pt, width=55pt, color=blue, dash=true]}
  \fbox{\mruleth[height=1pt, width=57pt, color=blue, dash=true]}
  \fbox{\mruleth[height=1pt, width=59pt, color=blue, dash=true]}

  % vertical rule
  \fbox{\mruletv[width=1pt, height=55pt, color=blue]}
  \fbox{\mruletv[width=1pt, height=55pt, color=blue, dash=true]}
  \fbox{\mruletv[width=1pt, height=57pt, color=blue, dash=true]}
  \fbox{\mruletv[width=1pt, height=59pt, color=blue, dash=true]}\bigskip

  % Horizontal: Alternating Black and Cyan segments
  \mruleth[width=120pt, height=2pt, dash=true, dash-len=6pt, gap-len=6pt, color=black, gap-color=cyan]\bigskip

  % Vertical: Warning Pattern (Yellow and Black)
  \mruletv[width=3pt, height=50pt, dash=true, dash-len=8pt, gap-len=4pt, color=yellow, gap-color=black]
\end{SourceCode}

\begin{OutPut}{Output}
  \fboxsep=0pt\fboxrule=.1pt%
  
  \fbox{\mruleth[height=1pt, width=55pt, color=blue]}
  \fbox{\mruleth[height=1pt, width=55pt, color=blue, dash=true]}
  \fbox{\mruleth[height=1pt, width=57pt, color=blue, dash=true]}
  \fbox{\mruleth[height=1pt, width=59pt, color=blue, dash=true]}

  \fbox{\mruletv[width=1pt, height=55pt, color=blue]}
  \fbox{\mruletv[width=1pt, height=55pt, color=blue, dash=true]}
  \fbox{\mruletv[width=1pt, height=57pt, color=blue, dash=true]}
  \fbox{\mruletv[width=1pt, height=59pt, color=blue, dash=true]}

  \bigskip

  % Horizontal: Alternating Black and Cyan segments
  \mruleth[width=120pt, height=2pt, dash=true, dash-len=6pt, gap-len=6pt, color=black, gap-color=cyan]

  \bigskip

  % Vertical: Warning Pattern (Yellow and Black)
  \mruletv[width=3pt, height=50pt, dash=true, dash-len=8pt, gap-len=4pt, color=yellow, gap-color=black]
\end{OutPut}

\subsubsection{Advanced usage: Use Like Phantom}
By setting the width to zero, these commands can be used as "phantoms" that provide arbitrary height and depth. 
In a traditional way to set a phantom, you use \verb|\vphantom| or \verb|\hphantom|. How ever, the total-height or width depends on the argument. So, I recommend you to use the modern-rulers as a flexible phantom.

\begin{SourceCode}{Intput}{TeX}
  % To visualize
  \fboxrule=.1pt\fboxsep=0pt 

  % modern-vphantom
  abc\fbox{\mruleth[height=2em, depth=.5em, width=0pt]def}ghi

  % modern-hphantom
  jkl\fbox{\mruletv[height=0pt, width=2em]mno\mruletv[height=0pt, width=1em]}pqr
\end{SourceCode}

\begin{OutPut}{Output}
  % To visualize
  \fboxrule=.1pt\fboxsep=0pt 

  % modern-vphantom
  abc\fbox{\mruleth[height=2em, depth=.5em, width=0pt]def}ghi

  % modern-hphantom
  jkl\fbox{\mruletv[height=0pt, width=2em]mno\mruletv[height=0pt, width=1em]}pqr
\end{OutPut}

\subsection{\texttt{\textbackslash undernote}}
\subsubsection{Basic Usage}
This commands provides underlined \undernote{annotation}{Like this.}. There is some optional parameters which adjust the position of the annotation text.

\begin{SourceCode}{Intput}{TeX}
  % grammar
  \undernote<star option>[<number of lines to shift the note downward>]{<the target phrase>}{<annotation>}

  % example
  In this single paragraph, we deliberately place many annotated terms to
  stress-test the undernote mechanism, starting with a
  \undernote{concept}{A brief explanation of the main concept}
  that appears early in the line, followed closely by another\\
  \undernote{idea}{A slightly longer explanatory note that is expected to
  interact with nearby notes} to encourage horizontal overlap detection.
  As the sentence continues, we insert a fixed-level annotation such as
  \undernote[2]{method}{This note is forced onto the second vertical level}
  to verify that manual level assignment overrides automatic stacking,
  and later a short
  \undernote{term}{Short note}
  next to a much longer
  \undernote*{expression}{This is a considerably longer explanatory note
  designed to increase the occupied width and push subsequent notes
  downward in the vertical stacking algorithm}.
  Near the end of the paragraph, we add one more fixed example,
  \undernote[3]{result}{A third-level note used to confirm deep stacking},
  followed immediately by an automatic one,
  \undernote*{observation}{This final note should be placed at a safe
  vertical distance determined by the collision analysis performed
  during the previous compilation run}.
\end{SourceCode}

\begin{OutPut}{Output}
  In this single paragraph, we deliberately place many annotated terms to
  stress-test the undernote mechanism, starting with a
  \undernote{concept}{A brief explanation of the main concept}
  that appears early in the line, followed closely by another\\
  \undernote{idea}{A slightly longer explanatory note that is expected to
  interact with nearby notes} to encourage horizontal overlap detection.
  As the sentence continues, we insert a fixed-level annotation such as
  \undernote{method}{This note is forced onto the second vertical level}
  to verify that manual level assignment overrides automatic stacking,
  and later a short
  \undernote[2]{term}{Short note}
  next to a much longer
  \undernote*{expression}{This is a considerably longer explanatory note
  designed to increase the occupied width and push subsequent notes
  downward in the vertical stacking algorithm}.
  Near the end of the paragraph, we add one more fixed example,
  \undernote*{result}{A third-level note used to confirm deep stacking},
  followed immediately by an automatic one,
  \undernote*{observation}{This final note should be placed at a safe
  vertical distance determined by the collision analysis performed
  during the previous compilation run}.
\end{OutPut}

As the example above shows, the star option puts the annotation text in a parabox. So when you include a long description in the fourth argument of the \verb|\undernote|, the option is the best way to avoid overflow.

Regarding the second argument, ``number of lines to shift the note downward'' is always determined automatically if you don't specify it. I recommend using this option only when annotations are too close to each other.

Of course, this package provides some package options for adjustments.\bigskip

\begin{center}
  \begin{tabular}{lllp{.4\linewidth}}
    \toprule
    \textbf{Key} & \textbf{Type} & \textbf{Default} & \textbf{Description} \\ \midrule
    notesize          & tl   & \KKverb|\footnotesize|& Font size of the note text \\
    notepos           & dim  & 3mm           & Minimum vertical length of the line to the note \\
    noteshift         & dim  & 4mm           & Vertical shift amount per level for overlapping notes \\
    noterulethickness & dim  & \KKverb|.07\zw|        & Thickness of the rule used in the note \\
    noterulehshift    & dim  & 1.5mm         & Horizontal offset of the vertical line from the underline start \\
    noterulehsize     & dim  & 1.5mm         & Length of the horizontal line extending to the note \\
    notesep           & dim  & 0em           & Minimum horizontal distance to prevent note overlap \\
    noteoverhang      & dim  & 5em           & Extension length of the note parbox (starred version) \\
    noteparstyle      & int  & 0             & Border style (0: none, 1: solid, 2: dashed) \\
    notelinecolor     & color & black        & Color of the the underline and the vertical line \\
    \bottomrule
  \end{tabular}
\end{center}\bigskip

When you want to change some settings in the middle of the document, you can use \verb|\SetUNote|. 
It takes a keyvalue-style options like this:

\begin{SourceCode}{Intput}{TeX}
  \SetUNote[noteparstyle=1, notelinecolor=blue]

  LaTeX is a \undernote{versatile}{Abundant package that can be used for free.} typesetting system \undernote*{that excels at producing high-quality documents}{I think LaTeX is the most flexibly customizable typesetting software.}, especially those containing complex mathematical formulas or technical structures. 
\end{SourceCode}


\begin{OutPut}{Output}
  \SetUNote[noteparstyle=1, notelinecolor=blue]

  LaTeX is a \undernote{versatile}{Abundant package that can be used for free.} typesetting system \undernote*{that excels at producing high-quality documents}{I think LaTeX is the most flexibly customizable typesetting software.}, especially those containing complex mathematical formulas or technical structures. 
\end{OutPut}

These are all the keys provided for it.\bigskip

\begin{center}
  \begin{tabular}{lllp{.4\linewidth}}
    \toprule
    \textbf{Key} & \textbf{Type} & \textbf{Default} & \textbf{Description} \\ \midrule
    \texttt{notesize}          & tl   & \KKverb|\footnotesize| & Font size of the note text. \\
    \texttt{notepos}           & dim  & ---           & Minimum vertical length of the line connecting to the note. \\
    \texttt{noteshift}         & dim  & ---           & Vertical shift amount per level for overlapping notes. \\
    \texttt{noterulethickness} & dim  & ---           & Thickness of the rules used in the note structure. \\
    \texttt{noterulehshift}    & dim  & ---           & Horizontal offset of the vertical line from the start of the underline. \\
    \texttt{noterulehsize}     & dim  & ---           & Length of the horizontal line extending towards the note. \\
    \texttt{notesep}           & dim  & ---           & Minimum horizontal distance to prevent overlap between notes. \\
    \texttt{noteoverhang}      & dim  & ---           & Extra horizontal extension for the note's parbox (used in starred version). \\
    \texttt{noteparstyle}      & int  & 0             & Border style for the note (0: none, 1: solid, 2: dashed). \\
    \texttt{notelinecolor}     & color & black        & Color of the underline and the connected vertical lines. \\
    \bottomrule
  \end{tabular}
\end{center}\bigskip

\subsubsection{Additional Description}

You can use the command in mathmode.

\begin{SourceCode}{Intput}{TeX}
  \[
    \undernote {%
      a + b
    }{In the equation envriomnemt.}
    -
    \undernote*{%
      x^5 + 4x^3 + \int_{c}^{\frac{d}{e}}\sum_{k=1}^{n} {}_n\mathrm{C}_k x^k + 12
    }{Even the argument includes an expression with large depth, they doesn't overlap the other texts.} 
    = \undernote{\frac{a}{b+\frac{x}{6}}}{No problem.}
  \]
\end{SourceCode}

\begin{OutPut}{Output}
  \[
    \undernote {%
      a + b
    }{In the equation envriomnemt.}
    -
    \undernote*{%
      x^5 + 4x^3 + \int_{c}^{\frac{d}{e}}\sum_{k=1}^{n} {}_n\mathrm{C}_k x^k + 12
    }{Even the argument includes an expression with large depth, they doesn't overlap the other texts.} 
    = \undernote{\frac{a}{b+\frac{x}{6}}}{No problem.}
  \]
\end{OutPut}

\section{License}
Released under the MIT License.

\section{Version History}
\begin{itemize}
  \item \textbf{v1.0.0--1.1.0} --- Initial public release, and add a fallback for \verb|\zw| and \verb|\ltjgetparameter|.
  \item \textbf{v1.3.1 (2026/01/26)} --- Fixed a bug which occurs when \verb|\undernote| command is used in mathmode. The bug was caused my misreplacement of \verb|\@elt|.
  \item \textbf{v2.1.5 (2026/02/06)} --- In this update, I made changes in the following two points:
    \begin{itemize}
      \item Fixed a bug where the arguments of the \verb|\undernote| with large depth caused text overlap. 
      \item Modernized the internal implementation by migrating from TeX primitives to the expl3 framework.
    \end{itemize}
  \item \textbf{v2.1.6 (2026/02/07)} --- Fixed a bug which occurs when \verb|noteparstyle| is set to ``2''. Also, added an error message to warn users when an invalid \verb|noteparstyle| is provided.
  \item \textbf{v2.1.7 (2026/05/18)} --- Internal refactor with no user-facing behavior changes:
    \begin{itemize}
      \item Deduplicated the \verb|noteparstyle| dispatch logic, which was previously written in two places that needed to stay in sync.
      \item Factored shared dash-rendering code between \verb|\mruleth| and \verb|\mruletv| through a common loop and segment emitters.
      \item Unified \verb|\FramedBox| and \verb|\DashedBox| internals and extracted the shared \verb|\parbox| body used by the underlying wrap commands.
      \item Migrated further from TeX primitives to the expl3 framework (\verb|\def| → \verb|\cs_set:Npn|, \verb|\let| → \verb|\cs_set_eq:NN|, \verb|\ifnum| → \verb|\int_case:nnF|, etc.), and removed unused declarations.
    \end{itemize}
  \item \textbf{v2.2.0 (2026/05/19)} --- Further internal refactor with no user-facing behavior changes:
    \begin{itemize}
      \item Replaced primitive scratch registers (\verb|\dimen@|, \verb|\count@|, \verb|\@tempcnt[ab]|, \verb|\@tempdim[ab]|) with semantically named private \verb|\l__modernruler_*| variables.
      \item Rewrote \verb|\undernote|, \verb|\@text@undernote|, \verb|\undernotedata@internal|, \verb|\@check@undernotedata@split[@]|, and \verb|\@check@undernotedata@elt| in expl3 style (\verb|\def| → \verb|\cs_new_protected:Npn|, \verb|\ifmmode| → \verb|\mode_if_math:TF|, \verb|\leavevmode| → \verb|\mode_leave_vertical:|, \verb|\hbox| → \verb|\hbox:n|, \verb|\vtop| → \verb|\vbox_top:n|, etc.).
      \item Collapsed the \verb|\cs_set:Npx \l_tmpa_tl { \write\@auxout{...} } \l_tmpa_tl| idiom for \verb|.aux| writes into a single \verb|\iow_shipout:Nx|.
      \item Converted \verb|\@UNDATA@yfuzz| into a \verb|\dim_const:Nn| constant.
    \end{itemize}
\end{itemize}
\end{document}