\documentclass[a4paper]{article}
\usepackage[scale=0.8]{geometry}
\usepackage{setspace}
\usepackage{pxrubrica}
\newcommand*{\vb}{\symbol{`\|}}
\newcommand*{\Opt}[1]{\texttt{#1}}
\newcommand*{\PKN}[1]{\textsf{#1}}
\newcommand*{\Eg}{E.\,g.\mbox{}}
\newcommand*{\eg}{e.\,g.\mbox{}}
\newcommand*{\ie}{i.\,e.\mbox{}}
\newcommand*{\myfileversion}{1.3d}
\newcommand*{\myfiledate}{2021/03/06}
\newsavebox{\myexample}
\begin{document}

\title{The \PKN{pxrubrica} package}
\author{Takayuki YATO\quad (aka ``ZR'')}
\date{v\myfileversion \quad[\myfiledate]}
\maketitle

\setstretch{1.5}

\section{Package Loading}

There is no options available.

\begin{quote}\small\begin{verbatim}
\usepackage{pxrubrica}
\end{verbatim}\end{quote}

\section{Basic Usage}

\subsection{Very Basic}

\begin{itemize}
\item Mono ruby (\Opt{m} option): one ruby block per one kanji.\\
\Eg\quad
\verb+\ruby[m]{$BBk(B}{$B$?$+(B}+ $\rightarrow$ \ruby[m]{$BBk(B}{$B$?$+(B}\quad
\verb+\ruby[m]{$Brt(B}{$B$&$0$$$9(B}+ $\rightarrow$ \ruby[m]{$Brt(B}{$B$&$0$$$9(B}
\item Group ruby (\Opt{g} option): one ruby block per kanji sequence.\\
\Eg\quad
\verb+\ruby[g]{$B1@?}(B}{$B$R$P$j(B}+ $\rightarrow$ \ruby[g]{$B1@?}(B}{$B$R$P$j(B}\quad
\verb+\ruby[g]{$BITG!5"(B}{$B$[$H$H$.$9(B}+ $\rightarrow$ \ruby[g]{$BITG!5"(B}{$B$[$H$H$.$9(B}
\item Jukugo ruby (\Opt{j} option): one ruby block per kanji, but read as whole.\\
\Eg\quad
\verb+\ruby[j]{$B9&?}(B}{$B$/(B|$B$8$c$/(B}+ $\rightarrow$ \ruby[j]{$B9&?}(B}{$B$/(B|$B$8$c$/(B}\quad
\verb+\ruby[j]{$B<7LLD;(B}{$B$7$A(B|$B$a$s(B|$B$A$g$&(B}+ $\rightarrow$ \ruby[j]{$B<7LLD;(B}{$B$7$A(B|$B$a$s(B|$B$A$g$&(B}\\
The current implementation uses the following strategy:
if none of the ruby string per a kanji causes protrusion,
then the whole is typeset as mono-ruby;
otherwise, the whole is typeset as group-ruby,
ignoring the ruby grouping.

\item A \verb+|+ symbol in a ruby string denotes the boundary of reading for each kanji
(\ie\ $B9&(B = $B$/(B and $B?}(B = $B$8$c$/(B).
It is not needed in group ruby.
\item Comparison of typeset results:
\begin{quote}\begin{tabular}{ll@{\ }l@{\ }c*3{@{\quad}c}}
Mono & (\verb+\ruby[m]{$B>.H7(B}{$B$3(B|$B$P$H(B}+) & $\rightarrow$
  & \ruby[m]{$B>.H7(B}{$B$3(B|$B$P$H(B}
  & \ruby[m]{$Bs5ry(B}{$B$;$-(B|$B$l$$(B}
  & \ruby[m]{$BMkD;(B}{$B$i$$(B|$B$A$g$&(B}
  & \ruby[m]{$B1m(B}{$B$D$P$a(B}
\\
Group & (\verb+\ruby[g]{$B>.H7(B}{$B$3$P$H(B}+) & $\rightarrow$
  & \ruby[g]{$B>.H7(B}{$B$3$P$H(B}
  & \ruby[g]{$Bs5ry(B}{$B$;$-$l$$(B}
  & \ruby[g]{$BMkD;(B}{$B$i$$$A$g$&(B}
  & \ruby[g]{$B1m(B}{$B$D$P$a(B}
\\
Jukugo & (\verb+\ruby[j]{$B>.H7(B}{$B$3(B|$B$P$H(B}+) & $\rightarrow$
  & \ruby[j]{$B>.H7(B}{$B$3(B|$B$P$H(B}
  & \ruby[j]{$Bs5ry(B}{$B$;$-(B|$B$l$$(B}
  & \ruby[j]{$BMkD;(B}{$B$i$$(B|$B$A$g$&(B}
  & \ruby[j]{$B1m(B}{$B$D$P$a(B}
\end{tabular}\end{quote}
Usually When a jukugo has per-character reading then jukugo ruby
(\Opt{j}) is preferred, otherwise (\Opt{g}) is.
If you particularly intend to show the per-character reading
for a jukugo, you might use the \Opt{m} option.
Note that all of \Opt{m}, \Opt{g} and \Opt{j} lead to
the same result for ruby to a single kanji.
\item You can give a default value of option
using the \verb+\rubysetup+ command;
\verb+\rubysetup{g}\ruby{$B737\(B}{$B$7$c$b(B}+ is
equivalent to \verb+\ruby[g]{$B737\(B}{$B$7$c$b(B}+.
The ``default of default'' is \Opt{|cjPeF|}.
\end{itemize}

\subsection{Intrusion/Protrusion}

\begin{itemize}
\item Control of ruby intrusion:
\begin{center}\begin{tabular}{ll@{\ }l@{\ }c*2{@{\quad}c}}
No intrusion & \verb+$B$3$N(B\ruby[|-|]{$Bs'(B}{$B$+$5$5$.(B}$B$N(B+ & $\rightarrow$
 & $B$3$N(B\ruby[|-|]{$Bs'(B}{$B$+$5$5$.(B}$B$N(B
 & $B$3$N(B\ruby[|-|]{$BsA(B}{$B$3$&$N$H$j(B}$B$N(B
 & $B$3$N(B\ruby[|-|]{$B1-(B}{$B$&(B}$B$N(B
\\
Small intrusion & \verb+$B$3$N(B\ruby[(-)]{$Bs'(B}{$B$+$5$5$.(B}$B$N(B+ & $\rightarrow$
 & $B$3$N(B\ruby[(-)]{$Bs'(B}{$B$+$5$5$.(B}$B$N(B
 & $B$3$N(B\ruby[(-)]{$BsA(B}{$B$3$&$N$H$j(B}$B$N(B
 & $B$3$N(B\ruby[(-)]{$B1-(B}{$B$&(B}$B$N(B
\\
Big intrusion & \verb+$B$3$N(B\ruby[<->]{$Bs'(B}{$B$+$5$5$.(B}$B$N(B+ & $\rightarrow$
 & $B$3$N(B\ruby[<->]{$Bs'(B}{$B$+$5$5$.(B}$B$N(B
 & $B$3$N(B\ruby[<->]{$BsA(B}{$B$3$&$N$H$j(B}$B$N(B
 & $B$3$N(B\ruby[<->]{$B1-(B}{$B$&(B}$B$N(B
\end{tabular}\end{center}
\item If you require ``ruby output may intrude to kana but not to kanji,''
then you might want to do ``\verb+$B$3$N(B\ruby[<-|]{$Bs'(B}{$B$+$5$5$.(B}$BEy(B+''
to get ``$B$3$N(B\ruby[<-|]{$Bs'(B}{$B$+$5$5$.(B}$BEy(B.''
\item To specify a basic mode (\Opt{m}/\Opt{g}/\Opt{j})
and intrusion at a time, you can use option strings
such as \Opt{|g|} and \Opt{|m>}.
In fact, the symbol \Opt{-} works as placeholder
for basic mode and means the use of default value.
\item Control of ruby protrusion:
the string \Opt{||} supresses the protrusion.
\begin{quote}
\begin{lrbox}{\myexample}
\small$\leftarrow$ \verb+\ruby[||->]{$B?}(B}{$B$9$:$a(B}+
\end{lrbox}
\fbox{\parbox{.42\linewidth}{%
\ruby[||->]{$B?}(B}{$B$9$:$a(B}$B$N!D(B
\quad \usebox{\myexample}%
\rule{0pt}{12pt}\\
$B%$%s%3$N(B
}}\quad vs.\quad
\begin{lrbox}{\myexample}
\small$\leftarrow$ \verb+\ruby[|->]{$B?}(B}{$B$9$:$a(B}+
\end{lrbox}
\fbox{\parbox{.42\linewidth}{%
\ruby[|->]{$B?}(B}{$B$9$:$a(B}$B$N!D(B
\quad \usebox{\myexample}%
\rule{0pt}{12pt}\\
$B%$%s%3$N(B
}}
\end{quote}
\end{itemize}

\subsection{More Commands}

\begin{itemize}
\item \verb+\aruby+: attaches ruby to an alphabet (non-CJK) string.
\par\noindent\Eg\quad
\verb+\aruby{Get out}{$B%2%i%&%C(B}!+ $\rightarrow$
  \aruby{Get out}{$B%2%i%&%C(B}!
\item \verb+\rubyfontsetup+: specifies the font used for ruby output.
For example, when you want to attach mincho-font ruby
to gothic-font kanji string you can do as follows:
\par\noindent
{\small
\verb+\rubyfontsetup{\mcfamily}$B$3$N(B{\gtfamily \ruby[j]{$BL@D+BN(B}{$B$_$s(B|$B$A$g$&(B|$B$?$$(B}}+}
$\rightarrow$
{\rubyfontsetup{\mcfamily}$B$3$N(B{\gtfamily \ruby[j]{$BL@D+BN(B}{$B$_$s(B|$B$A$g$&(B|$B$?$$(B}}}
\end{itemize}

\end{document}
