path: root/Master/texmf-dist/doc/lualatex/hmtrump/hmtrump.tex

%! LuaLaTeX
\documentclass{jlreq}
\usepackage{hmtrump}
\usepackage{shortvrb,bxtexlogo}
\usepackage[colorlinks,unicode=true]{hyperref}
\hypersetup{linkcolor=blue,urlcolor=teal}
\usepackage{tgheros,newpxtext,newpxmath}
\usepackage[scaled]{beramono}
\MakeShortVerb{\|}
\usepackage[jfm_yoko=jlreq,jfm_tate=jlreqv]{luatexja-preset}
\renewcommand{\thefootnote}{\textasteriskcentered\arabic{footnote}}
\title{|hmtrump| Package}
\author{ひとみさん}
\date{v1.2a [2019-08-06]}

\begin{document}
\maketitle

\begin{center}
Repository: \url{https://github.com/Hitomi-San/hmtrump}\\
Font: \url{http://hwm3.gyao.ne.jp/shiroi-niwatori/nishiki-teki.htm}
\end{center}

\hrulefill
\tableofcontents
\pagebreak

\section{What is this}
You will be able to describe playing cards using |hmtrump| package.
\emph{This package needs LuaLaTeX.}


\section{How to use?}
\begin{enumerate}
\item Install NKD04 Playing Card's Index font
\item |\usepackage{hmtrump}| in preamble
\item To describe cards, use |\trump{<rank>}{<suit>}|
\end{enumerate}

\begin{description}
\item[<rank>] 1 to 9, T (meaning 10), J, Q, K
\item[<suit>] S (Spade), H (Hard), D (Diamond), C (Club), x (no suits)
\end{description}

\vspace*{5pt}
\rule{0pt}{0pt}\hfil
\begin{minipage}[t]{.45\textwidth}
\centerline{output}\hrule\vspace*{1pt}\hrule
\footnotesize
When you play skat, you might remember all \trumpx J
cards---\trump JC, \trump JS, \trump JH and \trump JD
belong trump suit. If trump suit is \hmD{} and
\trump TD is led, then you can follow with \trump JC.

The rank of \trumpx{J} is below:
\[\trump JC>\trump JS>\trump JH>\trump JD\]

All joker---\joker, \blackjoker, \redjoker{} will not
be used in skat.

\hspace{1ex}\hrule\hspace{1ex}

タロットカードには、切札専用のカード\tarottrump{1}〜
\tarottrump{21}が含まれています。占い用のタロットカード
には\trumpblank{愚者}のカードが含まれていますが、
これは切札ではありません。
\end{minipage}
\hfil
\begin{minipage}[t]{.45\textwidth}
\centerline{input}\hrule\vspace*{1pt}\hrule
\scriptsize\ttfamily
When you play skat, you might remember all |\trumpx| J 
cards---|\trump| JC, |\trump| JS, |\trump| JH and |\trump| JD
belong trump suit. If trump suit is |\hmD{}| and |\trump| TD
is led, then you can follow with |\trump| JC.\\

The rank of trumps are below:\\
|\[|
|\trump| JC > |\trump| JS > |\trump| JH > |\trump| JD 
|\]|\\
All joker---|\joker|, |\blackjoker|, |\redjoker{}| will not
be used in skat.\\

|\hspace{1ex}\hrule\hspace{1ex}|\\

タロットカードには、切札専用のカード |\tarottrump{1}|〜
|\tarottrump{21}| が含まれています。占い用のタロットカードには
|\trumpblank{愚者}| のカードが含まれていますが、これは切札では
ありません。
\end{minipage}
\hfil\rule{0pt}{0pt}
\vspace*{5pt}

\section{これは何}
\TeX 文書中で、トランプのカードを表現するためのパッケージです。
|hmtrump| パッケージを利用することで、次のような出力を得る
ことができます。内部で |fontspec| パッケージを読み込んでいるので、
\LuaLaTeX 専用のパッケージとなります（\XeLaTeX でも動くかも
しれないけど、動作確認してないので非対応です）。日本語文書中
でも使用できます。

\section{使い方}
このパッケージで用いているトランプのインデックス用のフォントは、
同梱のトランプの隅印的書体『NKD04 Playing Card's Index』Version 0.80
\footnote{\url{http://hwm3.gyao.ne.jp/shiroi-niwatori/nishiki-teki.htm}}
を用いています。|hmtrump| パッケージを利用する前に、このフォントを
\LuaTeX から利用可能な場所に保存してください。通常はこのフォントを
インストールすればよいです。フォントの作成者はうみほたる様です。
パッケージ作成者ではありません。

パッケージを読み込むには|\usepackage{hmtrump}|をプリアンブルに
書いてください。オプションはありません。

\section{依存パッケージ}
|hmtrump| パッケージは内部で |tikz|、|xcolor|、|fontspec| パッケージ
を読み込みます。

\section{提供される命令}
\begin{table}[tb]
\centering
\caption{例\label{ie}}
\begin{tabular}{lc}
\hline
\multicolumn{1}{c}{入力/input}&出力/output\\
\hline\hline
|\trump{A}{S} \trump{J}{C}|&\trump {A}{S} \trump{J}{C}\\
|\trump 7D \trump QH|&\trump 7D \trump QH\\
|\trump 3x \trump Tx|&\trump 3x \trump Tx\\
|\trumpx 6 \trumpx Q|&\trumpx 6 \trumpx Q\\
\hline
|\hmS \hmH \hmD \hmC|&\hmS \hmH \hmD \hmC\\
\hline
|\JOKER \joker|&\JOKER \joker\\
|\BLACKJOKER \blackjoker|&\BLACKJOKER \blackjoker\\
|\WHITEJOKER \whitejoker|&\WHITEJOKER \whitejoker\\
|\REDJOKER \redjoker|&\REDJOKER \redjoker\\
\hline
|\unitrump{7H} \unitrump{KS}|&\unitrump{7H} \unitrump{KS}\\
\hline
|\trumpblank{愚者}|&\trumpblank{愚者}\\
|\trumpblank{\hmtcfont PAGE}|&\trumpblank{\hmtcfont PAGE}\\
\hline
|\tarottrump{0}|&\tarottrump{0}\\
|\tarottrump{14}|&\tarottrump{14}\\
|\tarottrump{21}|&\tarottrump{21}\\
\hline
\end{tabular}
\end{table}

\subsection{\textbackslash trump 命令}
|\trump{<ランク>}{<スート>}| の書式で、トランプのカードを出力します。
|<ランク>| には通常 |A|、|1| から |9| の整数、|T|、|J|、|C|、|Q|、|K| の
いずれかが入力されることを想定しています。|T| とすると
{\fontspec{NKD04_Playing_Cards_Index}{\char"E002}}が出力
されます。|<スート>| には |S|（\hmS）、|H|（\hmH）、|D|（\hmD）、
|C|（\hmC）|x|（スートの指定なし）のいずれかを指定します。

|\trump{<ランク>}{x}|は|\trumpx{<ランク>}|と書くこともできます。

\subsection{スート出力命令}
|\hmS|、|\hmH|、|\hmD|、|\hmC| はそれぞれ \hmS、\hmH、
\hmD、\hmC を出力します。

\subsection{ジョーカー出力命令}
|\JOKER| や |\joker| で\JOKER や\joker を出力します。
ジョーカー出力命令は8種類あります。表\ref{ie}を参照してください。
デフォルトでは、|\JOKER| は |\BLACKJOKER|になり、
|\joker| は |\blackjoker| となっています。必要に
応じて、|\renewcommand{\joker}{\whitejoker}| などとすることが
できます。

\subsection{\textbackslash unitrump 命令}
|\unitrump{<ランク><スート>}| の書式で、Unicodeのトランプ領域の
文字を出力します。例えば、|\unitrump{QC}| や |\unitrump{TD}| で、
\unitrump{QC} や \unitrump{TD} が出力されます。
\footnote{\texttt{\textbackslash unitrump} 命令で出力される文字は、
\LuaLaTeX-ja を用いている場合は、\textbf{AJchar} として出力されます。}

その他、Unicode のトランプ領域にある文字ならば、すべて出力することができます。
|\unitrump|を用いて出力できる文字は、表\ref{unitrump}を参照してください。

\begin{table}[tb]
\caption{\textbackslash unitrump 命令で出力できる文字\label{unitrump}}
\centering
\begin{tabular}{cc}
\hline
引数/argument&出力/output\\
\hline\hline
|AS AH AD AC|&\unitrump{AS} \unitrump{AH} \unitrump{AD} \unitrump{AC}\\
|2S 2H 2D 2C|&\unitrump{2S} \unitrump{2H} \unitrump{2D} \unitrump{2C}\\
|3S 3H 3D 3C|&\unitrump{3S} \unitrump{3H} \unitrump{3D} \unitrump{3C}\\
|4S 4H 4D 4C|&\unitrump{4S} \unitrump{4H} \unitrump{4D} \unitrump{4C}\\
|5S 5H 5D 5C|&\unitrump{5S} \unitrump{5H} \unitrump{5D} \unitrump{5C}\\
|6S 6H 6D 6C|&\unitrump{6S} \unitrump{6H} \unitrump{6D} \unitrump{6C}\\
|7S 7H 7D 7C|&\unitrump{7S} \unitrump{7H} \unitrump{7D} \unitrump{7C}\\
|8S 8H 8D 8C|&\unitrump{8S} \unitrump{8H} \unitrump{8D} \unitrump{8C}\\
|9S 9H 9D 9C|&\unitrump{9S} \unitrump{9H} \unitrump{9D} \unitrump{9C}\\
|TS TH TD TC|&\unitrump{TS} \unitrump{TH} \unitrump{TD} \unitrump{TC}\\
|JS JH JD JC|&\unitrump{JS} \unitrump{JH} \unitrump{JD} \unitrump{JC}\\
|CS CH CD CC|&\unitrump{CS} \unitrump{CH} \unitrump{CD} \unitrump{CC}\\
|QS QH QD QC|&\unitrump{QS} \unitrump{QH} \unitrump{QD} \unitrump{QC}\\
|KS KH KD KC|&\unitrump{KS} \unitrump{KH} \unitrump{KD} \unitrump{KC}\\
\hline
|back|&\unitrump{back}\\
\hline
|joker joker1 joker2|&\unitrump{joker} \unitrump{joker1} \unitrump{joker2}\\
\hline
|0|&\unitrump{0}\\
|1 2 3 4 5 6 7|&
	\unitrump{1} \unitrump{2} \unitrump{3} \unitrump{4} \unitrump{5} \unitrump{6} \unitrump{7}\\
|8 9 10 11 12 13 14|&
	\unitrump{8} \unitrump{9} \unitrump{10} \unitrump{11} \unitrump{12} \unitrump{13} \unitrump{14}\\
|15 16 17 18 19 20 21|&
	\unitrump{15} \unitrump{16} \unitrump{17} \unitrump{18} \unitrump{19} \unitrump{20} \unitrump{21}\\
\hline
\end{tabular}
\end{table}

\subsection{汎用カード命令}
|\trumpblank{<内容>}| で一般のカードを出力します。カードの中身
は本文書体で表示されるので、必要があれば適当に |\textsf| や |\textbf|
などを補ってください。|\hmtcfont| 命令
で NKD04 Playing Card's Index を利用できます（|\hmtcfont|
は宣言型の命令です）。例えば、|\trumpblank{\hmtcfont JOKER}|
で\trumpblank{\hmtcfont JOKER}を出力します。

\subsection{タロットカードの切札用命令}
|\tarottrump{<数字>}| で、タロットの切札を出力できます。|<数字>| には
0から21の整数が入ります。例えば、|\tarottrump{8}| で\tarottrump{8}が
出力されます。|\tarottrump{0}| は愚者のカードを出力する目的で用い、
\tarottrump{0}が出力されます。

\section{カスタマイズ}
|\renewcommand| などをすることによって、出力結果をカスタマイズ
することができます。

\subsection{フォント名}
NKD04\_Playing\_Cards\_Index を違うフォント名でインストールした場合、
|\hmtc@trump@font| をインストールしたフォント名に |\renewcommand| で
定義し直してください。

\textbf{注意}: NKD04 Playing Card's Index Version 0.80 の私用領域を
前提としているので、他のフォントを指定した場合はうまく動きません。

\subsection{色}
\begin{table}[tb]
\centering
\caption{変更可能な色\label{color}}
\begin{tabular}{lll}
\hline
色の名前&デフォルトの定義&色の箇所\\
\hline\hline
|hartsuit|&|{cmyk}{.14,.94,.22,.27}|&ハートのスート及びカードの文字\\
|diasuit|&|{cmyk}{.11,.57,.97,.31}|&ダイヤのスート及びカードの文字\\
|clubsuit|&|{cmyk}{.70,.5,.99,.18}|&クラブのスート及びカードの文字\\
|spadesuit|&|{cmyk}{.98,.80,.5,.15}|&スペードのスート及びカードの文字\\
\hline
|cardback|&|{gray}{.95}|&カードの背景\\
|cardborder|&|{gray}{.2}|&カードの枠線\\
|cardtext|&|{gray}{0}|&スート指定のないカードの文字\\
\hline
\end{tabular}
\end{table}

視認しやすいよう、|hmtrump| パッケージではスートのマークと、
スートのマークを伴うカードを出力する時に、色を使って出力します。
デフォルトでは、白黒印刷にも耐えれるよう、それぞれ彩度を落とした
色になっています。

色を変更したい場合は、|xcolor| パッケージが提供している、 |\definecolor|
命令を使って、色の定義を変更します。変更できる色の定義は、表\ref{color}に
示してあるとおりです。

例えば、|\definecolor{hartsuit}{cmyk}{0,.84,.94,.01}| と書いておけば、
|\hmH| で{\definecolor{hartsuit}{cmyk}{0,.84,.94,.01}\hmH}が出力されます。
|\definecolor| 命令は、局所化の影響を受けるので、|{}| で括れば
一部だけの色を変えることも可能です。

\subsection{サイズ}
|\tikzset|命令を使って、出力されるカードのサイズを変更することができます。

|\tikzset{hmtcscale/.style={scale=<倍率>}}| と書くことで指定した倍率の
カードが出力されます。デフォルトでは 0.9 倍になっています。こちらも局所化の影響を
うけます。ベースラインの位置は固定です。

例えば |{\tikzset{hmtcscale/.style={scale=0.6}}\trump 3H}\trump JD| と
書くと {\tikzset{hmtcscale/.style={scale=0.6}}\trump 3H}\trump JD が出力されます。

\section{その他}
\begin{itemize}
\item \LuaLaTeX-ja を利用している場合、|\ltjdefcharrange| 命令を用いて、24番の
	文字範囲にいくつかの文字を追加し、それらを\textbf{ALchar}として設定します。
	文字範囲を変更している場合、24番の文字範囲には新しく文字を追加したり、\textbf{JAchar}
	として設定しないように注意してください。
\end{itemize}

\section{TO DO}
以下実装したいと思っていること:
\begin{itemize}
\item |\trump| 命令に不正なスートの指定子が指定された時にエラーを吐くようにする。
\item もしかしなくても |\joker| 命令で出力されるカード、若干位置が下がってますね……。
\end{itemize}

\section{License}

\rule{0pt}{0pt}\hfill\includegraphics[height=2\zh]{by-sa.png}\hfill\rule{0pt}{0pt}

このパッケージに含まれる成果物は、クリエイティブ・コモンズ 表示--継承
ライセンスの元で配布を行う。

NKD04 Playing Card's Index フォントのライセンスは、配布元で示されている通りの
条件に従う。すなわち、商用私用問わず自由に使用でき、配布元
\url{http://hwm3.gyao.ne.jp/shiroi-niwatori/nishiki-teki.htm}
を示せば再配布も可能である。原文は下に示す。

This package is licensed under a Creative Commons Attribution-ShareAlike
4.0 International License.

NKD04 Playing Card's Index is licensed under following;
There is no restriction on using NKD04 Playing Card's Index regardless
of private or commercial, and it is possible to redistribute this.
In the case of redistribution, please specify this distribution source
\url{http://hwm3.gyao.ne.jp/shiroi-niwatori/nishiki-teki.htm}.
The original text is shown below.

以下が、\url{http://hwm3.gyao.ne.jp/shiroi-niwatori/faq.txt}にて記されている、
フォントのライセンスの全文である（「以下各フォント」に
nkd04\_playing\_cards\_index.ttf も含まれている）。

\noindent\hspace{1cm}\dotfill\hspace{1cm}

\bgroup\small
\url{http://hwm3.gyao.ne.jp/shiroi-niwatori/nishiki-teki.htm}
にて配布している「にしき的フォント」以下各フォントでの文書や画像の作成、
装飾としての利用等、一般的な目的での使用については何の制限もありません。
私用商用を問わず存分にご自由におこなってください。

ゲームなどのアーカイヴへの同梱や、その他なんらかの形の再配布についても、必要であればかまいません。
再配布の場合は当配布元は明示しておいていただければと思います (当配布元が消滅した場合は不要です)。

フォントはときどき更新していたりするので、なるべく最新版をお使いいただけると嬉しいです。
特に「にしき的フォント」(Nishiki-teki) は文字の追加や修正等をかなり頻繁におこなっております。

フォントの使用に際して当方への報告などは特に必要ありません。
が、ご一報などいただけました場合には使ってくださってありがたいなあと喜びつつ今後の参考にさせて
いただいたり心の糧として励みにするなどいたします。

なにか疑問点や至らぬ点などございましたら忌憚なくお問い合わせください。\\
\url{http://hwm3.gyao.ne.jp/shiroi-niwatori/quispiam_est.htm}\\
このページ下部のWeb拍手あたりをご利用いただければと存じます。
当方からの返答は \url{http://d.hatena.ne.jp/Umihotaru/} こちらをご覧になってください。


\hspace{3\zw}2016-03-18\hspace{1\zw}うみほたる拝
\egroup

\section{Change log}
\begin{description}
\item[{[2019-08-06 ver.~1.2a]}] |\newfontfamily| を覚えた。
\item[{[2019-06-13 ver.~1.1b]}] マニュアルの誤植を修正。
\item[{[2019-06-12 ver.~1.1a]}] |\unitrump| 命令を追加。
\item[{[2019-06-12 ver.~1.1a]}] マニュアルの誤植を修正。
\item[{[2019-05-21 ver.~1.0d]}] フォントのライセンスを明記。
\item[{[2019-05-15 ver.~1.0c]}] ライセンスを明記。
\item[{[2019-05-14 ver.~1.0b]}] |\@undefined| を使うことを覚えた。
\item[{[2019-05-14 ver.~1.0b]}] 英文のドキュメントを作成。
\item[{[2019-04-14 ver.~1.0]}] |hmtrump.sty| に作者を明記。
\item[{[2019-04-14 ver.~1.0]}] ドキュメントのサンセリフフォントを変更。
\item[{[2019-04-14 ver.~1.0]}] TO DO を追加。
\end{description}

\end{document}