% !TEX TS-program = arara
% arara: xelatex: { shell: yes, synctex: yes }

\documentclass[a4paper]{oblivoir}

\usepackage{fapapersize}
\usefapapersize{*,*,1in,*,1in,*}

\setkomainfont[Noto Serif CJK KR]()( Bold)
\setmainfont{Noto Serif}
\setmonofont{Monaco}[Scale=.9]

\usepackage{xcolor}
\usepackage{ksruby}

\usepackage{tcolorbox}
\tcbuselibrary{minted,breakable}

\ExplSyntaxOn

\makeatletter
%\int_new:N \l_parnum_int
\newcounter{parnumcnt}

\NewDocumentCommand \numpar { }
{
%	\int_incr:N \l_parnum_int
%	\tl_set:Nf \@currentlabel{\use:c {p@parnum}\int_use:N \l_parnum_int}	
	\bigskip
		
	\noindent
	\refstepcounter{parnumcnt}
	\ifxetex
	\XeTeXLinkBox {
		\makebox[2em][l]{\bfseries \theparnumcnt .}
	}
	\else
		\makebox[2em][l]{\bfseries \theparnumcnt .}
	\fi	
}


\makeatother
\ExplSyntaxOff

\def\pkg#1{\textsf{#1}}

\begin{document}

\title{\texttt{ksruby} 패키지}
\author{Noname}
\date{2025/02/07, v0.0.4}

\maketitle
\firmlists

\numpar 
\XeLaTeX 에서, 한글 문서에 루비 문자(또는 그 아류)를 쓰려 할 적에 현재까지 CJK의 \pkg{ruby} 패키지에 의존해왔다. 몇 가지 마음에 들지 않는 것이 있어서 새로 만들기로 하고 이를 테스트한다. \pkg{luatexko}에는 이미 \verb|\ruby| 명령이 따로 존재하므로 주로 \pkg{xetexko}와 함께 쓰기 위함이다.

\numpar
패키지는 다음과 같이 로드한다.
\begin{tcblisting}{listing only}
\usepackage[<options>]{ksruby}
\end{tcblisting}
옵션은 다음과 같다.
\begin{itemize}
\item \texttt{rubysep=<dim>}. 기저 글자와 루비 글자 사이의 간격을 설정한다. 기본값은 \texttt{0pt}.
\item \texttt{rubysize=<size>}. 루비 글자의 상대적 크기를 지정한다. 배수이므로 단위 없이 적어야 한다. 기본값은  \texttt{0.55}.
\item \texttt{rubyeachchar=<true|false>}. 글자마다 루비를 다는 방식으로 식자한다. \ref{eachchar}번 문단에서 설명한다.
\item \texttt{rubywidth=<true|false>}. 기저 문자와 루비 문자의 폭이 다를 때 루비 문자의 폭을 설정하는 방법을 지정한다. 기본값은 \texttt{false}. \ref{rubywidth}번 문단에서 설명한다. [v0.0.2]
\item \texttt{rubyheight=<true|false>}. 루비 문자 박스의 높이를 0으로 만든다. \ref{rubyheight}번 문단에서 설명한다. [v0.0.3]
\item \texttt{rubycenter=<c|l|r>}. 루비 문자를 기저 문자에 대하여 어떤 식으로 정렬할지를 결정한다. 기본값은 \textit{c}\texttt{enter}.
\end{itemize}

\numpar
기본 명령은 \verb|\ksruby|이다. 다른 루비 패키지를 로드하지 않았다면 \verb|\ruby| 명령을 변형으로서 쓸 수 있다.
두 개의 인자를 취하며 \verb|#1|이 기저 문자이고 \verb|#2|가 루비 문자이다.
\begin{tcblisting}{listing side text}
\ksruby{루비}{ruby}
\ruby{선언}{宣言}
\end{tcblisting}
만약 CJK의 \pkg{ruby} 패키지를 미리 로드하였거나 \pkg{luatexko}가 작동하고 있다면 그 경우에 \verb|\ruby| 명령은 미리 로드한 정의를 따라간다. 이 때에 \verb|\ksruby|만이 이 패키지의 것이 된다.

\numpar
\verb|\ksruby*|와 같이 별표를 붙이면 글자마다 루비를 붙이는 방식으로 식자한다. 다만 이 때는 첫 번째 인자와 두 번째 인자의 글자수가 같아야 하며 만약 글자수가 다르면 별표를 붙이지 않은 것과 똑같이 식자한다.
\begin{tcblisting}{listing side text}
\ksruby*{선언}{宣言}
\ksruby*{루비}{ruby}
\end{tcblisting}

\numpar \label{eachchar}
패키지 옵션으로 \verb|[rubyeachchar]|가 선언되면 \verb|\ksruby| 명령은 별표를 붙이지 않아도 글자마다 식자하는 방식으로 변화한다.
문장 중에 \verb|\ksrubyeachchardefault| 명령을 주면 같은 일이 일어난다.
\begin{tcblisting}{listing side text}
\ksrubyeachchardefault
\ksruby{선언}{宣言}
\ksruby{루비}{ruby}
\end{tcblisting}
이 선언은 지역적(\emph{local})이므로 그룹 밖에까지 영향을 미치지 않는다. 만약 원래의 값으로 이를 되돌리려 한다면 \verb|\ksrubyeachchardefault[false]|라고 선언할 수 있다.\footnote{이 패키지에서 true, false를 인자로 주어야 할 때는 옵션 인자 형식으로 주도록 하였다.}
\begin{tcblisting}{listing side text}
\ksrubyeachchardefault[false]
\ksruby{선언}{宣言}
\ksruby{루비}{ruby}
\end{tcblisting}

\numpar
\verb|rubysep|과 \verb|rubysize|를 문서 중에서 바꿀 수 있다. 이 때에는 \verb|\ksrubysep|이나 \verb|\ksrubysize| 명령을 쓴다. \verb|\ksrubysize| 선언은 전역적(\emph{global})이고
\verb|\ksrubysep|은 지역적(\emph{local})이다.
\begin{tcblisting}{listing side text}
{\ksrubysep{5pt} \ruby{선언}{宣言}}
\ksrubysize{1}
\ruby{선언}{宣言}
\end{tcblisting}
\ksrubysize{.6}

\numpar 
세로쓰기에서도 원하는 대로 잘 나타남을 볼 수 있다. 다만 세로쓰기 시에는 \verb|rubysep|을 조금 조정해야
할 필요가 있을 수 있다.
\begin{tcblisting}{listing side text}
\begin{vertical}{10em}
\adhochangulfont{HCR Batang LVT}%
   [Renderer=OpenType,
    Vertical=Alternates,
    RawFeature=vertical]
\adhochanjafont{HCR Batang LVT}%
   [Renderer=OpenType,
    Vertical=Alternates,
    RawFeature=vertical]
\ksrubysep{-2pt}
\ruby{차}{此}를 \ruby*{선언}{宣言}함이며
\end{vertical}
\end{tcblisting}

\numpar 
\verb|\ksrubyextra|라는 특별한 명령이 있다. 이것은 루비 문자를 식자하기 시작하는 위치에 원하는 명령을 추가할 수 있게 하는 것이다. 주로 루비 텍스트의 색상을 지정하기 위해 쓸 수 있다.
\begin{tcblisting}{listing side text}
\ksrubyextra{\color{red}}
\ruby{선언}{宣言}
\end{tcblisting}
\noindent 만약 이 명령을 이용하여 루비 문자의 폰트를 바꾸려 한다면 \dotemph{선언형 폰트 명령}을 써야 한다.
\begin{tcblisting}{listing side text}
\ksrubyextra{\sffamily\bfseries}
\ruby{宣言}{선언}
\end{tcblisting}
인자로 주어진 명령의 효과는 루비 텍스트로 제한된다. 그러나 이 선언은 전역적이므로 원래 상태로 돌리기 위해서는 \verb|\ksrubyextra{}|를 선언해주어야 한다.

\ksrubyextra{}


\numpar 
CJK의 \pkg{ruby}보다 좋은 점이 있다면 이른바 ``행 간격 이슈''가 발생하지 않는다는 것이다. 
\begin{tcblisting}{listing side text,breakable}
\ksruby*{吾等}{오등}은 \ksruby*{玆}{자}에 \ksruby*{我}{아} \ksruby*{朝鮮}{조선}의 \ksruby*{獨立國}{독립국}임과 \ksruby*{朝鮮人}{조선인}의 \ksruby*{自主民}{자주민}임을 \ksruby*{宣言}{선언}하노라 
\end{tcblisting}
\begin{tcblisting}{listing side text,breakable}
\linespread{2.5}
\ksruby*{吾等}{오등}은 \ksruby*{玆}{자}에 \ksruby*{我}{아} \ksruby*{朝鮮}{조선}의 \ksruby*{獨立國}{독립국}임과 \ksruby*{朝鮮人}{조선인}의 \ksruby*{自主民}{자주민}임을 \ksruby*{宣言}{선언}하노라 
\end{tcblisting}

\numpar\label{rubywidth}
[v0.0.2] 기저 문자와 루비 문자의 폭이 다를 때 조판 방법을 결정하기 위하여 \verb|rubywidth|와 \verb|rubycenter| 옵션을 두었다. 문장 중에서 이를 변경하려면 \verb|\ksrubywidthdefault|와 \verb|\ksrubycenterdefault| 명령을 사용한다. 

\verb|\ksrubywidthdefault| 명령은 그 명령이 주어진 시점에서 지금까지의 조판 방식을 변경(toggle)한다. 다음 보기를 보면 쉽게 이해할 수 있을 것이다.
\begin{tcblisting}{listing side text}
이를 \ruby{ruby}{보석의 이름}라고 한다.\\
\ksrubywidthdefault
이를 \ruby{ruby}{보석의 이름}라고 한다.
\end{tcblisting}
\noindent 또는 명시적으로 옵션 인자를 주어 \texttt{true} 또는 \texttt{false}를 선언할 수 있다.
\verb|\ksrubywidthdefault[false]|. 기본값은 false이며 이 때는 긴 루비를 식자할 공간을 확보한다. 반면 이 값이 true이면 기저문자의 폭만을 유지한다. true일 때 가까이 있는 루비 문자가 충돌하여 겹쳐질 수 있으며 이는 사용자의 책임이다.
\begin{tcblisting}{listing side text}
\ksrubywidthdefault[true]
\ruby{루비}{보석의 이름} \ruby{dia}{금강석의 이름}\\
\ksrubywidthdefault[false]
\ruby{루비}{보석의 이름} \ruby{dia}{금강석의 이름}
\end{tcblisting}

\numpar\label{rubyheight}
[v0.0.3] \verb|rubyheight| 옵션을 주어 값을 \verb|true|로 하면 상단의 루비 문자를 식자하는 박스의 높이(height)가 무시된다. 명령으로서는 \verb|\ksrubyheightdefault|를 쓸 수 있고 옵션 인자 없이 쓰면 값을 변경(toggle)한다. \verb|[true]| 또는 \verb|[false]| 값을 옵션 인자로 주어서 강제할 수 있다. 기본값은 \verb|false|.
\begin{tcblisting}{listing side text}
\linespread{1.0}\ksrubysep{2pt}
\ksruby{確實}{확실}\par
\ksruby{確認}{확인}\par
\ksrubyheightdefault
\ksruby{確實}{확실}
\end{tcblisting}
이 옵션이 주어지면 위의 예에서 보듯이 루비 문자가 윗쪽 줄과 겹칠 수 있다. 즉 루비 문자를 위한 수직 공간을 자동으로 확보하지 않게 하는 것이다. 행간격이 아주 중요한 특별한 상황에서 쓰게 만든 것이며 일반적으로 이 옵션은 필요없다.


\numpar
[v0.0.2] \verb|rubycenter| 옵션으로는 \verb|c|, \verb|l|, \verb|r| 셋 중의 하나를 줄 수 있다.
각각 center, left, right를 의미하고 루비 문자를 식자하는 기저 문자에 대한 상대적 정렬 위치를 표시한다.
일반적으로 center면 충분할 것이고, 그것이 당연히 default이다. 그러나 루비 텍스트가 길 경우에 가끔 필요할 수 있다.

문장 중에서는 \verb|\ksrubycenterdefault|명령을 쓴다. 인자 없이 쓰면 center를 강제한다. l이나 r일 때는 (옵션 인자가 아니라) \verb|\ksrubycenterdefault{l}|과 같이 명령하여야 한다.\footnote{여기서는 true, false 형 인자가 아니기 때문에 중괄호를 쓴다.}
\begin{tcblisting}{listing side text}
\ksrubycenterdefault{l}
우리 \ruby{루비}{고양이 이름}는
\ksrubycenterdefault{r}
\ruby{루비}{보석 이름}와 완전히 다른
\ksrubycenterdefault
\ruby{색}{color}이다.
\end{tcblisting}

\numpar
일본어의 루비를 이 패키지로 완전히 구현하지 않았다. 이 패키지는 주로 한글 문서를 위한 것이다. 
일본어 문서의 루비에 대한 표준은 \href{https://www.w3.org/TR/jlreq/#ruby_and_emphasis_dots}{Requirements for Japanese Text Layout}에 있는데 이를 구현하는 것은 일본어 텍의 일이 아니겠는가.

\numpar 
행나눔에 관한 메모. \verb|\ksruby| 명령은 기저문자를 박스로 식자하고 그 위에 루비문자를 역시 박스로 올려붙이는 것이므로 이 명령이 적용되는 단어에서는 행나눔이 일어나지 아니한다.
그러나 \verb|\ksruby*| 즉 \verb|rubyeachchar|가 활성화되어 있는 상태에서는 글자마다 박스로 식자하므로 글자 끝에서 행나눔이 일어날 수 있다.

%%%%

\numpar
변경사항: 
\begin{enumerate}
\item v0.0.1에서 현재 식자되고 있는 폰트 크기를 자동으로 알아내어서 거기에 맞추어 루비 문자를 찍도록 하는 기능을 추가하였다.
\begin{tcblisting}{listing side text}
\small \ruby{發達}{발달}
\normalsize \ruby{發達}{발달}
\large \ruby{發達}{발달}
\Large \ruby{發達}{발달}
\LARGE \ruby{發達}{발달}
\end{tcblisting}

\item v0.0.2에서 \texttt{rubywidth}와 \texttt{rubycenter} 관련 명령과 옵션을 추가하였다.
\end{enumerate}

\newpage

\begin{tcblisting}{listing above text}
\ksrubyeachchardefault
\ksrubyextra{\color{blue!50!gray}}
\ruby{噫}{희}라! \ruby{舊來}{구래}의 \ruby{抑鬱}{억울}을 \ruby{宣暢}{선창}하려 하면,
\ruby{時下}{시하}의 \ruby{苦痛}{고통}을 \ruby{擺脫}{파탈}하려 하면,
\ruby{將來}{장래}의 \ruby{脅威}{협위}를 \ruby{芟除}{삼제}하려 하면,
\ruby{民族的良心}{민족적량심}과 \ruby{國家的廉義}{국가적염의}의 \ruby{壓縮銷殘}{압축소잔}을 \ruby{興奮伸張}{흥분신장}하려 하면,
\ruby{各個人格}{각개인격}의 \ruby{正當}{정당}한 \ruby{發達}{발달}을 \ruby{遂}{수}하려 하면,
\ruby{可憐}{가련}한 \ruby{子弟}{자제}에게 \ruby{苦恥的財産}{고치적재산}을 \ruby{遺與}{유여}치 안이하려 하면,
\ruby{子子孫孫}{자자손손}의 \ruby{永久完全}{영구완전}한 \ruby{慶福}{경복}을 \ruby{導迎}{도영}하려 하면,
\ruby{最大急務}{최대급무}가 \ruby{民族的獨立}{민족적독립}을 \ruby{確實}{확실}케 함이니,
\ruby{二千萬各個}{이천만각개}가 \ruby{人}{인}마다 \ruby{方寸}{방촌}의 \ruby{刃}{인}을 \ruby{懷}{회}하고
\ruby{人類通性}{인류통승}과 \ruby{時代良心}{시대량심}이 \ruby{正義}{정의}의 \ruby{軍}{군}과 \ruby{人道}{인도}의 \ruby{干戈}{간과}로써 \ruby{護援}{호원}하는 \ruby{今日}{금일},
\ruby{吾人}{오인}은 \ruby{進}{진}하야 \ruby{取}{취}하매 \ruby{何强}{하강}을 \ruby{挫}{좌}치 못하랴, \ruby{退}{퇴}하야 \ruby{作}{작}하매 \ruby{何志}{하지}를 \ruby{展}{전}치 못하랴.
\end{tcblisting}

\end{document}
