\DocumentMetadata{}
\documentclass{ltxdoc}

\usepackage{tabularx, booktabs}
\usepackage[hangul]{kotex}

\linespread{1.6}
\settowidth\parindent{가}
\renewcommand\contentsname{차례}


\title{\textsf{varioref}, \textsf{hyperref}, \textsf{cleveref} 패키지의 한국어화\thanks{각 패키지의 최종 수정일은 2024년 3월 31일이며, 버전은 1.0이다.}}
\author{강우현\thanks{\texttt{kangwh.2003@gmail.com}}}
\date{2024년 9월 27일}


\begin{document}

\maketitle

\tableofcontents

\section{소개}

\textsf{varioref}~패키지의 |\vref|, \textsf{hyperref}~패키지의 |\autoref|, \textsf{cleveref}~패키지의 |\cref|~제어 문자열은 상호 참조한 대상의 번호 앞뒤에 `section'이나 `page' 등의 문구를 붙여 주는 기능을 제공한다. 이때, 각 패키지는 문서의 언어에 맞추어 문구의 내용을 변경해 주는데, 세 패키지 모두 한국어는 지원하지 않는다. 따라서 한국어 문서에서도 각 패키지를 쉽게 사용할 수 있도록 \textsf{varioref-korean}, \textsf{hyperref-korean}, \textsf{cleveref-korean}~패키지를 작성하였다.

이 패키지가 없더라도 사용자는 |\setlabel|, |\crefname|, |\crefformat| 등 각 패키지가 제공하는 사용자화 제어 문자열을 통해 참조 문구를 직접 한국어화 할 수 있다. 하지만 여러 패키지를 함께 사용하는 경우에는 명령어 사이에 --- 특히 \textsf{varioref}~패키지와 \textsf{cleveref}~패키지를 함께 사용할 때 --- 충돌이 일어나기 쉬우며, |\autoref|~패키지는 작동 방식 상 한국어의 문법적 구조와 맞지 않는다. 따라서 필자가 작성한 세 가지 패키지는 이러한 불편함(과 귀찮음)을 해결해 줄 것이다.

\section{사용하기}

\subsection{설치하기}

세 패키지는 모두 KTUG 사설 저장소에 등록되어 있다.\footnote{세 패키지를 KTUG 사설 저장소에 등록해 주신 noname~님께 감사를 표한다. 관련 정보는 \href{http://www.ktug.org/xe/index.php?mid=KTUG_open_board&document_srl=270293}{여기}를 클릭하여 확인할 수 있다.}

KTUG 사설 저장소를 통해 패키지를 내려받는 것이 제한된다면, 저자의 \href{https://applemincho-latex.tistory.com/3}{티스토리 블로그}를 통해 내려받을 수도 있다. \texttt{sty}~파일을 내려받은 다음, 이를 \TeX~배포판이 설치된 폴더나 작업하는 파일과 같은 폴더에 저장하면 된다.

\subsection{불러오기}

일반적인 패키지처럼 |\usepackage|를 사용하여 패키지를 불러 오면 된다. 각 패키지는 모두 본래의 패키지를 자동으로 불러 온다. 패키지에 지정된 옵션은 (\textsf{varioref-korean}~패키지에서 |setlabel|을 제외하고) 모두 본래의 패키지에 전달된다.

예를 들어, \textsf{varioref-korean}~패키지를 사용한다면 일반적으로 다음과 같이 입력한다.

\begingroup
\linespread{}%
\begin{verbatim}
\usepackage[nospace, setlabel]{varioref-korean}
\end{verbatim}
\par
\endgroup

\noindent 특별한 상황이 아니라면, \textsf{varioref}~패키지를 사용할 때에는 |nospace|~옵션을 지정해 주는 것이 좋다.

또, 세 가지 패키지를 모두 함께 사용한다면 다음과 같이 입력하면 된다. (\textsf{cleveref}~패키지의 매뉴얼에 따르면 세 패키지는 꼭 이 순서대로 불러와야 한다.)

\begingroup
\linespread{}%
\begin{verbatim}
\usepackage[nospace]{varioref-korean}
\usepackage{hyperref-korean}
\usepackage{cleveref-korean}
\end{verbatim}
\par
\endgroup

특정 패키지는 한국어화 기능을 사용하지 않고 싶다면 이름에 `\textsf{-korean}'이 붙지 않은 본래의 패키지를 불러 오면 된다. 예를 들어, \textsf{hyperref}~패키지의 다른 기능은 모두 사용하되 |\autoref|는 사용하지 않는다면 \textsf{hyperref-korean}을 굳이 불러올 필요가 없으므로 다음과 같이 입력하면 된다.

\begingroup
\linespread{}%
\begin{verbatim}
\usepackage{hyperref}
\usepackage{cleveref-korean}
\end{verbatim}
\par
\endgroup


\subsection{\textsf{varioref-korean}~패키지의 기능}

\textsf{varioref-korean}~패키지는 |setlabel|~옵션을 제공한다. 이는 |\setlabel|~제어 문자열을 사용하여 상호 참조 대상의 번호 형식을 한국어화 하는 기능을 제공한다. 따라서 |\ref{chapter:1}|은 단순히 `1' 대신 `제1장'을, |\ref{footnote:3}|은 `3' 대신 `각주~3'을 출력한다.

일반적으로 한국어 문서에서 `표'나 `그림', `식' 등의 문구는 대상의 번호 앞에 붙는다. 따라서 |setlabel|~옵션을 사용하면 |\vref{table:4.8}| 등의 코드를 입력했을 때 `39쪽의 표~4.8'이라는 문구를 쉽게 얻을 수 있다. 그러나 |setlabel|~옵션을 사용하지 않는다면 같은 코드가 `39쪽의 4.8'을 조판하므로, 표의 번호 앞에 `표'라는 문구를 넣기 곤란해질 것이다.

추가로, \textsf{varioref-korean}~패키지는 |\UItrue|와 |\UIfalse|~제어 문자열을 제공한다.\footnote{이 제어 문자열은 \textsf{kotex-varioref}~패키지와 동일하다.} 이는 \textsf{kotex-varioref}~패키지와 동일한 역할을 한다. |\vref|를 사용했을 때 페이지 정보와 대상의 번호 사이에 `의'라는 조사를 넣을지 말지를 결정해 준다. |\UItrue|를 선언하면 조사~`의'가 출력되며, |\UIfalse|를 선언하면 조사~`의'가 출력되지 않는다.


\section{\textsf{kotex-varioref}와 \textsf{varioref-korean}의 차이}

두 패키지 모두 \textsf{varioref}~패키지의 기능을 한국어 문서에서도 자연스럽게 사용할 수 있도록 한다는 목적을 가지고 있지만, 몇 가지 차이점이 있다.

\begin{itemize}
    \item 본래 \textsf{varioref}~패키지는 같은 표현을 반복하여 사용하지 않는 기능을 제공한다. 예를 들어, |\vref|로 한 페이지 앞에 있는 대상을 여러 번 참조했을 때에는 `on the preceding page'와 `on the previous page'라는 표현이 돌아가며 사용된다. \textsf{kotex-varioref}~패키지는 --- 한국어 문서에서는 같은 표현을 반복하여 사용하는 것에 관대해서인지 모르겠지만 --- 이 기능을 무시하고, 항상 같은 표현을 사용하도록 되어 있다. \textsf{varioref-korean}~패키지는 본래의 동작과 비슷하게 `이전 쪽'과 `앞쪽'이라는 표현을 돌아가며 사용한다.
    \item 양면 편집 문서에서, \textsf{varioref}~패키지는 맞은편 페이지에 있는 대상을 참조하는 경우 `facing page'라는 표현을 함께 사용한다. \textsf{kotex-varioref}~패키지는 이 기능을 구현하지 않았으며, 단면 편집 문서를 작성할 때와 마찬가지로 `앞 페이지'와 `다음 페이지'라는 표현만을 사용한다. \textsf{varioref-korean}~패키지는 `옆쪽'과 (페이지 번호의 홀짝에 따라) `왼쪽 페이지', `오른쪽 페이지'라는 표현을 사용한다.
\end{itemize}


\section{주의 사항}

세 패키지를 사용할 때에는 다음 사항을 주의해야 한다.

\subsection{한글 조판 패키지}

세 패키지는 모두 \textsf{kotex}이나 \textsf{CJKutf8}, \textsf{polyglossia} 등 한국어 문서를 조판하기 위한 필수 패키지를 불러오지 않는다. 적절한 패키지를 불러오지 않는다면 --- 특히 레거시 엔진에서는 --- 한글 조판과 관련된 오류가 발생할 수 있다.

이 패키지가 \textsf{kotex} 등을 불러 오지 않는 것은 호환성과 범용성을 위해서이다. 세 패키지의 코드 모두 특정 한글 조판 패키지의 코드에 의존하지 않으므로, 또 어떤 한글 조판 패키지를 사용하든 이 패키지를 함께 사용할 수 있도록 하기 위해, \textsf{kotex} 등을 불러오는 코드를 넣지 않았다.

\subsection{\textsf{varioref-korean}~패키지의 \texttt{setspace}~옵션과 다른 패키지와의 호환성}

\textsf{varioref-korean}~패키지를 사용할 때, |setspace|~옵션을 사용하면 참조 문구의 한국어화를 |\setlabel|~제어 문자열을 통해 진행한다. 따라서
\begin{itemize}
    \item \textsf{hyperref}~패키지의 |\autoref| 등
    \item \textsf{cleveref}~패키지의 |\cref| 등
    \item \textsf{amsmath}~패키지의 |\eqref|
\end{itemize}
제어 문자열이 정상적으로 작동하지 않을 것이다. 만약 위의 제어 문자열을 문서에서 사용하려는 경우에는 \textsf{varioref-korean}~패키지를 불러올 때 |setspace|~옵션을 사용하지 않기를 권장한다.

\subsection{\textsf{cleveref}의 \texttt{poorman}~옵션}

현재 버전의 \textsf{cleveref-korean}~패키지는 \textsf{cleveref}~패키지의 |poorman|~옵션이 제대로 작동하는지 보장하지 않는다. 저자는 아직 이 기능에 대한 호환성을 확인하지 않았으므로, |poorman|~옵션을 지정한 후 \textsf{cleveref-korean}~패키지가 정상적인 것으로 보이는 결과물을 만들더라도 한 번 더 확인하기 바란다.\footnote{\textsf{cleveref}~패키지의 안내서에서도 이 기능은 완벽하지 않을 수 있다고 주의하고 있다.} 차후 버전의 \textsf{cleveref-korean}~패키지는 |poorman|~옵션을 지원하도록 개선할 계획이다.


\section{참고할 만한 글}

세 패키지는 저자가 `레이텍 입문부터 활용까지'라는 \LaTeX~가이드북을 만들면서 함께 작성한 것이다. 해당 책의 제15장에서는 번호 붙은 대상을 상호 참조할 때 함께 사용할 만한 패키지를 소개하는데, 이때 \textsf{varioref}, \textsf{hyperref}, \textsf{cleveref}~패키지를 함께 소개한다.

해당 가이드북을 작성할 때의 주안점 중에는 저자의 모국어인 `\LaTeX 의 사용법을 한국어로 알려 주는 것'과, `한국어 문서 작성 실정에 맞는 기능을 추가하는 것'이 있었다. 따라서 세 패키지가 한국어를 제공하지 않는다는 점이 아쉬워 이들을 각각 한국어화 하기로 결정하였다.

본래 패키지들의 안내서와 함께, 저자가 작성한 가이드북도 참조하기를 바란다. 가이드북의 예시 문서 15.1, 15.2, 15.3에서 세 패키지의 소스 코드를 확인할 수 있다.
\begin{itemize}
    \item \textsf{varioref}~패키지의 안내서: \href{http://mirrors.ctan.org/macros/latex/required/tools/varioref.pdf}{CTAN 링크}
    \item \textsf{hyperref}~패키지의 안내서: \href{http://mirrors.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.pdf}{CTAN 링크}
    \item \textsf{cleveref}~패키지의 안내서: \href{http://mirrors.ctan.org/macros/latex/contrib/cleveref/cleveref.pdf}{CTAN 링크}
    \item \LaTeX~가이드북 `레이텍 입문부터 활용까지': \href{https://applemincho-latex.tistory.com/3}{링크}
\end{itemize}

\end{document}
