doc: add v0.2.0 documentation

doc/example.tex

@@ -0,0 +1,13 @@
+\documentclass[nenga,rensuji]{hagaki}
+\sender{
+  postal_code = 103-0027,
+  name        = 日本 太郎,
+  address     = 東京都中央区日本橋1-3-11
+}
+\begin{document}
+\recipient{
+  postal_code = 542-0071,
+  name        = {戎 太郎, 花子},
+  address     = 大阪府大阪市中央区道頓堀1丁目
+}
+\end{document}

doc/hagaki-doc.cls

@@ -1,54 +1,112 @@
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesExplClass{hagaki-doc}{2021/12/22}{}{}
 
+% -- debug
+
+% \RequirePackage{lua-visual-debug}
+
 % -- layout
 
-\LoadClass{jlreq}
-\RequirePackage[margin=2.5cm]{geometry}
-\pagestyle{plain}
+\LoadClass{ jlreq }
+\RequirePackage[ margin=2.5cm ]{ geometry }
+\pagestyle{ plain }
 
 \dim_set:Nn \parindent { 0mm }
 \dim_set:Nn \parskip { 0mm }
 
+\renewcommand\@maketitle{
+  \raggedright
+  { \Huge\bfseries \@title \par }
+  \vspace{4mm}
+  { \large \bfseries \@author \hspace{3mm} | \hspace{3mm} \@date }
+  \vspace{20mm}
+}
+
+\ModifyHeading{ section }{
+  font = \Large\bfseries
+}
+\ModifyHeading{ subsection }{
+  font = \large\bfseries
+}
+
+\cs_new:Npn \__hgkd_desc_label:n #1 {
+  \normalfont\bfseries #1 \hfill
+}
+\renewenvironment{ description }{
+  \list{}{
+    \dim_set_eq:NN \labelwidth \leftmargin
+    \dim_set:Nn \labelsep { 1\zw }
+    \dim_add:Nn \labelwidth { - \labelsep }
+    \cs_set_eq:NN \makelabel \__hgkd_desc_label:n
+  }
+}{
+  \endlist
+}
+
 % -- font
 
-\RequirePackage{luatexja-fontspec}
-\setmainfont{Helvetica}
-\setmainjfont{NotoSansJP}
-\setmonofont{JetBrainsMono}
+\RequirePackage{ luatexja-fontspec }
+\setmainfont{ Helvetica.ttc }[
+  UprightFeatures = { FontIndex = 4 },
+  BoldFeatures    = { FontIndex = 1 }
+]
+\setmainjfont{ NotoSansJP }[
+  UprightFont = NotoSansJP-Light,
+  BoldFont    = NotoSansJP-Medium
+]
+\setmonofont{ JetBrainsMono }
 
 % -- tabular
 
-\RequirePackage{tabularx}
-\RequirePackage{booktabs}
+\RequirePackage{ tabularx }
+\RequirePackage{ booktabs }
 
 \dim_set:Nn \abovetopsep { .8\baselineskip }
 \dim_set:Nn \belowbottomsep { .8\baselineskip }
 
 % -- image
 
-\RequirePackage{graphicx}
+\RequirePackage{ graphicx }
+\RequirePackage{ wrapfig }
 
 \dim_set:Nn \fboxsep { 0mm }
 \dim_set:Nn \fboxrule { 0.1mm }
 
+\NewDocumentCommand\image{ O{} m }{
+  \fbox{
+    \includegraphics[#1]{#2}
+  }
+}
+
+% -- url
+
+\RequirePackage{ hyperref }
+\hypersetup{
+  hidelinks,
+  colorlinks  = true,
+  linkcolor   = blue,
+  urlcolor    = blue
+}
+\AtBeginDocument{
+  \hypersetup{
+    pdftitle  = \@title,
+    pdfauthor = \@author
+  }
+}
+
 % -- code
 
 \newcommand\code[1]{
   \texttt{#1}
 }
-\cs_set_eq:NN \pkg \code
-\cs_set_eq:NN \file \code
-
+\newcommand\pkg[1]{
+  #1
+}
 \newcommand\cs[1]{
   \char`\\\texttt{#1}
 }
 
-\RequirePackage{listings}
+\RequirePackage{ listings }
 \lstset{
   basicstyle=\ttfamily
 }
-
-\ExplSyntaxOff
-\RequirePackage{fancyvrb}
-\DefineShortVerb{\|}

doc/hagaki.tex

@@ -2,28 +2,35 @@
 
 \title{Hagaki クラス}
 \author{HiroSpark}
-\date{v0.1.0}
+\date{v0.2.0 （\today）}
 
 \begin{document}
 
 \maketitle
 
 \section{概要}
 
-\code{Hagaki} クラスはハガキの宛名印刷を簡単に行うためのドキュメントクラスです。
-Lua\LaTeX{} が必要です。
+\code{Hagaki}クラスはハガキの宛名印刷を簡単に行うためのドキュメントクラスで、
+Lua\TeX{}上で動作します。
+ライセンスはMITです。
+
+\begin{description}
+  \item[Issues] \url{https://github.com/HiroSpark/hagaki/issues}
+  \item[Code] \url{https://github.com/HiroSpark/hagaki}
+\end{description}
 
 \section{インストール}
 
-リポジトリをクローンし、\file{build.lua}のあるディレクトリで、
+\href{https://github.com/HiroSpark/hagaki/releases/}{GitHub Releases}から
+ソースコードをダウンロードし、\code{build.lua}のあるディレクトリで、
 
 \begin{lstlisting}
 $ l3build install
 \end{lstlisting}
 
 を実行してください。
-\pkg{l3build}によって、TDSに準拠した形で、\code{TEXMF}ツリーに
-\file{hagaki.cls}がインストールされます。
+\pkg{l3build}によって、ユーザーの\code{TEXMF}ツリーに
+\code{hagaki.cls}がインストールされます。
 アンインストールするには、同じディレクトリで、
 
 \begin{lstlisting}
@@ -33,46 +40,116 @@ \section{インストール}
 を実行します。
 詳細は\pkg{l3build}のドキュメントを見てください。
 
-\section{使用法}
+\section{基本的な使い方}
+
+\subsection{普通ハガキと年賀ハガキ}
+
+\pkg{hagaki}クラスのデフォルトは、普通ハガキのレイアウトです。
+年賀ハガキのレイアウトにするには、クラスオプションに\code{nenga}を指定してください。
+
+\begin{lstlisting}
+\documentclass[nenga]{hagaki}
+\end{lstlisting}
+
+\subsection{\cs{sender}と\cs{recipient}}
 
-予定にはありませんが、現在も開発中なため、将来のリリースで変更される可能性があります。
 \cs{sender}は差出人の情報を、\cs{recipient}は宛先の情報を指定します。
 \cs{recipient}は宛先の情報の指定とともに、宛名面の作成も行います。
 
-どちらも|keyval|リストで郵便番号・住所・名前を指定します。
+どちらも\code{keyval}リストで郵便番号・住所・名前を指定します。
 受け取る値の詳細は以下のようになっています。
 
 \begin{tabularx}{\linewidth}{llX}
   \toprule
   \code{key} & 指定する値 & 注意 \\
   \midrule
-  \code{postal\_code} & 郵便番号 & \code{-} が必要です。\\
+  \code{postal\_code} & 郵便番号 & \code{-}が必要です。\\
   \code{name} & 名前 & 半角スペースで名字と名前を区切ってください。\\
   \code{address} & 住所 &
   組版の関係で、英数字は「\rotatebox[origin=c]{270}{1}」のようになってしまいます。
-  それを避けたい場合は、数字を和文文字にするか、\pkg{lltjext} の
-  \cs{rensuji{}} を使ってください。\\
+  それを避けたい場合は、数字を和文文字にするか、クラスオプションに\code{rensuji}を
+  指定してください。\\
   \bottomrule
 \end{tabularx}
 
 例えば、以下のソースを処理すると、次のような宛名面が作成されます。
 
-\begin{lstlisting}
-\documentclass{hagaki}
-\sender{
-  postal_code = 103-0027,
-  name        = 日本 太郎,
-  address     = 東京都中央区日本橋1-3-11
-}
-\begin{document}
-\recipient{
-  postal_code = 542-0071,
-  name        = 戎 太郎,
-  address     = 大阪府大阪市中央区道頓堀1丁目
-}
-\end{document}
-\end{lstlisting}
+\begin{figure}
+  \begin{minipage}{.6\linewidth}
+    \lstinputlisting{example.tex}
+  \end{minipage}
+  \begin{minipage}{.4\linewidth}
+    \image[width=\linewidth]{example.pdf}
+  \end{minipage}
+\end{figure}
+
+\section{リファレンス}
+
+\subsection{クラスオプション}
+
+\begin{tabularx}{\linewidth}{lX}
+  \toprule
+  オプション & 説明 \\
+  \midrule
+  \code{nenga} & 年賀状用のレイアウトに変更します。\pkg{hagaki}のデフォルトレイアウトは通常ハガキです。\\
+  \code{rensuji} & 住所の数字に対して、自動的に\cs{rensuji}を適用します。\pkg{lltjext}を読み込みます。\\
+  \code{debug} & デバッグ用に、グリッドや\TeX{}のボックスなどが表示されます。\pkg{lua-visual-debug}を読み込みます。\\
+  \bottomrule
+\end{tabularx}
+
+\subsection{\cs{hagakisetup}}
+
+\cs{hagakisetup{\arg{options}}でレイアウトをカスタマイズ出来ます。
+\arg{options}には\code{keyval}リストで以下の値を指定可能です。
+この機能は実験的なため、将来的に変更される可能性があります。
+
+\begin{tabularx}{\linewidth}{ll}
+  \toprule
+  key & 説明 \\
+  \midrule
+  \code{top\_line}                        & 宛先の住所と名前の上端 \\
+  \code{bottom\_line}                     & 宛先の名前と差出人の住所と名前の下端 \\
+  \code{recipient / address\_position}    & 宛先の住所の中心（y座標） \\
+  \code{recipient / name\_position}       & 宛先の名前の中心（y座標） \\
+  \code{recipient / name\_indent}         & 宛先の名前のインデント \\
+  \code{recipient / family\_name\_width}  & 宛先の苗字に充てるスペース \\
+  \code{sender / address\_position}       & 差出人の住所の中心（y座標） \\
+  \code{sender / name\_position}          & 差出人の名前の中心（y座標） \\
+  \bottomrule
+\end{tabularx}
+
+\subsection{\code{expl3}インターフェイス}
+
+\code{hgk}モジュールとして提供されます。
+この機能は実験的なため、将来的に変更される可能性があります。
+
+\begin{tabularx}{\linewidth}{ll}
+  \toprule
+  関数 & 挿入箇所 \\
+  \midrule
+  \cs{hgk\_rcpt\_postal\_code\_style:}    & 宛先の郵便番号 \\
+  \cs{hgk\_rcpt\_address\_style:}         & 宛先の住所 \\
+  \cs{hgk\_rcpt\_name\_style:}            & 宛先の名前 \\
+  \cs{hgk\_sender\_postal\_code\_style:}  & 差出人の郵便番号 \\
+  \cs{hgk\_sender\_address\_style:}       & 差出人の住所 \\
+  \cs{hgk\_sender\_name\_style:}          & 差出人の名前 \\
+  \bottomrule
+\end{tabularx}
 
-\fbox{\includegraphics[width=.5\linewidth]{example.pdf}}
+\section{バージョン履歴}
+
+\begin{description}
+  \item[v0.2.0] カスタマイズ関連を中心に、機能の追加・強化といくつかの破壊的変更を行いました。
+    \leavevmode
+    \begin{itemize}
+      \item 年賀状用のレイアウトはクラスオプション\code{nenga}の指定が必要に
+      \item \cs{hagakisetup}によるカスタマイズ機能の導入
+      \item \pkg{expl3}インターフェイスによるコードの挿入
+      \item 数字に\cs{rensuji}を自動的に適用するクラスオプション\code{rensuji}を追加
+      \item デバッグ用のクラスオプション\code{debug}を追加
+      \item 差出人・宛先が複数の場合に対応
+    \end{itemize}
+  \item[v0.1.0] 最初のリリース
+\end{description}
 
 \end{document}

hagaki.cls

@@ -1,7 +1,7 @@
 % The package is distriibuted under the MIT License.
 
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesExplClass{hagaki}{2021/12/18}{0.1.0}{}
+\ProvidesExplClass{hagaki}{2021/12/18}{0.2.0}{}
 \RequirePackage{tikz}
 
 % -- エラーの出力