%!TEX program = SpiX
%%%%
%%%% minted + python pygments (required)
%%%%
%$ cluttex -e xelatex -shell-escape -synctex=1 --package-support=minted $texname
%%%$ latexmk -c $texname && rm -f $basename.listing && rm -rf _minted-$basename/
\documentclass[a4paper,11pt,itemph,footnote]{oblivoir}

\usepackage{fapapersize}
\setmarginnotes{10pt}{2.2in}{12pt}
\usefapapersize{*,*,1in,*,1in,*}

%\setmainfont{Minion Pro}
%\setkomainfont[KoPubBatang ](Light)(Bold)[][KoPubBatang ](Light)(Bold)
\setmainfont{Noto Serif Light}
\setkomainfont[Noto Serif CJK KR]( Light)( Medium)
\setmonofont{Noto Sans Mono CJK KR Regular}[Scale=.9]
\setkormonofont{Noto Sans CJK KR Regular}[Scale=.9,FakeStretch=1.08,RawFeature={+hwid}]
\setmonohanjafont{Noto Sans Mono CJK KR Regular}[Scale=.9]
\newfontfamily\fallbackhanjafont{Noto Sans CJK KR}

\usepackage{xcolor,graphicx}
\hypersetup{colorlinks}
\usepackage{jiwonlipsum}
\usepackage{kotex-logo}

\usepackage[normalem]{ulem} 
\usepackage{etoolbox}
\robustify{\uline}
\robustify{\uuline}
\usepackage{ksruby}
\usepackage{hnja2hngl}
\grrubystyle{default}

%\makeindex

\makeatletter
\let\atonum\@onum
\makeatother

\ExplSyntaxOn
\NewDocumentCommand \mycmd { s m }
{
%	\tl_if_head_eq_charcode:nNTF { #1 } \
%	{
%		\texttt { \tl_to_str:n { #1 } } \unskip 
%	}
%	{
%		\cnm{\textit { #1 }} 
%	} 
	\IfBooleanTF { #1 }
	{
		\texttt { \textbackslash #2 }
		\index{Command!\textbackslash #2 }
	}
	{
		\cnm{\textit { #2 } }
	}
}

\NewDocumentCommand \pkg { m }
{
	\textsf { #1 }
	\index{Package!#1}
}

\NewDocumentCommand \opt { m }
{
	\textit { #1 }
	\index{Option!#1}
}

\NewDocumentCommand \wi { m }
{
	#1\index{#1}
}

\ExplSyntaxOff 

\usepackage[most]{tcolorbox}
\tcbuselibrary{minted}
\newtcblisting{myexam}[1][\empty]{
	breakable,
	listing engine=minted,
	minted style=emacs,
	\ifx\empty#1\else#1\fi}

\usepackage{relsize}

\begin{document}

\title{hnja2hngl: 한자음 달기 \\ {\smaller[2] for \XeLaTeX}}
\author{nova de hi}
\date{\hnjahnglpkgdate, \hnjahnglpkgversion}

\maketitle

\let\origrwhanja=\rwhanja
\let\rwhanja=\grrwhanja
\let\rw=\rwhanja
\pagestyle{hangul}

\begin{abstract}
\rwhanja{漢字}로 \rwhanja{入力}된 텍스트에 \rwhanja{對}하여 \rwhanja{對應}하는 한글 \rwhanja{音}을 붙여준다.
이 패키지가 \rw{作成}된 \rw{事緣}은 KTUG의 \href{http://www.ktug.org/xe/index.php?document_srl=204761&mid=KTUG_open_board}{\rw{揭示物}}을 보아라.
``故로 文之不工함은 非\ruby{텍}{\TeX}之罪也라.''

2021년 9월에, 패키지의 새로운 버전을 작성하였다. 한자음 읽기 루틴을 전면적으로 완전히
새로 작성하였기 때문에 내부적으로는 동일한 패키지라 말할 수 없게 되었으나, 사용자 명령은
계승하고 있다. 한자음 데이터베이스는 약 2만 7천자까지 확대되어 BMP 평면의 모든 한자를
포함하게 되었다.
\end{abstract}

\tableofcontents*

\section{패키지}

이 패키지가 의도하는 바는, 입력은 오직 한자로만 하되 ``웬만한 한자음은 자동으로 달아주고 (그 자동으로 달아준 음이 좀 이상하면) 원하는 음을 붙일 수 있도록 하자''는 것이다.

문서의 Preamble에 다음과 같이 선언한다.

\begin{tcblisting}{listing style=tcblatex,listing only}
\usepackage{hnja2hngl}
\end{tcblisting}
이 패키지는 \XeTeX-\ko 에서만 사용할 수 있다.
\LuaLaTeX 이라면 \pkg{readhanja} 패키지를 쓰도록 하라.

이 패키지는 \pkg{grruby}를 디폴트로 불러온다. 만약 어떤 이유에선가
\pkg{grruby}를 로드하지 않으려면 
\begin{verbatim}
\usepackage[grruby=false]{hnja2hngl}
\end{verbatim}
과 같이 \verb|[grruby=false]| 옵션을 부여한다. 이에 대하여는
\ref{sec:grruby}절을 보라.

\section{명령 요약}

이 패키지가 제공하는 명령의 요약이다. 이후 절에서 상세히 설명한다.

\begin{enumerate}[\expandafter\atonum1] \oblivoirlist
\item \mycmd*{readhanja} 한자 한 글자의 음을 식자. \ref{sec:basic}절. \readhanja{安}
\item \mycmd*{readhanjaword} 한자 한 단어의 음을 식자. \ref{sec:basic}절. \readhanjaword{安寧}
\item  \mycmd*{rwhanja} 한자와 한글을 괄호로 묶어 식자. \ref{sec:basic}절. \rwhanja{安寧}
\item \mycmd*{grrwhanja} \pkg{grruby} 방식으로 \mycmd*{rwhanja}를 식자. \ref{sec:basic}절. \grrwhanja{安寧} 
\item \mycmd*{rwhanjachar} 한자의 글자마다 음을 붙이는 방식으로 식자. \ref{sec:everyhanja}절. \rwhanjachar{安寧} 
\item \mycmd*{rpRead} 인자로 지정된 부호까지 한자의 음을 붙여 문단을 식자. \ref{sec:rpread}절.
\item \mycmd*{viewCodePoint} 인자로 주어진 문자의 코드포인트 식자. \ref{sec:codepoint}절. \viewCodePoint{寧}
\item \mycmd*{showReadings} 한자음 데이터베이스에 등록된 음을 모두 식자. \ref{sec:showreadings}절. \showReadings{安寧}
\end{enumerate}

\section{한자로 입력된 글자와 단어의 독음}\label{sec:basic}

\paragraph{\mycmd*{readhanja} 명령}
인자로 주어진 한자 \wi{한 글자의 독음}을 식자한다. 인자로 두 글자 이상이 올 수 없다.

\begin{myexam}[]
\readhanja{漢}
\end{myexam}

\paragraph{\mycmd*{readhanjaword} 명령}
인자로 두 자 이상이 올 수 있다. 인자 중에 온 스페이스는 무시되고
\wi{한자 음을 한글로 출력}한다.
\begin{myexam}[]
\readhanjaword{漢字 植字}
\end{myexam}

\let\rwhanja=\origrwhanja
\paragraph{\mycmd*{rwhanja} 명령}
\mycmd*{readhanjaword}와 같으나 ``한글(漢字)'' 형식으로 식자한다.
이 패키지의 중심 명령이다.
\begin{myexam}[]
\rwhanja{漢字植字}
\end{myexam}

\paragraph{\mycmd*{grrwhanja} 명령}

이 패키지는 \pkg{grruby}를 로드하는 것이 디폴트이다.
\mycmd*{grrwhanja}라는 명령은
\pkg{grruby} 방식으로 \mycmd*{rwhanja}를 식자하라는 의미이다.
\begin{myexam}[]
\grrwhanja{漢字植字} \grrubystyle{progress}\grrwhanja{敎養}
\end{myexam}
\pkg{grruby} 패키지의 기능과 사용법은 패키지 문서(grruby-doc.pdf)를
참고하라.\footnote{\pkg{grruby}는 KTUG 사설저장소에서 \pkg{ksruby} 패키지를
	설치하면 함께 설치된다.}

\section{한자의 \protect\rwhanja{異音}}

\subsection{이음을 지정하는 옵션}

하나의 한자가 \wi{둘 이상의 음}으로 읽히는 경우는 대단히 많다. 
이 패키지가 활용하는 한자음 데이터베이스에도 \wi{둘 이상의 음}이 할당된 한자가 있다.
\rwhanja{異音}이 부여되어 있다면 그 각각을 `0', `1', `2', \obldots의 이음 선택 번호로 식별한다. 
만약 지정된 이음 선택 번호가 해당 문자에 할당된 이음의 개수보다 큰 수가 주어지면, 마지막 번호에
해당하는 음을 식자한다.

\mycmd*{readhanja}은 한 글자이므로 옵션인자처럼 이음선택번호를 부여한다.
\begin{myexam}[]
\readhanja{樂}[0] \readhanja{樂}[1] \readhanja{樂}[2] \readhanja{樂}[3]
\end{myexam}
\mycmd*{readhanjaword}와 \mycmd*{rwhanja}에서는 다른 음으로 읽어야 할
한자의 직후에 alternative 번호\index{이음 선택 번호}를 대괄호로 묶어 전달한다.
\begin{myexam}[]
\readhanjaword{樂[0]山} \readhanjaword{樂[1]山} \readhanjaword{樂[3]山}\\
\rwhanja{樂[0]山} \rwhanja{樂[1]山} \rwhanja{樂[3]山} \rwhanja{出必告[2]反必面}
\rwhanja{數數[1]} 
\end{myexam}

이음 지정 옵션에는 ``선택 번호''를 통한 방법 이외에, 직접 이음의 적어넣는 방법이 동작한다.
실용적으로는 이것이 더 쓸 기회가 많을 것이다.

\begin{myexam}[]
\readhanjaword{仁者樂[요]山} \rwhanja{在親[신]民} \rwhanja{出必告[곡]}

\end{myexam}

\subsection{`不'자의 독음}\index{不의 독음}

`不'은 다음 자음이 `ㄷ'이거나 `ㅈ'이면 `부'로, 그렇지 않으면 `불'로 읽는다.
그 다음 글자의 초성에 따라 \wi{독음이 시시때때로 변하는 글자}이다.
\rwhanja{不屈} \rwhanja{不讀書}.
이 독음을 자동화하였다. 

\begin{myexam}[]
\rwhanja{不斷} \rwhanja{不可} \rwhanja{不得不} \rwhanja{不知}
\end{myexam}

이음 선택을 명시적으로 지정한 경우에는 그것이 우선한다.

\begin{myexam}[]
\rwhanja{不㥁} \rwhanja{不[1]㥁} \rwhanja{不[비]㥁}
\end{myexam}

\subsection{첫소리법칙과 한자음}\label{sec:headrule}

\wi{첫소리법칙}(\wi{두음법칙})이 적용되는 한자음이 몇 있다. 예를 들면 落落長松은 ``낙락장송''으로 읽힌다.
이 패키지는 두음법칙을 반자동으로 강제하게 되어 있다. 즉, ``이음 선택 옵션''이 없다면, 무조건 필요할 때 두음법칙을 적용한다. 다만 한 글자를 식자하는 \verb|\readhanja|는 두음법칙을 적용하지
않는다.

\begin{myexam}[]
\readhanjaword{落落長松} \rwhanja{戀戀} \rwhanja{凜凜} \readhanja{凜}
\end{myexam}

\noindent
다음 예제는 두음법칙이 어떻게 작용하는가를 보여주는 예이다. 
\begin{myexam}[]
\rwhanja{龍[0]龍[1]龍[2]龍[3]} \rwhanja{飛龍} \rwhanja{龍山}
\end{myexam}

두 단어 이상이 결합한 합성어에서 \wi{첫소리법칙}을 분석하여 식자해주는 기능은 없다. 예컨대 
\rwhanja{民主}와 \rwhanja{理念}이 따로 각각의 단어일 때는 \wi{첫소리법칙}이 잘 적용되지만
`\readhanjaword{民主|理念}'으로 합쳐진 경우 이 때의 理에 \wi{첫소리법칙}이 적용되어야 하는 것을 이 패키지는 알지 못한다.

특정한 글자가 합성어의 첫글자이므로 첫소리법칙을 적용하라는 것을 알려주는 방법이 두 가지 마련되어 있다.
하나는 \wi{첫소리법칙}이 적용되어야 할 자리에 \verb+|+ (vertical bar)를 두는 것이다.
\begin{myexam}[]
\rwhanja{民主理念} \rwhanja{民主|理念} \readhanjaword{民主|理念}
\end{myexam}

다른 하나는 첫소리법칙을 적용하여야 할 글자의 ``이음 선택 옵션'' 위치에 해당 글자의 첫소리법칙에
해당하는 음운의 번호나 별표(\verb|*|)를 붙이는 것이다.
\begin{myexam}[]
\readhanjaword{民主理[*]念} \rwhanja{民主理[1]念} \rwhanja{民主理[*]念}.
\end{myexam}
\noindent 이 부호를 별표로 한 이유는 해당 글자의 첫소리법칙을 적용한 음운의 ``이음 선택 번호''가 몇 번인가를 고민할 필요가 없게 하기 위해서였다.

그런데, \mycmd*{rpRead}의 맥락(\ref{sec:rpread}절)에서는 vertical bar를 이용하는 방법은 
사용할 수 없고, 별표(*)를 이용하는 방법만이 허용된다는 점에 주의하여야 한다.

\subsection{임의의 한자음}\label{sec:force}

\rwhanja{率}과 같은 글자는 \wi{첫소리법칙}에만 영향을 받는 것이 아니라 앞글자의 끝소리가
모음이거나 `ㄴ'이면 `율'로 그밖의 경우에는 `률'로 적어야 한다.\footnote{%
	참고로 `\viewCodePoint{率}'이 첫소리 자리에 와서 `율'로 읽어야 하는 경우는 거의 없다.
	그런 까닭에 이 패키지는 率이 첫소리 자리에 오면 
	이음 선택 옵션이 없는 한 무조건 `솔'로 읽으며,
	기본음(0)은 `율'로 되어 있다. `률'을 얻어야 한다면 `2'로 접근할 수 있다.
	한편, 호환한자 영역의 \viewCodePoint{率}자는 첫소리 자리에서도 `\readhanja{率}'이고
	기본음도 `\readhanja{率}'이다.
}
이러한 복잡한 음운변환을 모두 자동화하는 것은 불가능하다고 보인다.
또한 문맥에 따라 특정 한자가 전혀 의외의 음으로 읽히는 경우마저 있으므로
이럴 경우에 대비하여 강제로 음을 할당할 수 있도록 하였다. 이음선택번호를 
써넣는 위치에 아예 독음을 써주는 것이다.
이 방법으로 부여되는 독음은 해당 단어에서 효력이 있다.
\begin{myexam}[]
\rwhanja{率先} \rwhanja{率[0]先}
\readhanja{率}[률] \rwhanja{比率} \rwhanja{統率[솔]} \rwhanja{確率[률]}
\end{myexam}

\subsection{한자음의 설정}\label{sec:assign}

패키지의 한자음 데이터베이스가 한자음을 제공하지 않으면 컴파일 과정에서
에러가 발생한다. 무시하고 컴파일하면 결과는 나타나지 않는다.

\begin{tcblisting}{listing style=tcblatex,listing only}
\rwhanja{𠆤}
\end{tcblisting}
\noindent 이것은 에러를 보일 것인데, \viewCodePoint*{𠆤}자가 데이터베이스에 들어 있지 않기 때문이다.
현재 이 패키지는 2만 7천자 가량의 한자 정보를 제공한다. 이것은 BMP 평면의 모든 한자를 포함하는
것이다. 따라서 에러가 발생한다는 것은 BMP 평면의 한자 범위를 넘어서서 사용하고 있다는 의미이다.

이 때에는 이 글자의 독법을 알려주어야 한다. 
\mycmd*{AssignReading}이 이를 위한 명령이다.
다음과 같이 사용한다.
\begin{tcblisting}{listing style=tcblatex,listing only}
\AssignReading{𠆤}{정}
\end{tcblisting}

이 명령은 지역적(local) 영향을 미친다. 즉 현재 범위(그룹)를 빠져나가면 무효화된다.

이를 이용하여 등록되지 않거나 임의의 방법으로 읽어야 하는 한자음을 구현할 수 있다.

\begin{myexam}[]
\AssignReading{𠆤}{정} \rwhanja{𠆤}
\end{myexam}

\paragraph{rpSetReading}
두 글자 이상의 음을 할당하려 하는 경우 \mycmd*{rpSetReading} 명령을 쓸 수 있다.
이것은 \mycmd*{AssignReading}을 반복 사용하는 것과 같다. 
다음은 의도적으로 이상한 음을 붙여본 것이다. (여기서 보는 대로, 이렇게 강제 할당한
음이 `ㄷ', `ㅈ' 계통이라도 그 앞의 不가 자동으로 `부'가 되지 않는다.)
\begin{myexam}[]
\rpSetReading{㥘=캅,鋋=옌,悳=뜩} \rwhanja{勇㥘} \rwhanja{弓矛戈鋋} \rwhanja{不悳}
\end{myexam}

\subsection{호환한자 관련 이슈}

\wi{첫소리법칙}의 경우는 위와 같이 하여 어떻게든 피해간다 하더라도
한 단어 안에서 같은 글자를 서로 다른 음으로 읽어야 할 때가 있다.

소위 `\wi{한중일 호환한자}'([U+F900]--[U+FAD9]) 영역의 글자를 이용하면
이런 경우에 대응할 방법이 있기는 하다.
즉 예를 들어보자면 \viewCodePoint{不}자(한중일 통합한자)와
\viewCodePoint{不}\allowbreak 자(\wi{한중일 호환한자})를 구분하여 입력하는 것이다.
적어도 KS X 1001에 중복 등록되어 있는 한자는 이 영역에서 발견할 수 있다.
\begin{myexam}[]
\rwhanja{不得不}
\end{myexam}
이 패키지에서는 \viewCodePoint{不}자에 대하여 `부/불'의 자동 교체가 적용되고 호환한자일 때는 
단순히 `불'로만 적힌다.

그렇기는 하지만 이를 구분하여 입력할 방법도 마땅치않고(이를 구분하여 입력하게 해주는 입력기를
본 적이 없다) 또 다른 텍스트 프로세서들과의 호환성을
염두에 둔다면 현실적으로 쉽지 않은 일이다.

\section{확장}

\subsection{\protect\mycmd*{rpRead}}\label{sec:rpread}

글자마다 한글 음을 붙이는 것이 아니라 단어 단위로 하고 싶을 때
단어마다 마크업을 붙여야 한다. 이것이 귀찮은 관계로 한 문장, 또는 한 단락
전체에 대하여 자동으로 단어별로 처리하게 해주면 좋을 것이다.
이를 위하여 \mycmd*{rpRead}가 정의되어 있다.

\begin{myexam}[]
\rpRead{period} 單語마다 讀音이 붙도록 하면 便利하다.
\end{myexam}

이 명령은 하나의 인자를 취하는데 이 때 올 수 있는 인자는 \texttt{period, comma, para, at} 네
가지이다. 각각 마침표가 있는 데까지, 쉼표가 있는 데까지, 문단 구분(\verb|\par|나 두 줄의 공행)이 있는 데까지,
at-기호(@)가 있는 데까지
한자로 시작하는 단어의 한자 부분만 독음을 붙여 식자해준다.

한자 식자는 항상 \mycmd*{rwhanja}를 이용하므로 이 명령을 \mycmd*{grrwhanja}로
바꾸어놓고 \pkg{grruby} 방식의 결과를 얻을 수 있다.

만약 주어진 텍스트의 종지를 나타내는 부호(인자로 주어진 것)를
발견하지 못하면 에러를 토한다.

\begin{myexam}[]
\let\rwhanja=\grrwhanja
\rpRead{comma} 終止符나 休止符를 境界文字로 설정해두면 그 位置까지,
漢字를 自動으로 植字한다.
\end{myexam}

\wi{수동으로 독음을 할당}해야 할 수 있는데 이를 위하여
옵션 인자를 쓸 수 있다. 이 독음의 할당은 \mycmd*{AssignReading}과 마찬가지
효과를 갖는다. \mycmd*{rpSetReading}과 같은 방식이지만 옵션 인자로 준다는 점에 주의.

\begin{myexam}[]
\rpRead{at}[度=탁,告=곡] 度支 出必告反必面@
\end{myexam}

이음 선택 번호 또는 강제 이음을 할당하는 방법으로 입력하여도 된다.
그리고 \ref{sec:headrule}절에서 설명한 대로 단어 중간에
첫소리법칙을 적용하여야 할 때에는 이음 선택 옵션 위치에 별표를 쓸 수 있다.

\begin{myexam}[]
\let\rwhanja=\grrwhanja \grrubystyle{rup} \grrubycolor{red!80}
\rpRead{para}
悠久한 歷史와 傳統에 빛나는 우리 大韓國民은 3·1 運動으로 建立된
大韓民國臨[*]時政府의 法統과 不義에 抗拒한 4·19 民主理[1]念을 繼承하고

祖國의 民主改革과 平和的 統一의 使命에 立脚하여
\end{myexam}

\mycmd*{rpRead}를 사용할 때 주의해야 할 것이 있다. 
\begin{itemize} \firmlist
\item \mycmd*{rpRead}가 한자를 변형해서 식자하려고
의도하는 범위 내에는 \uline{어떤 매크로도 올 수 없다}. 오직 일반문자, 한글, 한자, 문장부호만이 올 수 있다.
개행기호 \verb|\\|같은 것도 오면 안 된다. \mycmd*{rpSetReading}이나 \mycmd*{AssignReading}도
매크로이기 때문에 \mycmd*{rpRead} 명령이 진행 중에 오면 안 된다. 
범위를 잘 설정하여 사용하여야 할 것이다. 
\item \mycmd*{rpRead} 다음에 빈 줄이 오면 효력이 없다. 문단 첫머리에 바로 써야 한다.
\item \mycmd*{rpRead}는 한 문단 이상을 식자하는 데 쓸 수 없다. \texttt{period}, \texttt{comma}, \texttt{at} 모두 현재 문단 안에서 해당 종지부호가 위치해야 한다. \texttt{para}는 그 문단 마지막에 \verb|\par|나 두 줄의 공행이 반드시 존재해야 한다.%
%\footnote{%
%	\texttt{\textbackslash everypar}를 이용하여 이어지는 여러 문단을 처리하는 것이
%	가능하기는 하나 이는 사용자에게 맡겨져 있다.}
\item 하나의 단어에서 한자 아닌 것이 나올 때까지를 \mycmd*{rwhanja}로 처리한다.
첫 글자가 한자가 아닌 단어이거나 한글 이후에 다시 한자가 나오는 입력, 예컨대 (띄어쓰기 없는) \texttt{漢字의入力}과 같은 경우에 한글 뒤에 나오는 한자는 변환되지 아니한다. 가운뎃점이나 다른 문장부호가 스페이스없이 단어를 구분하는 경우도 이와 마찬가지이다.
\item \ref{sec:headrule}절에서 지적한 바와 같이 합성어에서 단어 중에 두음법칙을 적용하여야
하는 글자에는 \verb|[*]|라는 이음 선택 옵션을 붙여야 한다. vertical bar를 이용한 구분은 동작하지
않는다.
\end{itemize}

\subsection{글자마다 독음 붙이기}\label{sec:everyhanja}

\mycmd*{rwhanjachar}라는 명령은 \mycmd*{rwhanja}와 같지만 독음이 글자
단위로 처리되도록 한 명령이다. 이를 이용하여 \wi{글자마다 독음}을 붙일 수 있다.
ruby 방식으로 한자음을 붙이려면
\pkg{grruby}가 제공하는 \texttt{grrubystyle}을 이용하여 다음과 같이
한다. 첫소리법칙도 동작하고 이음선택번호도 사용가능하다.
\begin{myexam}[]
\let\rwhanja=\rwhanjachar\grrubystyle{ruby}
\rwhanja{仁者樂[3]山}, \rwhanja{智者樂[3]水}.
\rpRead{at}[說=열] 學而時習之, 不亦說乎? 有朋自遠方來, 不亦樂[2]乎?@
\end{myexam}

만약 오른쪽 위에 독음을 붙이는 쪽이 좋다면,
\begin{myexam}[]
\let\rwhanja=\rwhanjachar\grrubystyle{rup}\grrubycolor{red!80}
\rwhanja{仁者樂[3]山}, \rwhanja{智者樂[3]水}.
\rpRead{at}學而時習之, 不亦說[2]乎? 有朋自遠方來, 不亦樂[2]乎?@
\end{myexam}

\section{기타}

\subsection{코드포인트}\label{sec:codepoint}

특정 문자의 \wi{유니코드 코드포인트}를 보여주는 명령 \mycmd*{viewCodePoint}가 정의되어 있다.
원래 \mycmd*{kHangulReading} 명령을 위해서 특정 문자의 코드포인트를 알아야 할 때 쓰려고
만든 것이다. 한자만이 아니라 원칙적으로 모든 문자에 대하여 동작한다.
\begin{myexam}[]
\viewCodePoint{法} \viewCodePoint{가} \viewCodePoint{は}
\end{myexam}

별표를 붙이면 16진수가 아닌 10진수로 표현한다. \viewCodePoint*{學}.

\subsection{등록된 한자음의 확인}\label{sec:showreadings}

%\begin{tcblisting}{listing style=tcblatex,listing only}
%\usepackage[draft]{hnja2hngl}
%\end{tcblisting}
%\opt{draft} 옵션은 김도현 교수의 readhanja\footnote{이 패키지와 사실상 같은
%기능을 하는 것이고 \LuaTeX 을 이용하는 것이다. \url{http://www.ktug.org/xe/index.php?mid=KTUG_open_board&document_srl=204761} 참조.}에서 영감을 얻어 작성하였다.
%기본 선택 글자를 박스쳐서 보여주며 순서대로 0, 1, 2, \ldots 순이다. 
\mycmd*{showReadings} 명령은 데이터베이스에 등록된 \wi{선택 가능한 음을 확인}하는 용도로 쓰기 위한 것으로 
사용법은 \mycmd*{rwhanja}와 비슷하다. 만약 이음 선택 번호가 부여되어 있다면 
해당하는 음에 박스를 쳐서 표시한다. 그렇지 않으면 첫 번째 음에 표지가 붙는다.
이음 선택 번호는 첫 글자부터 차례로 0, 1, 2, \obldots\ 순이다.
만약 강제로 할당된 음이 있다면 일단 등록된 음을 모두 보이고 끝에 강제로 할당된
음을 별표를 붙여 표시한다. 다음 용례를 보라.

\begin{myexam}[]
\showReadings{樂[2]說數親[신]}
\end{myexam}

\noindent 이 명령은 \texttt{[grruby=false]}라면 의도대로 동작하지 않을 수 있다.

%\mycmd*{hnjahngldrafton}과 \mycmd*{hnjahngldraftoff}로 이 기능을 끄거나 켤 수 있다.


\subsection{grruby}\label{sec:grruby}

다음 두 명령이 \pkg{grruby} 명령을 사용한다: \mycmd*{rwhanjachar},
\mycmd*{grrwhanja}.
그런데 \verb|[grruby=false]| 하였을 때는 어떠한 일이 일어나는가?
위의 두 명령은 단순히 \mycmd*{ruby}를 쓴 것과 똑같아진다.
\mycmd*{ruby} 명령은 이를 사용할 수 있도록 활성화되어 있어야 한다.
\pkg{luatexko}에는 자체 \mycmd*{ruby} 명령이 있으나 이 패키지를
사용하는 상황에서는 \pkg{ruby} 또는 \pkg{ksruby}를 미리 로드해두어야 할 것이다.

\texttt{[grruby=false]}일 때 다음 예문은 아래 그림과 같은 결과를 가져온다.
\begin{tcblisting}{listing style=tcblatex,listing only}
\let\rwhanja\rwhanjachar
\rpRead{at}
大學之道，在明明德，在親[신]民，在止於至善。
知止而后有定，定而后能靜，靜而后能安，安而后能慮，慮而后能得。
物有本末，事有終始。知所先後，則近道矣。@
\end{tcblisting}
\noindent\includegraphics[width=\textwidth]{rubyexample}

\subsection{문장부호의 문제}

이 패키지는 \viewCodePoint{|}, \viewCodePoint{@}, \viewCodePoint{[}, \viewCodePoint{]},
이상 네 개의 \wi{문자를 특별한 목적으로 사용}한다. 그러므로 이 문자들이 입력되는 텍스트에 포함되면 에러를 토할 수 있다.
문제가 될 법한 것은 \texttt{[}와 \texttt{]}인데 이 글자를 원래의 용도(괄호)로 사용하려 한다면
\viewCodePoint{［}와 \viewCodePoint{］}로 대용하든가(`ㄴ'+한자키 방식으로 입력할 수 있다)
``한자 입력 문자열'' 범위 밖에 두든가 해야 할 것이다.
\begin{myexam}[]
\rpRead{comma}題目을 깨뜨리고 나서［破題］ 다시 묶어주는 것은,
\end{myexam}

\subsection{문서에 사용된 모든 한자의 목록}

\fbox{v1.3}부터 (조금이라도 시간을 절약하기 위해) 한번 사용된 한자는
내부적으로 다시 사용하도록 설계하였다. 한 문서를 컴파일하면서 사용된
모든 한자의 목록을 \cs{PrintAllUsedHanja} 명령으로 인쇄할 수 있다.

\subsection{컴파일 시간에 대한 코멘트}

이 패키지로 다량의 한문 텍스트를 처리하려 할 때, 컴파일 시간이
소요될 수 있다. 이는 전적으로 데이터베이스 파일의 읽기와 관련된
시간으로서, 참지 못할 정도는 아닐 것이다. 1.3에서 새로 도입한
한자 캐시 기능이 조금이라도 도움이 되기를 기대한다.

\section{감사의 말}

이 패키지의 제작과 관련한 토론에서 Unihan 데이터베이스의 이용을 권해주시고
한자음 데이터베이스를 보충해주신 김도현 교수께 감사드린다.

[2021, version 1.0]
김도현 교수께서 \LuaTeX\ 용으로 만드신 \pkg{readhanja}로써 사실상 ``한자음
읽기'' 문제는 해결되었다고 생각하지만 이 패키지를 업데이트해두는 이유는 
혹시 \XeTeX\ 사용자 가운데 약간의 수요가 있을지도 모르기 때문이었다.
이 패키지의 한자음 데이터베이스는 \pkg{readhanja}의 것을 수정하여 사용하였다.

\section{변경이력}

\noindent\textbullet\ 2023/02/27, v1.3: \cs{PrintAllUsedHanja} \par
\noindent\textbullet\ 2021/09/25, v1.2: \verb|\showReadings|. \par
\noindent\textbullet\ 2021/09/25, v1.1: 두음법칙 개선 \par
\noindent\textbullet\ 2021/09/25, v1.0: 핵심 루틴을 새로 작성함. \XeTeX 만 지원.

\medskip

\noindent\textbullet\ 2015/05/15, v0.9: draft의 표시방법 변경 \par\noindent
%\textbullet\ 2015/05/14, v0.8: 不의 독음 자동 선택 \par\noindent
%\textbullet\ 2015/05/13, v0.7: 한자음 선택방법 변경, draft 옵션 \par\noindent
%\textbullet\ 2015/05/13, v0.6: \LuaTeX-\ko\ 지원 \par\noindent
%\textbullet\ 2015/05/11, v0.5: 패키지 옵션 \texttt{[dry]} 추가. \par\noindent
\textbullet\ 2015/05/10, v0.4: 첫소리법칙 적용 \par \noindent
\textbullet\ 2015/05/10, v0.3: 한자음 데이터베이스 부분 수정.\par\noindent
\textbullet\ 2015/05/09, v0.2: 쉼표가 사라지는 버그 수정.

%\newpage

\section{예문}

연암의 \grrwhanja{騷壇赤幟引}을 예문으로 하여 \grrubystyle{progress}\grrwhanja{植字例}를 보이겠다.

\bigskip

\noindent (1) \mycmd*{rwhanjachar}로 루비: 두음법칙, 이음선택 등이 가능하다.

\begin{myexam}[]
\let\rwhanja=\rwhanjachar\grrubystyle{ruby}
\rpRead{at} [則=즉,金=금]
善爲文者, 其知兵乎? 字譬則士也; 意譬則將也; 題目者, 敵國也; 
掌故者, 戰場墟壘也; 束字爲句, 團句成章, 猶隊伍行陣也;
韻以聲之, 詞以耀之, 猶金鼓旌旗也; 照應者, 烽埈也; 
譬喩者, 遊騎也;@
\end{myexam}

\noindent (2) 한자와 한글의 자리바꿈 (\pkg{grruby}에 의존)

\begin{myexam}[]
\let\rwhanja=\rwhanjachar\grrubystyle{ruby}\grexpos
\rpRead{at}
抑揚反復者, 鏖戰撕[시]殺也; 破題而結束者, 先登而擒敵也; 
貴含蓄者, 不禽二毛也; 有餘音者, 振旅而凱旋也.@
\end{myexam}

\noindent (3) \mycmd*{rpRead}를 이용하여 문단 전체를 식자

\begin{myexam}[]
\grrubystyle{default}\grrubycolor{gray!80}
\let\rwhanja=\grrwhanja
\rpRead{para}[則=즉]
夫長平之卒, 其勇㥘非異於昔時也, 弓矛戈鋋, 其利鈍非變於前日也, 
然而 廉頗將之, 則足以制勝, 趙括代之, 則足以自坑. 
故善爲兵者, 無可棄之卒, 善爲文者, 無可擇之字. 苟得其將, 則鉏耰棘矜, 盡化勁悍,
而 裂幅揭竿, 頓[2]新精彩矣. 苟得其理, 則家人常談, 猶列學官, 而童謳里諺, 亦屬爾雅矣.
故文之不工, 非字之罪也.\par
\end{myexam}


\noindent (4) 단어마다 \mycmd*{rwhanja} 마크업: 이 예문과 같은 한문 장문은
이런 식 입력이 피곤해보이는데, 미리 에디터나 도큐멘트 프로세싱을 통해 
소스 수준에서 처리하여 들여오는 것이 좋을 것이다. 
한자가 단어 정도 수준에서 조금 사용되는 일반적인 한글 문서라면
응당 이 방법을 쓰는 것이 좋다.

\begin{myexam}[]
\rwhanja{彼評字句之雅俗}, \rwhanja{論篇章之高下者}, % 論은 두음법칙으로 `논'
\rwhanja{皆不識合變之機}, \rwhanja{而制勝之權者也}. \rwhanja{譬如不勇之將},
\rwhanja{心無定策}, \rwhanja{猝然臨[*]題}, % 臨을 `임'으로 읽음
\rwhanja{屹如堅城}, \rwhanja{眼前之筆墨}, \rwhanja{先挫於山上之草木},
\rwhanja{而胸裏之記誦}, \rwhanja{已化爲沙中之猿鶴矣}. \rwhanja{故爲文者},
\rwhanja{其患常在乎自迷蹊逕}, \rwhanja{未得要領}.
\end{myexam}

\noindent (5) 범위.
 중괄호로 둘러싼 문단에 rpRead하였으므로 다음 문단에서는 `則'이
 `즉'으로 읽어지지 않는다. 한자음 할당의 효력이 미치는 범위를 테스트하기
 위한 것으로 일부러 잘못 읽은 글자가 있다.

\begin{myexam}[]
{\rpRead{period}[則=즉]
夫蹊逕之不明, 則一字難下, 而常病其遲澁; 要領之未得, 則周匝雖密, 而猶患其疎漏,
譬如陰陵失道, 而名騅不逝, 剛車重圍, 而六[*]騾已遁矣.}
\rpRead{period}苟能單辭而挈領, 如雪夜之入蔡, 片言而抽綮, 如三鼓而奪關.
\underline{\rwhanja{則爲文之道},} \rwhanja{如此而至矣}.
\end{myexam}

\noindent (6) 한글 토가 붙은 경우

\begin{myexam}[]
\let\rwhanja=\grrwhanja \grrubystyle{default}\grrubycolor{gray!90}
\rpRead{para}[則=즉]
友人 李仲存이 集東人古今科軆하여 彙爲十卷하고 名之曰騷壇赤幟라 하다.
嗚呼라! 此皆得勝之兵이요 而百戰之餘也라. 
雖其軆格不同하고 精粗雜進이언정 而各有勝籌니 攻無堅城이라.
其銛鋒利刃이 森如武庫하여 趨時制敵함이 動合兵機로다.
繼此로 而爲文者가 率此道也한댄 定遠之飛食이요 燕然之勒[*]銘이니 其在是歟여 其在是歟여!
雖然이나 房琯之車戰이 效跡於前人이로되 而敗하고 虞詡之增竈가 反機於古法이로되 而勝하니
則所以合變之權은 其又在時요 而不在法也니라.\par
\end{myexam}

\end{document}

