Debian Codegraph @

texmf-dist/source/latex/mahjong/mahjong.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (c) 2021 Daniel Schmitz
4 %
5 % Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
6 % associated documentation files (the "Software"), to deal in the Software without restriction,
7 % including without limitation the rights to use, copy, modify, merge, publish, distribute,
8 % sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
9 % furnished to do so, subject to the following conditions:
10 %
11 % The above copyright notice and this permission notice shall be included in all copies or substantial
12 % portions of the Software.
13 %
14 % THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
15 % NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
16 % NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
17 % DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
18 % OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
19 %
20 % \fi
21
22 % \iffalse
23
24 %<*driver>
25 \documentclass[full]{l3doc}
26 \usepackage[height=1.5\baselineskip]{mahjong}
27 \usepackage{tabularx}
28 \usepackage{array}
29 \usepackage{booktabs}
30 \usepackage{multicol}
31 \usepackage{cleveref}
32 \usepackage{gensymb}
33 \renewcommand{\arraystretch}{1.8}
34 \parskip 6pt
35 \parindent 0pt
36 \EnableCrossrefs
37 \CodelineIndex
38 \RecordChanges
39 \begin{document}
40 \DocInput{mahjong.dtx} \end{document}
41 %</driver>
42 % \fi
43
44 % \CharacterTable
45 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
46 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
47 % Digits \0\1\2\3\4\5\6\7\8\9
48 % Exclamation \! Double quote \" Hash (number) \#
49 % Dollar \$ Percent \% Ampersand \&
50 % Acute accent \' Left paren \( Right paren \)
51 % Asterisk \* Plus \+ Comma \,
52 % Minus \- Point \. Solidus \/
53 % Colon \: Semicolon \; Less than \<
54 % Equals \= Greater than \> Question mark \?
55 % Commercial at \@ Left bracket \[ Backslash \\
56 % Right bracket \] Circumflex \^ Underscore \_
57 % Grave accent \` Left brace \{ Vertical bar \|
58 % Right brace \} Tilde \~}
59
60 % \changes{v0.5}{2021/04/07}{First working version, minimal error handling}
61 % \changes{v0.9}{2021/04/11}{Fully functional}
62 % \changes{v1.0}{2021/04/14}{First complete release}
63 % \changes{v1.0.1}{2021/04/16}{Added package prefix to filenames}
64 % \changes{v1.1}{2025/01/06}{Added feature to control size of symbols. Adjusted vertical alignment.}
65 %
66 % \GetFileInfo{mahjong.sty}
67 % \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
68 % \DoNotIndex{\advance,\begingroup,\catcode,\closein}
69 % \DoNotIndex{\closeout,\day,\def,\edef,\else,\empty,\endgroup}
70
71 % \title{The \textsf{mahjong} package\thanks{This document corresponds to \textsf{mahjong}~\fileversion, dated~\filedate}}
72 % \author{Daniel Schmitz \\ \texttt{[email protected]}}
73 %
74 % \maketitle
75 % \tableofcontents
76 % \begin{abstract}
77 % The \textsf{mahjong} package provides a \LaTeXe{} and \LaTeX~3 interface for typesetting mahjong tiles using an extended version of MPSZ algebraic notation.
78 % Features include spaces, rotated, blank, and concealed tiles, as well as red fives.
79 % The size of the mahjong tiles and their symbols can be controlled using package options and optional arguments.
80 % It is primarily aimed at Riichi (aka. Japanese) Mahjong but can be used to typeset any style of mahjong, save for flower tiles.
81 % \end{abstract}
82 %
83 % \begin{documentation}
84 % \section{Introduction}
85 % Mahjong is a tile-based game originating from China which is popular in East and South-East Asia and has since spread throughout the world.
86 % The \textsf{mahjong} package provides an interface for typesetting mahjong tiles and hands using MPSZ algebraic notation.
87 % This documentation assumes familiarity with the game in general but none of its many styles.
88 % Nonetheless, some basic terms will be defined because of differing vocabulary among players.
89 %
90 % \newcommand{\rmahjong}[1]{\raisebox{-.15\height}{\mahjong{#1}}}
91 % \section{Mahjong Tiles}
92 % \subsection{Suited Tiles}
93 % The suited tiles are referred to as follows:
94 %
95 % \begin{tabular}{@{} l l @{}}
96 % \toprule
97 % \textbf{Suit} & \textbf{Tiles} \\
98 % \midrule
99 % Bamboo & \rmahjong{1234506789s} \\
100 % Dots & \rmahjong{1234506789p} \\
101 % Character & \rmahjong{1234506789m} \\
102 % \bottomrule
103 % \end{tabular}
104 %
105 % Suited tiles are referred to using the pattern \meta{value} \meta{suit}.
106 % For instance, \mahjong{4s} is called \textit{4~Bamboo}.
107 %
108 % \subsection{Honor Tiles}
109 % This documentation refers to the seven honor tiles as follows:
110 %
111 % \begin{tabular}{@{}c c c c@{}}
112 % \toprule
113 % \multicolumn{4}{c}{\bfseries Winds} \\
114 % \mahjong{1z} & \mahjong{2z} & \mahjong{3z} & \mahjong{4z} \\
115 % East Wind (E) & South Wind (S) & West Wind (W) & North Wind (N) \\
116 % \midrule
117 % \multicolumn{4}{c}{\bfseries Dragons} \\
118 % \mahjong{5z} & \mahjong{6z} & \mahjong{7z} & \\
119 % White Dragon & Green Dragon & Red Dragon & \\
120 % \bottomrule
121 % \end{tabular}
122 %
123 % \section{MPSZ Algebraic Notation}
124 % \subsection{Standard Notation}
125 % \begin{table}
126 % \centering
127 % \caption[MPSZ reference]{MPSZ notation reference. Each tile is identified by its column's number and its row's letter.}
128 % \label{tab:mpszref}
129 % \begin{tabular}{ccccccccccc}
130 % & \textbf{0} & \textbf{1} & \textbf{2} & \textbf{3} & \textbf{4} & \textbf{5} & \textbf{6} & \textbf{7} & \textbf{8} & \textbf{9} \\
131 % \textbf{s} & \raisebox{-.75\baselineskip}{\rmahjong{0s}} & \rmahjong{1s} & \rmahjong{2s} & \rmahjong{3s} & \rmahjong{4s} & \rmahjong{5s} & \rmahjong{6s} & \rmahjong{7s} & \rmahjong{8s} & \rmahjong{9s} \\
132 % \textbf{p} & \rmahjong{0p} & \rmahjong{1p} & \rmahjong{2p} & \rmahjong{3p} & \rmahjong{4p} & \rmahjong{5p} & \rmahjong{6p} & \rmahjong{7p} & \rmahjong{8p} & \rmahjong{9p} \\
133 % \textbf{m} & \rmahjong{0m} & \rmahjong{1m} & \rmahjong{2m} & \rmahjong{3m} & \rmahjong{4m} & \rmahjong{5m} & \rmahjong{6m} & \rmahjong{7m} & \rmahjong{8m} & \rmahjong{9m} \\
134 % \textbf{z} & & \rmahjong{1z} & \rmahjong{2z} & \rmahjong{3z} & \rmahjong{4z} & \rmahjong{5z} & \rmahjong{6z} & \rmahjong{7z} & &
135 % \end{tabular}
136 % \end{table}
137 %
138 % % \DeleteShortVerb{\"}
139 % MPSZ notation assigns each tile an identifier consisting of a digit and a letter (\cref{tab:mpszref}).
140 % For suited tiles, the digit corresponds to the tile's value and the letter to its suit, Bamboo (|s|), Dots (|p|) or Character (|m|).
141 % For instance, |2m| identifies \mahjong{2m} (2~Character).
142 % The only exception ot this rule are red fives, whose numeric value is 0.
143 % Red 5 Bamboo, for example, has identifier |0s|.
144 % Honor tiles are assigned the "suit" |z|, with |1z| -- |4z| corresponding to E, S, W and N, and |5z| -- |7z| to the white, green and red dragon, respectively.
145 %
146 % Collections of tiles, such as melds or hands, are represented by concatenating the identifiers of the tiles they comprise.
147 % For instance, |3s4s5s| corresponds to \mahjong{3s4s5s}.
148 % Groups of tiles sharing the same suit can be abbreviated by omitting all but the last suit identifier.
149 % The above example can also be expressed as |345s|.
150 % Spaces are ignored and the notation is case-insensitive.
151 %
152 % \subsection{Extensions}
153 % \paragraph{Spaces.} Spaces can be inserted using |-|:
154 % |444s-567s| produces \mahjong{444s-567s}.
155 %
156 % \paragraph{Concealed Tiles.} \mahjong{X} Concealed (or face-down) tiles are represented by |X|.
157 % They don't need a suit identifier and don't act as one.
158 % |123s X 456s| and |123 X 456s| are therefore equivalent.
159 %
160 % \paragraph{Blank Tiles.} \mahjong{?} Blank or unknown tiles are represented by |?|.
161 % Just like concealed tiles, they don't change the current suit.
162 % |123s ? 456s| and |123 ? 456s| are equivalent, for instance.
163 %
164 % \paragraph{Rotation.} Inserting an apostrophe (|'|) rotates the \textit{preceeding} tile counter-clockwise.
165 % For instance, |6'66m| is rendered as \mahjong{6'66m}.
166 % This can only be done once per tile, i.e. it is not possible to rotate them 180\degree{} or 270\degree{}.
167 % When you want to rotate the last tile of a group, it doesn't matter whether the apostrophe appears before or after the suit, so |77'm| and |77m'| are equivalent.
168 %
169 %
170 % \paragraph{Rotation and Stacking.} Quotes (|"|) cause the \textit{preceeding} tile to be rendered as two rotated and stacked tiles.
171 % For instance, |77"7z| produces \mahjong{77"7z}.
172 %
173 % \section{Typesetting Mahjong Tiles in Your Document}
174 % \DescribeMacro{\mahjong}
175 % The main interface is |\mahjong| \oarg{height} \oarg{scale} \marg{hand}.
176 % \meta{hand} refers to a tile sequence in MPSZ notation as discussed above.
177 % \meta{height} specifies the height of the rendered mahjong tiles.
178 % \meta{scale} specifies the fraction of vertical space that the tiles' symbols should occupy.
179 % The value should be between 0 and 1.
180 % If an optional argument is not given, the default (which can be set through a package argument) will be used.
181 %
182 % \DescribeMacro{\mahjong_typeset_hand:n} \DescribeMacro{\mahjong_typeset_hand:x}
183 % The \LaTeX~3 interface for rendering mahjong tiles are |\mahjong_typeset_hand:n| and its variants.
184 % This macro accepts the hand to be rendered in MPSZ notation.
185 % The height can be specified by setting |\l_mahjong_tile_height| \DescribeMacro{\l_mahjong_tile_height} and the default height is saved in |\g_mahjong_default_height|. \DescribeMacro{\g_mahjong_default_height}
186 % The scale of the tiles' symbols can be changed by setting |\l_mahjong_tile_scale| \DescribeMacro{\l_mahjong_tile_scale} and the default scale is saved in |\g_mahjong_default_scale|.\DescribeMacro{\g_mahjong_default_scale}
187 %
188 % \subsection{Package Options}
189 % \begin{description}
190 % \item[height]
191 % The default height can be set using the package's |height| parameter.
192 % For instance, |\usepackage[height=2\baselineskip]{mahjong}| sets the default size of mahjong tiles to double the value of |\baselineskip| in the context they are rendered in.
193 % \item[scale] The default scale can be set using the package's |scale| parameter.
194 % It should ideally be set to a constant to ensure consistent typesetting.
195 % The default is 0.75, i.e. the symbols take up 85\% of the tiles' vertical space.
196 % \end{description}
197 %
198 % \section{Acknowledgments}
199 % The mahjong tiles used in this package were created by GitHub user \href{https://github.com/FluffyStuff}{FluffyStuff}.
200 % The original repository is \href{https://github.com/FluffyStuff/riichi-mahjong-tiles}{FluffyStuff/riichi-mahjong-tiles}, used under CC-BY Version 4.0.
201 % \end{documentation}
202 % \begin{implementation}
203 %
204 % \begin{macrocode}
205 %<*pkg>
206 %<@@=mahjong>
207 \NeedsTeXFormat{LaTeX2e}[2019/10/01]
208 \RequirePackage{expl3}
209 \ProvidesExplPackage{mahjong}{2025/01/06}{1.1}{Typeset Mahjong Hands}
210 \RequirePackage{xparse}
211 \RequirePackage{l3keys2e}
212 \RequirePackage{graphicx}
213 \RequirePackage{stackengine}
214 % \end{macrocode}
215
216 % \begin{macrocode}
217 \msg_new:nnnn {mahjong} {invalid_token}
218 {Token ~ #1 ~ is ~ not ~ valid ~ in ~ MPSZ ~ notation}
219 {Valid ~ tokens ~ are ~ digits ~ 0-9, ~ m, ~ p, ~ s, ~ z, ~ x, ~ -, ~ ?, ~ ', ~ and ~ " }
220 \msg_new:nnnn {mahjong} {unknown_tile}
221 {I~don't~know~tile~#1.}
222 {Please~check~the~documentation~for~recognized~tiles.}
223 \msg_new:nnnn {mahjong} {unknown_orientation}
224 {Orientation ~ #1 ~ is ~ unknown}
225 {This ~ should ~ not ~ happen.~ Please ~ create ~ a ~ bug ~ report.}
226
227 \keys_define:nn {mahjong} {
228 height .dim_gset:N = \g_mahjong_default_height,
229 scale .int_gset:N = \g_mahjong_default_scale
230 }
231
232 % Identifiers for all suits
233 \cs_new:Npn \c_@@_suits_tl {mpsz}
234 % Allowed tokens
235 \cs_new:Npn \c_@@_allowed_tokens_tl {0123456789mpsz-?x'"}
236
237 % Variables have to be declared globally
238 \tl_new:N \l_@@_suit_tl
239 \tl_new:N \l_@@_tiles_tl
240 \tl_new:N \l_@@_reversed_tl
241 \tl_new:N \l_@@_hand_tl
242 \tl_new:N \l_@@_current_suit_tl
243 \tl_new:N \l_@@_current_group_tl
244 \tl_new:N \l_@@_current_char
245
246
247 \dim_set:Nn \g_mahjong_default_height {\baselineskip}
248 \dim_new:N \l_mahjong_tile_height
249
250 \fp_set:Nn \g_mahjong_default_scale {0.75}
251 \fp_new:N \l_mahjong_tile_scale
252
253 \dim_new:N \l_@@_symbol_height
254 \dim_new:N \l_@@_baseline_offset
255
256 \int_new:N \l_@@_tile_orientation_int
257 \seq_new:N \l_@@_tile_maps_seq
258 \str_new:N \l_@@_file_path_str
259
260
261 \ProcessKeysPackageOptions{mahjong}
262 % \end{macrocode}
263
264 % \begin{macro}[aux]{\@@_make_tile:nn, \@@_make_tile:VV, \@@_make_tile:xV, \@@_make_tile:nV}
265 % Inserts a mahjong tile into the input stream.
266 % This functions only handles tiles that use the front background and have a forground,
267 % i.e. regular and blank tiles.
268 % \begin{macrocode}
269 \cs_set:Npn \@@_make_tile:nn #1#2 {
270 \file_if_exist:nTF {#1} {
271 \int_case:nnF {#2} {
272 {0} {
273 \stackinset{c}{0pt}{c}{0pt}{
274 \includegraphics[
275 angle=0,
276 height=\l_@@_symbol_height]
277 {#1}
278 }{
279 \includegraphics[
280 angle=0,
281 height=\l_mahjong_tile_height]
282 {tiles/mahjong-Front.pdf}
283 }
284 } {1} {
285 \stackinset{c}{0pt}{c}{0pt}{
286 \includegraphics[
287 angle=90,
288 width=\l_@@_symbol_height]
289 {#1}
290 }{
291 \includegraphics[
292 angle=90,
293 width=\l_mahjong_tile_height]
294 {tiles/mahjong-Front.pdf}
295 }
296 } {2} {
297 % Stack 2 rotated tiles on top of each other.
298 \stackon [0pt] {
299 \@@_make_tile:nn {#1} {1}
300 } {
301 \@@_make_tile:nn {#1} {1}
302 }
303 }
304 } {
305 \msg_fatal:nnx {mahjong} {unknown_orientation} {#2}
306 }
307 } {
308 \msg_error:nnx {mahjong} {unknown_tile} {#1}
309 }
310 }
311
312 \cs_generate_variant:Nn \@@_make_tile:nn {VV, xV, nV}
313 % \end{macrocode}
314 % \end{macro}
315 % \begin{macro}{\mahjong_typeset_hand:n, \mahjong_typeset_hand:x}
316 % Parses and typesets a mahjong hand in MPSZ notation.
317 % Set |\l_mahjong_tile_height| to control the tiles' size and |\l_mahjong_tile_scale| to control the size of the symbol relative to the tile.
318 % \begin{macrocode}
319 % Parses a full hand
320 \cs_set:Npn \mahjong_typeset_hand:n #1 {
321 % Set computed dimensions for symbol height and baseline offset
322 \dim_set:Nn \l_@@_symbol_height {\fp_to_decimal:n {\l_mahjong_tile_scale}\l_mahjong_tile_height}
323 \dim_set:Nn \l_@@_baseline_offset {(\l_mahjong_tile_height - \l_@@_symbol_height) / 2}
324 % Start sequence processing
325 \tl_set:Nx \l_@@_hand_tl {\text_lowercase:n {#1}}
326 % MPSZ notation is easier to parse right-to-left, so reverse string
327 % There is no string reversal function but we can reverse token lists
328 % Token lists and strings are freely convertible between each other
329 \tl_set:Nx \l_@@_reversed_tl {\tl_reverse:V \l_@@_hand_tl}
330 \tl_map_variable:NNn \l_@@_reversed_tl \l_@@_current_char {
331 % Check if we recognize the current token
332 \exp_args:NVV \tl_if_in:nnF \c_@@_allowed_tokens_tl \l_@@_current_char {
333 \msg_error:nnx {mahjong} {invalid_token} {\l_@@_current_char}
334 }
335 \exp_args:NVV \tl_if_in:nnTF \c_@@_suits_tl \l_@@_current_char {
336 % If we've found a suit identifier, change the current suit
337 \tl_set:NV \l_@@_current_suit_tl \l_@@_current_char
338 } {
339 \str_case:VnF \l_@@_current_char {
340 {'} {
341 % An apostrophe indicates that the next tile is rotated
342 \int_set:Nn \l_@@_tile_orientation_int {1}
343 }
344 {"} {
345 % Quotes mean the next tile is actually 2 rotated tiles stacked on top of each other
346 \int_set:Nn \l_@@_tile_orientation_int {2}
347 }
348 } {
349 % Default case: We've got a complete tile identifier
350 % Turn it into a property list
351 \prop_clear:N \l_tmpa_prop
352 \prop_put:NnV \l_tmpa_prop {suit} \l_@@_current_suit_tl
353 \prop_put:NnV \l_tmpa_prop {face} \l_@@_current_char
354 \prop_put:NnV \l_tmpa_prop {orientation} \l_@@_tile_orientation_int
355 % Add it to the beginning of the sequence (we are parsing in reverse)
356 \seq_put_left:NV \l_@@_tile_maps_seq \l_tmpa_prop
357 \int_set:Nn \l_@@_tile_orientation_int {0}
358 }
359 }
360 }
361 % Typesetting begins here. Sequence is in correct order
362 \raisebox{-\l_@@_baseline_offset}{
363 \seq_map_variable:NNn \l_@@_tile_maps_seq \l_tmpa_prop {
364 \prop_get:NnN \l_tmpa_prop {face} \l_tmpa_tl
365 \prop_get:NnN \l_tmpa_prop {orientation} \l_tmpa_int
366 \str_case:VnF \l_tmpa_tl {
367 {-} {
368 % If the current face is a dash, insert a space
369 \includegraphics[height=\l_mahjong_tile_height]{tiles/mahjong-Space.pdf}
370 } {x} {
371 % Insert a flipped tile
372 \int_case:nn {\l_tmpa_int} {
373 {0} { % Upright
374 \includegraphics[
375 angle=0,
376 height=\l_mahjong_tile_height]
377 {tiles/mahjong-Back.pdf}
378 } {1} { % Rotated
379 \includegraphics[
380 angle=90,
381 width=\l_mahjong_tile_height]
382 {tiles/mahjong-Back.pdf}
383 } {2} { % Rotated and stacked
384 \stackon [0pt] {
385 \includegraphics[
386 angle=90,
387 width=\l_mahjong_tile_height]
388 {tiles/mahjong-Back.pdf}
389 } {
390 \includegraphics[angle=90,
391 width=\l_mahjong_tile_height]
392 {tiles/mahjong-Back.pdf}
393 }
394 }
395 }
396 } {?} { % Blank tile
397 \@@_make_tile:nV {tiles/mahjong-Blank.pdf} \l_tmpa_int
398 }
399 } { % Any other tile identified by a code.
400 \@@_make_tile:xV {tiles/mahjong-\l_tmpa_tl\prop_item:Nn \l_tmpa_prop {suit}.pdf} \l_tmpa_int
401 }
402 }
403 }
404 % Clear the list for the next invocation
405 \seq_clear:N \l_@@_tile_maps_seq
406 }
407
408 % Have TeX automatically expand the argument for us
409 \cs_generate_variant:Nn \@@_typeset_hand:n {x}
410 % \end{macrocode}
411 % \end{macro}
412 %
413 % \begin{macro}{\mahjong}
414 % This is the only \LaTeXe{} macro in this package.
415 % It typesets a mahjong hand.
416 % \begin{macrocode}
417 \NewDocumentCommand{\mahjong}{O{\g_mahjong_default_height} O{\g_mahjong_default_scale} m}{
418 \dim_set:Nn \l_mahjong_tile_height {#1}
419 \fp_set:Nn \l_mahjong_tile_scale {#2}
420 \mahjong_typeset_hand:n {#3}
421 }
422 %</pkg>
423 % \end{macrocode}
424 % \end{macro}
425 %
426 % \end{implementation}
427 %
428 % \PrintChanges
429 \endinput