index.docbook 55.2 KB
Newer Older
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1
2
<?xml version="1.0" ?>
<!--IMPORTANT: please note that 'Do not change this!' notice does not apply to translators -->
3
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
4
5
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
  <!ENTITY % addindex "IGNORE"> <!-- do not change this! -->
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
  <!ENTITY s1 "s1">
  <!ENTITY s9 "s9">
  <!ENTITY b1 "b1">
  <!ENTITY b9 "b9">
  <!ENTITY c1 "c1">
  <!ENTITY c9 "c9">
  <!ENTITY we "we">
  <!ENTITY ws "ws">
  <!ENTITY ww "ww">
  <!ENTITY wn "wn">
  <!ENTITY db "db">
  <!ENTITY dr "dr">
  <!ENTITY dg "dg">
  <!ENTITY chow "chow">
  <!ENTITY pung "pung">
  <!ENTITY kong "kong">
  <!ENTITY mahjongg "mahjongg">
  <!ENTITY originalcall "originalcall">
  <!ENTITY violatesoriginalcall "violatesoriginalcall">
  <!ENTITY dangerousgame "dangerousgame">
  <!ENTITY nochoice "nochoice">
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
27
28
]>

29
30
<!-- TODO: describe the window with the list of tables -->

31
<book id="kajongg" lang="&language;"> <!-- do not change this! -->
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
32
<bookinfo>
33
	<title>The &kajongg; Handbook</title> <!-- This is the title of this docbook. -->
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
34
35
36
37
<!-- List of immidiate authors begins here. -->
<!--INPORTANT! - All other contributors: [to be determined] -->
<authorgroup>
<author>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
38
	&Wolfgang.Rohdewald; &Wolfgang.Rohdewald.mail;
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
39
40
41
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
42
<legalnotice>&FDLNotice;</legalnotice>
43

Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
44
45
<date>2021-05-30</date><!-- Date of (re)writing, or update.-->
<releaseinfo>KDE Gear 21.04</releaseinfo>
46

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
47
48
<!--Short description of this document. Do not change unless necessary!-->
<abstract>
Burkhard Lück's avatar
Burkhard Lück committed
49
	<para>This documentation describes the game of &kajongg;</para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
50
</abstract>
51

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
<!--List of relevant keywords-->
<keywordset>
	<keyword>KDE</keyword> <!-- do not change this! -->
	<keyword>kdegames</keyword> <!-- do not change this! -->
	<keyword>game</keyword> <!-- do not change this! -->
	<keyword>kajongg</keyword><!--Application name goes here-->
<!-- Game genre. Use as many as necessary. Available game types are: Arcade, Board, Card, Dice, Toys, Logic, Strategy.-->
	<keyword>board</keyword>
	<keyword>arcade</keyword>
	<keyword>tile game</keyword>
	<keyword>tiles</keyword>
<!--Number of possible players. It can be: One, Two,..., Multiplayer-->
	<keyword>four players</keyword>
<!--All other relevant keywords-->
</keywordset>
</bookinfo>
<!--Content begins here: -->
<chapter id="introduction"><title>Introduction</title> <!-- do not change this! -->
	<note><title>Gametype:</title><para>Board, Arcade</para></note><!-- Game genre. Use as many as necessary. Available game types are: Arcade, Board, Card, Dice, Toys, Logic, Strategy.-->
	<note><title>Number of possible players:</title><para>Four</para></note><!--Number of possible players. It can be: One, Two,..., Multiplayer-->
	<para>
73
		&kajongg; is a board game created after the famous oriental game of Mah Jong (from Chinese <foreignphrase lang="zh">麻將</foreignphrase>). It is played by four players. Worldwide many different rulesets are in use. Right now &kajongg; supports the Classical Chinese rules as played in Germany, eventually other main rulesets will follow. It is possible to customize or add new rulesets. Please do so and send them to the program author for integration!
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
74
75
	</para>
	<para>
76
                &kajongg; can be used in two different ways: Scoring a manual game where you play as always without the help of a computer and use &kajongg; for the computation of scores and for bookkeeping. Or you can use &kajongg; to play against any combination of other human players or computer players.
77

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
78
79
	</para>
</chapter>
80

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
<chapter id="screen_layout"><title>The Screen Layout</title>
		<para>
			<screenshot>
				<screeninfo>A screenshot of &kajongg;</screeninfo>
				<mediaobject>
					<imageobject>
						<imagedata fileref="gamescreen.png" format="PNG"/>
					</imageobject>
					<textobject><phrase>Screenshot</phrase></textobject>
				</mediaobject>
			</screenshot>
                </para>
                <para>
                        A quick explanation of the parts of the game screen.
                </para>
	<variablelist>
		<varlistentry>
			<term>Toolbar</term>
			<listitem><para>
				The Toolbar is located beneath the menubar and contains buttons for the most often used actions. The content of the Toolbar can be edited. You can also make it invisible, giving more room to the Board.
101
			      </para><para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
102
				Depending on the size of your screen you may want to make the toolbar invisible or to move it to the left side of the window. You can do that by click with the &RMB; on the toolbar.
103
			      </para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
104
105
106
107
		</varlistentry>
		<varlistentry>
			<term>Board</term>
			<listitem><para>
108
109
110
111
				The Board is the largest section of the window. You see the four walls with a length of 18 tiles (the exact number depends on the rules like using bonus tiles or not).
				The names of the players are written on the walls, together with the current value of the hand (as far as known) and their wind tiles. The prevailing wind has a coloured background, east in the screenshot above.
			</para><para>
				When <link linkend="play">playing</link>, the interior of the walls holds the tiles discarded by the players. They are randomly placed. The last discarded tile has a blue focus frame.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
112
113
114
115
116
117
118
119
			</para><para>
				When <link linkend="scoreGame">scoring manual games</link>, the interior of the walls has a selection of all available tiles, the central selector. You can assign them to the players using the mouse or the keyboard.
			</para>
			</listitem>
		</varlistentry>
		<varlistentry>
			<term>Player Region</term>
			<listitem><para>
120
121
122
123
124
125
126
127
128
				Every player has a screen range for her tiles. The upper row contains exposed tiles, the lower row concealed tiles.
				When <link linkend="scoreGame">scoring manual games</link>, concealed tiles are shown with a shadow over the entire tile.
				Bonus tiles go to the right end.
			</para></listitem>
		</varlistentry>
		<varlistentry>
			<term>Dialog</term>
			<listitem><para>
				The dialog presents choices the player has. Most often it has a timeout with a progress bar showing the remaining time.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
129
130
131
			</para></listitem>
		</varlistentry>
		<varlistentry>
132
			<term>Status bar</term>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
133
			<listitem><para>
134
				The Status bar is located at the bottom of the screen and contains the current totals for the players.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
135
136
137
138
			</para></listitem>
		</varlistentry>
	</variablelist>
</chapter>
139

140
<chapter id="scoreGame"><title>Scoring a Manual Game</title> <!-- do not change this! -->
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
141
142
143
144
145
	<para>
		In this mode, &kajongg; is only used to do the scoring. You play as usual with real people on a real table and at the end of a game you can tell &kajongg; the tiles a player has in her hand and everything else &kajongg; needs to know for calculating the scores - which is what the program will do. Alternatively you can calculate the hand scores manually and enter them. &kajongg; will then make the payments amongst the players and write the results into a data base. It is possible to suspend a game, start another game with other players and resume old games. All rules will be saved together with the games, so different games can be played with different rules.
	</para>
        <itemizedlist>
            <listitem><para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
146
                    From the menu, select <menuchoice><guimenu>Game</guimenu> <guimenuitem>Score Manual Game</guimenuitem></menuchoice> or press <keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
147
148
149
150
151
            </para></listitem>
            <listitem><para>
                    Now you can either select an existing unfinished game or start a new game. If you start a new game, you will be asked for the players and the ruleset. &kajongg; will propose the same values used for the previous game. If there was no previous game, it will propose the first four defined players. Please note that you cannot change the ruleset or any of its rules after this selection. You can do that beforehand in <link linkend="ruleset-options">the ruleset editor</link>.
            </para></listitem>
            <listitem><para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
152
                Now you get a new window titled <guilabel>Scoring for this Hand</guilabel>. Read <link linkend="enterhand-tiles">Have &kajongg; compute the score</link> for a detailed description.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
153
154
155
156
157
            </para></listitem>
            <listitem><para>
                After saving hand results, continue with the next hand.
            </para></listitem>
        </itemizedlist>
158
      <sect1 id="enterhand"><title>Entering hand results</title>
159
        <sect2 id="enterhand-scores">
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
160
161
162
163
164
165
166
167
168
169
	<title>Scores</title>
	<screenshot>
		<screeninfo>A screenshot of &kajongg;</screeninfo>
		<mediaobject>
			<imageobject>
				<imagedata fileref="enterhand.png" format="PNG"/>
			</imageobject>				<textobject><phrase>Screenshot</phrase></textobject>
		</mediaobject>
	</screenshot>
	<para>
170
		This is the window for entering hand results. It automatically shows itself when &kajongg; thinks you might need it. You can always show or hide it by pressing  <keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> or by selecting the corresponding menu entry.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
171
172
173
174
175
176
177
178
	</para>
	<para>
		As always the prevailing wind has its background colored.
	</para>
	<para>
		Here you can manually enter scores for all players. Alternatively you can exactly define which tiles a player had in her hand. If you choose to do that, the corresponding field for the manual score value will be grayed out. &kajongg; will automatically compute the score.
	</para>
	<para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
179
		After having entered all relevant data for a hand, press the button <guibutton>Save Hand</guibutton>. The hand values will be entered in the data base, and they are also shown in the score table. You might be prompted to change the seating positions of the players but you can choose not to change seats. The proposed changes are currently not customizable - if a ruleset needs something different, we will change that.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
180
181
	</para>
	<para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
182
		If the player might have won, the check box in the column <guilabel>Winner</guilabel> will be enabled - click this for the winner.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
183
184
185
186
	</para>
	<para>
		The status bar will now show the updated balances for the players, and you can continue with the next hand.
	</para>
187
	<sect3 id="enterhand-manually">
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
188
189
190
191
192
	<title>Enter the score manually</title>
	<para>
		A good player will probably prefer to compute her score himself. In that case you can directly enter it. This is only possible when no tiles are selected for this player.
	</para>
	<para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
193
		If you enter a manual score, it must already contain everything except penalties, you will have no optional rules to choose from. There is one exception: <quote>Dangerous Game</quote>. This does not influence any scores, it is no offense either. It only means the payment between players is different: The offender pays all for all to the winner. The other two players do not exchange payments. This is currently not customizable.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
194
	</para>
195
196
	</sect3>
	<sect3 id="enterhand-tiles">
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
197
198
199
200
201
202
203
204
	<title>Have &kajongg; compute the score</title>
	<para>
		If you explicitly tell &kajongg; what tiles a player holds, entering scores will be grayed out for that player in this window. While associating tiles with a player you will see how her score will grow - but as soon as you add the 14th tile the score goes to zero. That might surprise you but unless you declare this as the winner hand, it is recognized as a long hand which always has zero points. This behaviour is defined by the Classical Chinese ruleset, it might be different if you change the rules or use a different ruleset.
	</para>
	<para>
		You can associate tiles and melds with a player using either the mouse or the keyboard or both. With the mouse simply move tiles by dragging/dropping them to the player region. When dropping the tile, you will be asked what you want to move: Single, Pair, Pung, Kong, Claimed Kong or Chow. The upper row is for exposed tiles, the lower row for concealed tiles. The bonus tiles will appear to the far right. You can also move tiles and melds between rows, between players and back to the central selector.
	</para>
	<para>
205
206
207
208
		If you prefer using the keyboard, you can use &Tab; to move between the central selector and the player regions. The keys <keycap>eswnESWN</keycap> move a tile to the players East, South, West and North.
		The keys <keycap>xX</keycap> move it back to the central selector. <keycap>ESWN</keycap> moves to the concealed row, <keycap>eswn</keycap> moves to the exposed row.
		You can move the cursor between tiles or melds using the arrow keys, the currently selected tile or meld has a blue frame. Since the key arrows are far away from letters on the keyboard,
		you can also use the letters <keycap>hjkl</keycap> or <keycap>HJKL</keycap> for moving the cursor. <keycap>hH</keycap> move left, <keycap>jJ</keycap> move down, <keycap>kK</keycap> move up,
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
209
		<keycap>lL</keycap> move right. This is how the unix editor <command>vi</command> does it. The &kde; browser &konqueror; and even this help program also support those keys in the same way. Those keys may differ if you use a language other than English but it is currently not possible to configure them.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
210
211
	</para>
	<para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
212
		The options <guilabel>Last Tile:</guilabel> and <guilabel>Last Meld:</guilabel> are needed by some rules like <guilabel>Last tile completes pair</guilabel>. They can only be used for the winner hand.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
213
214
	</para>
	<para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
215
		In the right part of the window you can manually apply some rules. What rules appear in this list depends on the current ruleset and on the tiles. In the example of the above screen shot, the losing players might have an option <quote>dangerous game</quote> - again depending on the ruleset and on their tiles. It is the aim of the developers to keep this list of manually selectable rules as short as possible. Optimally &kajongg; should always be able to automatically determine whether a rule applies, but sometimes &kajongg; does not have enough information or knowledge to decide.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
216
	</para>
217
	</sect3>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
218
	</sect2>
219
	<sect2 id="enterhand-penalties">
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
220
221
222
223
224
225
226
227
228
229
230
231
	<title>Penalties</title>
			<screenshot>
				<screeninfo>A screenshot of &kajongg;</screeninfo>
				<mediaobject>
					<imageobject>
						<imagedata fileref="penalty.png" format="PNG"/>
					</imageobject>
					<textobject><phrase>Screenshot</phrase></textobject>
				</mediaobject>
			</screenshot>
	<para>
	In the <link linkend="enterhand">window for entering hand results</link>, the <guibutton>Penalties</guibutton> button will bring up this window where you can enter penalties. This can be done at any point in time independent of the normal scoring mechanism.</para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
232
	<para>The <guilabel>Offense:</guilabel> selection shows all offenses that might be applicable to the hands the players hold. Choose among them.</para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
233
234
235
	<para>Now you can adapt the <guilabel>Total Penalty</guilabel>. This is the total sum that is moved from payers to payees. It will be evenly split between them.</para>
	<para>Depending on the type of offense, the number of payers and payees varies. The right number of players is displayed. If you select a player, &kajongg; ensures that this player only occurs once by adapting the other players.
	</para>
236
	</sect2>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
237
	</sect1>
238
239
</chapter>

240
<chapter  id="play"><title>Playing</title>
241
242
243
	<para>At any time, you can enable or disable the Demo Mode. In Demo Mode, the computer will play for you. If no game is currently
	  played, a new game will be started with the last used ruleset.
	</para>
244
        <sect1 id="robotplay">
245
246
        <title>Play against the computer</title>
         <para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
247
            First you will get a login dialog. Enter the game server you want to connect to and your user name. If you choose the special entry <guilabel>Local Game</guilabel>,
248
            you only need to enter your name (or accept the proposed name) and the wanted ruleset. This will immediately start a local game where you play
249
250
            against 3 robot players. However if suspended games exist, they will be displayed in a list. You can then select the game you want to continue with
	    or start a new game.
251
252
        </para>
        </sect1>
253
        <sect1 id="humanplay">
254
255
256
257
258
        <title>Play with friends</title>
        <para>
	   If you want to play against other real people, you need a game server to which all players, including yourself, need to connect. Do that by
            selecting any other host or by manually entering a new host name and by specifying your password for that host. The last used password will be
            proposed.
259
        </para><para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
260
261
	    The easiest way is to use the game server at <literal>kajongg.org</literal>. &kajongg; will show this one in the list of possible game servers.
	    Please note that this server only offers a game server but no web page or any other services.
262
263
        </para><para>
	  If you do not have an account on the game server with the name you entered, you will be asked if you want to open an account. If you say yes, you will get a
264
	  new dialog where you can enter the wanted password twice. Your account will be created automatically.
265
        </para><para>
Yuri Chornoivan's avatar
Yuri Chornoivan committed
266
            After a successful login onto the game server, you will get a list of tables with available seats on that game server. Join a table or allocate a new table.
267
268
269
270
271
            If you allocate a new table, wait until more seats are taken by other players. You can start the game on a table you allocated at any time, the seats
            not taken will be filled by robot players.
        </para><para>
	  The table list also shows the name of the ruleset played on that table. The ruleset and its name are sent to the game server by the player initiating the table.
	  If you have an identical ruleset, the table shows your name for the ruleset - this might be helpful if the table initiator speaks another language and named
272
	  the ruleset differently. Also, if the name of your local ruleset is displayed, it is displayed in black. If however you have no identical ruleset, the name
273
274
	  appears in red, and you can use the button <guibutton>Compare</guibutton> to compare it with your own rulesets.
        </para><para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
275
	   If you do not use <literal>kajongg.org</literal> or any other existing game server, you can start your own &kajongg;  game server in two different ways:
276
            <itemizedlist><listitem><para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
277
	         connect to the server <literal>localhost</literal>. This is your own computer. If you do this and no game server is running, it will be started automatically. And when
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
278
		 you stop playing, the server will be stopped too. This differs from selecting <guilabel>Local Game</guilabel>, the latter does not allow connections from other computers.
279
280
            </para></listitem><listitem><para>
                manually start a server on any computer you want. All you need to do is go to a command line and start
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
281
            the program <command>kajonggserver</command>. Entering <command>kajonggserver --help</command>
282
            will show you all available options like changing the default port. This server will run until you kill it.
283
284
            </para></listitem></itemizedlist>
        </para><para>
285
            In both cases you need to tell the other players  how they can reach your game server. They need the &URL; or simply an IP address and the port your server is
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
286
            listening on. This might be something like <literal>mypc.dyndns.org:8301</literal> where <literal>8301</literal> is the port. Of course you need to configure your firewall such that the remote
287
            player can reach that port. The communication will be encrypted.
288
	    </para><para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
289
	    For the port number, please see <menuchoice><guimenu>Help</guimenu> <guimenuitem>About &kajongg;</guimenuitem></menuchoice>. The Protocol version is the port number. For &kajongg; 17.04 this is 8301.
290
	    If the player enters no port for the wanted game server, the client computes the port in the same way.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
291
	    So if a computer runs several game servers with different protocol versions, you should normally reach the correct game server automatically.
292
	    Anyway the game server and the client will make sure that their versions are compatible and warn you otherwise.
293
         </para><para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
294
295
            If you encounter possible bugs, you might want to use the option <command>kajongg --debug=traffic</command>. This will show you, on the console where the game server has been started,
            what messages are flowing between the game server and the clients. For more options, see <command>kajongg --help</command>
296
        </para>
297
        <sect2 id="playing-caveats">
298
299
300
301
302
303
        <title>Caveats</title>
            <itemizedlist><listitem><para>
                If you want to make sure nobody can cheat none of the human players should have access to the computer  the game server is running on. Of course you can never avoid that two players help each other because you cannot know what they really are doing. Two players might even be one and the same person.
            </para></listitem></itemizedlist>
        </sect2>
        </sect1>
304
<sect1  id="gamerules"><title>Game rules</title>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
305
<para>Worldwide, many different game variants exist. Currently, &kajongg; supports two variants of Classical Chinese, one as played in Germany and one as played in Great Britain.</para><para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
306
  This description does not go into details and as such matches both variants.</para><para>
307
308
309
310
311
  However most of the basic rules are the same in most variants.</para>
  <para>Since the program &kajongg; knows how to play, this description only contains things that might not be obvious.</para>
  <para>If you want to learn Mah Jong in more detail, please consult the <link linkend="bibliography">bibliography</link>.</para>
<sect2 id="gamerules-aim">
  <title>The aim of the game</title>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
312
  <para>Each player tries to collect tiles such that she has a winning hand. On achieving this, she calls <quote>Mah Jong</quote>. In a winning hand, the tiles are normally grouped into five melds: Four
Yuri Chornoivan's avatar
Yuri Chornoivan committed
313
314
    melds with three or four tiles each and a fifth meld consisting of two equal tiles. A normal meld has three or four identical tiles (called Pung
    and Kong respectively) or three successive tiles like Bamboo 3, Bamboo 4, Bamboo 5 (called Chow).</para>
315
  </sect2>
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
  <sect2>
    <title>The course of the game</title>
    <para>
      Initially, the player with the East wind (as indicated on the wall) has one more tile than the other players. East begins by discarding an unwanted tile.
      </para>
    <para>
      Whenever a tile has been discarded, other players can claim it by saying what they can complete with that tile (Chow, Pung, Kong, Mah Jong).
      Only the next player can claim a Chow - the other claims are possible for all players. A meld completed by a claim will be exposed - made visible
      to all players.
    </para><para>
      If nobody claims the discarded tile, the next player, South (and then West and North) gets a tile from the wall and discards an unwanted tile.</para>
      <para>There are several rules about when a Pung can be extended to a Kong (by claiming the forth tile or by getting it from the wall) - these rules
	are not explained here. But &kajongg; of course knows them and makes sure they are respected. If a Kong is declared, the player automatically gets
	a replacement tile from the wall - otherwise it would not be possible to build the five melds as mentioned above.
      </para>
    </sect2>
    <sect2>
      <title>Year, Round and Hand</title><para>
      When a player claims Mah Jong or we end up in a draw, a hand is completed. Now, except for draws, the winds rotate among the players.
      This is repeated until every player once had every wind. This entire unit is called a round. An entire game, also called year, consists of four such rounds:
      East wind round, South wind round, West wind round, North wind round. The wind of a round is also called prevailing wind, it can result in
	higher scores.</para>
	<para>So a full game (a year) consists of at least 16 hands. Since the winds do not rotate for draws or when the East player says Mah Jong, a higher
	  number of hands is normally needed for a full game.
    </para></sect2><sect2><title>Bonus tiles</title>
    <para>A game can contain eight bonus tiles (unless the rules exclude them). They are exposed separately on the right side of the player region
      as they are never used for building melds. They do however generate bonus points.</para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
343
      <para>If a player gets a bonus tile, she will automatically also get a replacement tile from the wall. And a bell rings.</para></sect2>
344
345
      <sect2><title>Scoring</title><para>
	At the end of a hand, the score for each player is computed. First, basis points are counted like 2 points for a simple exposed pung or 20 points
346
347
	for winning. Next, another set of rules is applied - those rules can double the points like one double for a meld of dragons. When the score for
	each hand is known, differences are paid between players - while the winner gets its full score paid from all other players. East always gets and
348
349
350
	  pays twice her score.</para>
	  <para>Of course &kajongg; knows about all applicable rules but a good player knows what combinations get what score so she can optimize.
	    While learning it is recommended to activate the window <guimenuitem>Explain Scores</guimenuitem>.</para>
351
	  <para>The exact scoring rules often vary - in &kajongg; you are free to change them with the <link linkend="ruleset-options">the ruleset editor</link>.</para>
352
	  <para>The ruleset editor also shows you all available rules and their meaning. Place the mouse over them and for the
353
354
355
356
357
	    more exotic rules help text will appear.</para>
	</sect2>
</sect1>
<sect1 id="playing-play">
        <title>How to play with &kajongg;</title>
358
359
360
361
362
363
        <para>
            You will be prompted for what you want to do. This is a little dialog which appears either on the right or at the bottom depending on the size of the window. If
            you make it broader than  high, the dialog appears on the right. Sometimes the dialog will have a timeout - when it is over, the first possible answer is automatically selected for you.
            This timeout is configurable in the Ruleset Editor, under <guilabel>Options</guilabel>, <guilabel>Claim Timeout</guilabel>.
            All players should have the same timeout, that is why this is part of the ruleset.
          </para><para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
364
            If you need to select a tile from your hand, you can move between tiles using the &Right; and &Left; arrow keys or the letters <keycap>h</keycap> and <keycap>l</keycap> on your keyboard. Of course you can use the mouse too.
365
366
367
368
          </para><para>
	    You can discard a tile by using the keyboard the same way as for all actions. Alternatively, you can use the mouse and move the tile from your hand into the
	    discard area (the interior of the walls). The placement of the tile in the discard area will still be done by the computer - because the placement should be the same for
	    players.
369
370
          </para><para>
          Often, the dialogs will offer choices which are not really applicable like calling Pung when you do not have the needed tiles. This is intended - just like in a real game.
371
	  But you can configure impossible choices away: Disable <guilabel>Show only possible actions</guilabel> on the <guilabel>Play</guilabel> page of the settings dialog.
372
373
374
375
376
377
          </para><para>
            Discarded tiles are placed randomly between the walls. Some game variants define where the tiles should be placed, this is not yet configurable however. When it becomes configurable, it will be part of the ruleset.
        </para>
	</sect1>
</chapter>

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
378
379
<chapter id="interface"><title>Interface Overview</title> <!-- do not change this! -->
<!-- This section has to do with menubar. Describe every single entry in order. Use <variablelist> and <varlistentry>. Split the chapter into sections using <sect1(2,3)> for better viewing.-->
380

381
382
383
<sect1 id="menu">
<title>Menu Items</title>

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
384
385
386
		<variablelist>
			<varlistentry id="game-menu-scoreGame">
				<term><menuchoice>
387
					<shortcut><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></shortcut>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
388
389
390
					<guimenu>Game</guimenu>
					<guimenuitem>Score Manual Game</guimenuitem>
				</menuchoice></term>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
391
				<listitem><para><action>Only score a manually played game.</action></para><para>You can load an old game or start a new game. By default only pending (&ie; unfinished) games are shown in the selection list. You can optionally show all games including finished games. Here you can also delete games.</para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
392
393
394
			</varlistentry>
                        <varlistentry  id="game-menu-play">
                                <term><menuchoice>
395
					<shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></shortcut>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
396
397
398
                                        <guimenu>Game</guimenu>
                                        <guimenuitem>Play</guimenuitem>
                                </menuchoice></term>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
399
                                <listitem><para><action>Play with others (people and computers)</action>.</para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
400
401
402
                        </varlistentry>
                        <varlistentry  id="game-menu-abort">
                                <term><menuchoice>
403
					<shortcut><keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo></shortcut>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
404
                                        <guimenu>Game</guimenu>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
405
                                        <guimenuitem>Abort Game</guimenuitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
406
                                </menuchoice></term>
Yuri Chornoivan's avatar
Yuri Chornoivan committed
407
                                <listitem><para><action>Abort the current game. If it was a manual game with scoring only, you can resume it later. If you played using &kajongg;, the game is not yet resumable.</action></para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
408
409
410
                        </varlistentry>
			<varlistentry>
				<term><menuchoice>
411
					<shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></shortcut>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
412
					<guimenu>Game</guimenu>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
413
					<guimenuitem>Quit &kajongg;</guimenuitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
414
				</menuchoice></term>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
415
				<listitem><para><action>Quits</action> &kajongg;.</para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
416
			</varlistentry>
Burkhard Lück's avatar
Burkhard Lück committed
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
			<varlistentry id="view-chat">
				<term><menuchoice>
					<shortcut><keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo></shortcut>
					<guimenu>View</guimenu>
					<guimenuitem>Chat</guimenuitem>
				</menuchoice></term>
				<listitem><para><action>Chat</action></para>
				<screenshot>
					<screeninfo>Chat Window</screeninfo>
					<mediaobject>
						<imageobject>
						<imagedata fileref="chat.png" format="PNG"/>
						</imageobject>
						<textobject>
						<phrase>Chat Window</phrase>
						</textobject>
					</mediaobject>
				</screenshot>
				<para>
				Lets you chat with the other players.
				</para></listitem>
			</varlistentry>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
439
			<varlistentry id="view-scoretable">
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
440
                                <term><menuchoice>
441
					<shortcut><keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo></shortcut>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
442
443
444
                                        <guimenu>View</guimenu>
                                        <guimenuitem>Score Table</guimenuitem>
                                </menuchoice></term>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
445
                                <listitem><para><action>Score Table</action></para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
446
447
448
449
450
451
452
453
454
455
456
                                <screenshot>
                                        <screeninfo>Score Table</screeninfo>
                                        <mediaobject>
                                                <imageobject>
                                                <imagedata fileref="scoretable.png" format="PNG"/>
                                                </imageobject>
                                                <textobject>
                                                <phrase>Screenshot</phrase>
                                                </textobject>
                                        </mediaobject>
                                </screenshot>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
457
    <para>
458
459
460
	Show the score table. Round/Hand are the current round (East, South, West, North) followed by a count of the hands played in that round.
	The winner has a green background for her values.
	The Payments show how much the player paid to or received from all other players with this hand.
461
	The Balance shows the current balance for all players.
462
463
464
	The Chart shows the development of the balance values.
	The hints give you more details: They show all rules that have been applied to this hand. Just move the mouse over the value you are interested in.</para><para>
        The lower part shows the used ruleset. Between the score table and the used ruleset you can find a splitter letting you change the relative sizes of both parts.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
465
466
467
468
                        </para></listitem>
                        </varlistentry>
			<varlistentry id="view-explain-scores">
				<term><menuchoice>
469
					<shortcut><keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo></shortcut>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
470
471
472
					<guimenu>View</guimenu>
					<guimenuitem>Explain Scores</guimenuitem>
				</menuchoice></term>
473
				<listitem><para><action>Explain Scores</action></para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
474
475
476
477
478
479
480
481
482
483
484
				<screenshot>
					<screeninfo>Score Table</screeninfo>
					<mediaobject>
						<imageobject>
						<imagedata fileref="explain.png" format="PNG"/>
						</imageobject>
						<textobject>
						<phrase>Score Table</phrase>
						</textobject>
					</mediaobject>
				</screenshot>
485
				<para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
486
487
488
				Explains how the score for the current hand was computed.
				</para></listitem>
			</varlistentry>
Burkhard Lück's avatar
Burkhard Lück committed
489
			<varlistentry>
490
				<term><menuchoice>
491
					<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>F</keycap></keycombo></shortcut>
492
					<guimenu>View</guimenu>
Burkhard Lück's avatar
Burkhard Lück committed
493
					<guimenuitem>Full Screen Mode</guimenuitem>
494
				</menuchoice></term>
Burkhard Lück's avatar
Burkhard Lück committed
495
				<listitem><para><action>Switches between full screen mode and normal mode.</action></para></listitem>
496
			</varlistentry>
497

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
498
499
500
501
502
			<varlistentry>
				<term><menuchoice>
					<guimenu>Settings</guimenu>
					<guimenuitem>Players</guimenuitem>
				</menuchoice></term>
503
504
505
506
507
508
				<listitem><para><action>Add, modify and delete players.</action></para>
				<para>The passwords in this table are those used by default when logging onto
				  a game server. Changing the password you initially chose
				  for a game server is not yet really helpful because there is no way yet for you to also change
				  your password on the game server. You would have to ask the administrator of the game
				  server to do that for you directly in the data base.</para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
509
			</varlistentry>
510
511
512
513
514
515
516
517
			<varlistentry>
				<term><menuchoice>
					<guimenu>Settings</guimenu>
					<guimenuitem>Rulesets</guimenuitem>
				</menuchoice></term>
				<listitem><para><action>Customize rulesets.</action></para>
				<para>Use the Ruleset Editor to customize rulesets. For details see <link linkend="ruleset-options">here</link>.</para></listitem>
			</varlistentry>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
518
519
			<varlistentry>
				<term><menuchoice>
520
					<shortcut><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></shortcut>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
521
522
523
524
525
					<guimenu>Settings</guimenu>
					<guimenuitem>Change Visual Angle</guimenuitem>
				</menuchoice></term>
				<listitem><para><action>Changes the viewing angle of the tiles counterclockwise.</action></para></listitem>
			</varlistentry>
526
527
			<varlistentry>
				<term><menuchoice>
528
					<shortcut><keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo></shortcut>
529
530
531
532
533
					<guimenu>Settings</guimenu>
					<guimenuitem>Demo Mode</guimenuitem>
				</menuchoice></term>
				<listitem><para><action>Enables or disables the Demo Mode. See <link linkend="play">here</link> for details.</action></para></listitem>
			</varlistentry>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
534
		</variablelist>
535
536

<para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
537
Additionally &kajongg; has the common &kde; <guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
538
539
menu items, for more information read the sections about the <ulink url="help:/fundamentals/menus.html#menus-settings"
>Settings Menu</ulink> and <ulink url="help:/fundamentals/menus.html#menus-help">Help Menu</ulink>
540
541
542
of the &kde; Fundamentals.
</para>

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
543
544
</sect1>
</chapter>
545

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
546
547
548
549
550
551
<chapter id="configuration"><title>Game Configuration</title> <!-- do not change this! -->
<!--This section describes configuration &GUI;. If your game is configured using menubar exclusively, please remove this section.-->
<screenshot>
<screeninfo>Configure Dialog</screeninfo>
	<mediaobject>
	  <imageobject>
552
	    <imagedata fileref="config_play.png" format="PNG"/>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
553
554
555
556
557
558
559
	  </imageobject>
	  <textobject>
	    <phrase>Configure Dialog</phrase>
	  </textobject>
	</mediaobject>
</screenshot>

Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
560
<para>The menu entry <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure &kajongg;...</guimenuitem></menuchoice> opens the <guilabel>Configure - &kajongg;</guilabel> dialog.</para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
561
<para>If you press the <guibutton>Cancel</guibutton> button  here, all of your configuration changes will be reverted, including everything you did with the ruleset editor.</para>
562
563
<para>
  You can also select the different tabs with the keyboard: <keycombo action="simul">&Ctrl;<keycap>1</keycap></keycombo> selects
564
  the first tab <guilabel>Play</guilabel> options, <keycombo action="simul">&Ctrl;<keycap>2</keycap></keycombo> selects
565
566
  the second tab, and so on.
</para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
567

568
<sect1 id="play-options"><title>Play options</title>
569
		<variablelist>
570
571
			<varlistentry>
				<term>
572
					<guilabel>Show tile shadows</guilabel>
573
574
575
576
577
578
579
				</term>
				<listitem><para>
				This shows tiles with borders and shadows. Also there is some space between tile rows, and the wall tiles are shown such that you can see
				that the wall  is two or three tiles high. So if you disable this option, you have a simpler display with slightly larger tiles. This may be helpful
				for small screens.
</para></listitem>
			</varlistentry>
580
581
582
583
584
585
586
			<varlistentry>
				<term>
					<guilabel>Rearrange undisclosed tiles to melds</guilabel>
				</term>
				<listitem><para>
				This groups melds in the hand.
				 Sometimes the grouping might not be like you want it, so you might prefer to have no grouping at all, just like in a real world game.
587
588
589
590
591
592
593
</para></listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<guilabel>Show only possible actions</guilabel>
				</term>
				<listitem><para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
594
				When playing, show only possible actions like <quote>No claim</quote> or <quote>Pung</quote>.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
595
596
597
598
599
600
601
602
</para></listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<guilabel>Propose what to do</guilabel>
				</term>
				<listitem><para>
				Whenever you have a choice of actions like claiming a tile or not or like choosing which tile to discard, &kajongg; can help you by making a proposal.
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
</para></listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<guilabel>Use sounds if available</guilabel>
				</term>
				<listitem><para>
		This lets you hear discards and claims. If other players recorded sound files with their own voice, you can hear them.
</para></listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<guilabel>Let others hear my voice</guilabel>
				</term>
				<listitem><para>
		If you recorded sound files with your voice this option will let the other players
		hear your discards and claims with your voice.
620
621
622
623
</para></listitem>
			</varlistentry>
			<varlistentry>
				<term>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
624
					<guilabel>Animation speed:</guilabel>
625
626
				</term>
				<listitem><para>
627
		Define how fast the tiles should move around. If you move the slider to the rightmost position, tile movement is not animated:
628
		the tiles will simply change place.
629
630
631
632
633
</para></listitem>
			</varlistentry>
		</variablelist>

	<sect2><title>Sound</title>
634
	<para>
635
636
637
638
639
640
641
		Playing gives you a much nicer experience if you hear players claim tiles and announce discards. It also makes playing
		easier because you can concentrate on your own tiles, you do not have to watch what others discard.
	</para>
	<para>
		&kajongg; comes with voices for different players. It automatically assigns voices to players. For every language there should be
		four voices, preferably two male and two female. &kajongg; tries to use voices in the same language &kajongg; runs in. If it
		finds no voices in that language, &kajongg; will fallback to other languages, using the same fallback languages you defined for
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
642
		&kajongg; (see <menuchoice><guimenu>Help</guimenu> <guimenuitem>Switch Application Language</guimenuitem></menuchoice>). If no
643
644
645
646
		voice files exist yet for your language, you are invited to record and contribute them to &kajongg;.
	</para>
	<para>
		</para><itemizedlist><listitem><para>
647
		This is how you can generate voices yourself. There is a separate folder for every voice. Please note that those folders may
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
648
		be somewhere else on your system, they depend on how &kde; was installed. Only the part starting with <filename class="directory">kajongg</filename>
649
		is always the same. There are two groups of voices
650
651
		with different places in the file system:
		<itemizedlist><listitem><para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
652
			Predefined voices for every language. They live in a folder like <filename class="directory">/usr/share/kajongg/voices/LANG</filename> where
653
			LANG is the code for your language. The voice directories directly under <filename class="directory">.../kajongg/voices/</filename> are the US-english
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
654
			versions. Predefined voices are randomly assigned to players. Those voices have names like <quote><literal>male1 male2 female1 female2</literal></quote> but those names do not matter, the user will never see them.
655
656
657
658
		</para></listitem><listitem><para>
			User voices can be defined for a specific user.
			If &kajongg; makes use of such a voice, it can automatically be transferred to other players
			over the internet.
659
660
			Those voices live in a folder like <filename class="directory">~/.local/share/apps/kajongg/voices/</filename>.
			So if your login name is joe, this might be <filename class="directory">/home/joe/.local/share/apps/kajongg/voices/joe/</filename>.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
661
			The folder <filename class="directory">voices/</filename> might not yet exist - if so, create it.
662
663
		</para></listitem></itemizedlist>
		</para></listitem><listitem><para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
664
		Now that you know where to place your new voice, generate a new folder for it.
665
		</para></listitem><listitem><para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
666
			In that subfolder, you can place the sound files. They have to be encoded with the <ulink url="https://xiph.org/vorbis/">Ogg Vorbis</ulink> audio compressor, the file names need to
667
668
669
670
671
672
			have the extension <filename class="extension">.ogg</filename>.
			A single file has a name like <filename>s3.ogg</filename> - this is Stone 3. You should define such files for all tiles and
			for all claims and announcements. But if a sound file is missing, nothing bad happens - you just will not hear that sound. Fallback
			to other voices or languages only works for entire voices, not for single sound files.
		</para></listitem><listitem><para>
		After having defined all sound files for a predefined voice, please make sure that the &kajongg; process has write permission in
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
673
		the new voice folder. Start &kajongg; and test the voice. After everything is OK, you can revoke write permission (and you should
674
675
676
677
678
679
680
681
682
683
		do so for predefined voices). &kajongg; will automatically generate a file named <filename>md5sum</filename> containing a checksum
		over all sound files. Whenever you change, add or delete a sound file for a voice, &kajongg; will try to rewrite that file.
	</para></listitem></itemizedlist>
	<para>
		Please make the length of the sound short but speak clearly - this game can be played very fast when you get used to it. It is easier
		if you first write down a list with everything that should be spoken. Do not read it as a sequence of items, try to pronounce each
		item as if it were the only one and as you would when playing. Leave room between the items. Reading this needs a little practicing.</para>
	<para>
		This is just one possibility to create the sound files:
	</para><para><itemizedlist><listitem><para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
684
		Record a sound file with the program <command>qarecord</command>, save it in the <acronym>WAV</acronym> format.
685
686
687
688
		In this single sound file, speak all of the sounds.
	</para></listitem><listitem><para>
		Edit that file with the sound editor <command>audacity</command>. In that editor, use the mouse to mark a range of the sound waves.
		The editor will play that part. Repeat until you have the correct part selected.
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
689
690
		This may be easier if you <menuchoice><guimenu>View</guimenu> <guimenuitem>Zoom In</guimenuitem></menuchoice>.
		Use the menu command <menuchoice><guimenu>File</guimenu> <guimenuitem>Export Selection</guimenuitem></menuchoice> and save in the <filename class="extension">.ogg</filename> format.
691
692
693
		Under <guilabel>Options</guilabel>, choose low quality - this is sufficient and even
		wanted because this reduces the time to transfer the sounds to the other players.
	</para></listitem></itemizedlist></para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
694
	<para>The following are the names of the files that you should generate. Always append <filename class="extension">.ogg</filename> to them:</para>
695

696
697
698
699
700
<table>
<title>Sound file names</title>
<tgroup cols="2">
<tbody>
<row>
701
<entry>&s1; .. &s9;</entry><entry>Stone 1 to Stone 9</entry>
702
703
</row>
<row>
704
<entry>&b1; .. &b9;</entry>
705
706
707
<entry>Bamboo 1 to Bamboo 9</entry>
</row>
<row>
708
<entry>&c1; .. &c9;</entry>
709
710
711
<entry>Character 1 to Character 9</entry>
</row>
<row>
712
<entry>&we; &ws; &ww; &wn;</entry>
713
714
715
<entry>The winds East, South, West, North</entry>
</row>
<row>
716
<entry>&db; &dr; &dg;</entry>
717
718
719
<entry>The dragons blue/white, red, green</entry>
</row>
<row>
720
<entry>&chow; &pung; &kong; &mahjongg;</entry>
721
722
723
<entry>The major claims</entry>
</row>
<row>
724
<entry>&originalcall; &violatesoriginalcall;</entry>
725
<entry>Original Call and its violation</entry>
726
</row>
727
<row>
728
<entry>&dangerousgame;</entry>
729
730
731
<entry>A player lets off a cannon (dangerous game)</entry>
</row>
<row>
732
<entry>&nochoice;</entry>
733
734
<entry>A player declares he has no choice but to play dangerous game</entry>
</row>
735
736
737
738
</tbody>
</tgroup>
</table>
	</sect2>
739
740
</sect1>

741
<sect1 id="tiles-options"><title>Tiles options</title>
742
743
744
745
746
747
748
749
750
        <screenshot>
                <screeninfo>Tileset selector</screeninfo>
                <mediaobject>
                        <imageobject>
                                <imagedata fileref="config_tiles.png" format="PNG"/>
                        </imageobject>
                        <textobject><phrase>Tileset selector</phrase></textobject>
                </mediaobject>
        </screenshot>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
751
752
753
754
755
	<para>
		Use the <guilabel>Tiles</guilabel> selector to select graphics for the tiles.
	</para>
</sect1>

756
<sect1 id="background-options"><title>Background options</title>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
        <screenshot>
                <screeninfo>Background selector</screeninfo>
                <mediaobject>
                        <imageobject>
                                <imagedata fileref="config_background.png" format="PNG"/>
                        </imageobject>
                        <textobject><phrase>Background selector</phrase></textobject>
                </mediaobject>
        </screenshot>
	<para>
		Use the <guilabel>Background</guilabel> selector to select a background graphic for the game.
        </para><para>Some backgrounds like the Chinese Landscape need some time to load. If you feel that
                the program should start faster or that resizing the main window takes too long, you might try some
                other background.
	</para>
</sect1>

<sect1 id="ruleset-options"><title>Ruleset Editor</title>
			<screenshot>
				<screeninfo>Ruleset Editor</screeninfo>
				<mediaobject>
					<imageobject>
						<imagedata fileref="ruleseteditor.png" format="PNG"/>
					</imageobject>
					<textobject><phrase>Ruleset Editor</phrase></textobject>
				</mediaobject>
			</screenshot>
			<para>
				Use the Ruleset Editor to customize rulesets. Predefined rulesets are shown in an italic font, customized rulesets have a normal font. Predefined rulesets cannot be changed by the user in any way, however an update of &kajongg; might. Customized rulesets will never be affected by an update.
			</para><para>
				When starting a new game, you will be able to select a ruleset for that game. All rulesets defined in the ruleset editor can be used. The ruleset is saved together with the game, so you can always change rulesets here - your changes will only affect future games.
			</para>
789
790
791
792
			<sect2><title>Rule, Points, x2, Limits</title><para>
				Simply double click on whatever you want to change.
				If all values are cleared, this rule  will have no influence on the game.
				Rules cannot be deleted.</para>
793
			</sect2>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
794
			<sect2><title>Copy and Remove</title><para>
795
				You can copy and remove entire rulesets.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
796
			</para><para>
797
				 Again this can even be done if existing games use this ruleset since every game has its own ruleset copy. You can view rulesets for old games: <link linkend="game-menu-scoreGame">Load</link> the old game and <link linkend="view-explain-scores">show its score table</link>.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
798
799
			</para>
			</sect2>
800
801
802
803
804
805
806
807
808
809
810
811
			<sect2><title>Compare</title><para>
			<screenshot>
				<screeninfo>Ruleset Comparator</screeninfo>
				<mediaobject>
					<imageobject>
						<imagedata fileref="differ.png" format="PNG"/>
					</imageobject>
					<textobject><phrase>Ruleset Comparator</phrase></textobject>
				</mediaobject>
			</screenshot>
				You can select this command when an entire ruleset is selected. It lets you compare the selected ruleset against any other ruleset.
			</para></sect2>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
812
813
814
815
816
</sect1>

<sect1 id="default-keybindings">
<title>Default Keybindings</title>

Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
817
818
<!-- TODO: not yet implemented
<para>The menu entry <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure ...</guimenuitem></menuchoice> allows you to change the default keyboard bindings.</para> -->
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
819
820

<para>
821
The default shortcuts are as follows:
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
</para>

<para>
<variablelist>

<varlistentry>
<term><keycap>F1</keycap></term>
<listitem>
<para>
Displays this handbook.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></term>
<listitem>
<para>
Score a manual game.
</para>
</listitem>
</varlistentry>

<varlistentry>
846
<term><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></term>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
847
848
<listitem>
<para>
849
Play a game with friends or computer players.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo></term>
<listitem>
<para>
Abort the current game.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></term>
<listitem>
<para>
Quit the program.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo></term>
<listitem>
<para>
Show the score table.
</para>
</listitem>
</varlistentry>

881
882
883
884
885
886
887
888
889
<varlistentry>
<term><keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo></term>
<listitem>
<para>
Show a chat window.
</para>
</listitem>
</varlistentry>

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
890
891
892
893
894
895
896
897
898
<varlistentry>
<term><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></term>
<listitem>
<para>
Change the viewing angle.
</para>
</listitem>
</varlistentry>

899
900
901
902
903
904
905
906
907
<varlistentry>
<term><keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo></term>
<listitem>
<para>
Enables or disables the Demo Mode.
</para>
</listitem>
</varlistentry>

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
908
909
910
911
<varlistentry>
<term><keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo></term>
<listitem>
<para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
912
What's this? help.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
913
914
915
916
917
918
919
920
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><keycombo action="simul">&Ctrl;&Shift;<keycap>F</keycap></keycombo></term>
<listitem>
<para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
921
Full Screen Mode.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
922
923
924
925
926
927
928
929
930
931
</para>
</listitem>
</varlistentry>

</variablelist>
</para>

</sect1>
</chapter>

932
<appendix id="problems"><title>Known problems</title>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
933
934
935
936
        <itemizedlist>
                <listitem><para>In playing mode, penalties are not yet possible.</para></listitem>
                <listitem><para>The computer players are still rather stupid.</para></listitem>
        </itemizedlist>
937
</appendix>
938

939
<appendix id="future"><title>Possible future features</title>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
940
941
942
        <itemizedlist>
                <listitem><para>Add more rulesets. This should optionally be done by people using those rulesets regularly.</para></listitem>
        </itemizedlist>
943
</appendix>
944

945
 <appendix id="faq"><title>Frequently asked questions</title> <!-- do not change this! -->
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
946
947
948
949
950
<!--This chapter is for frequently asked questions. Please use <qandaset> <qandaentry> only!-->
<qandaset>
<!--Following is a standard list of FAQ questions.-->
        <qandaentry>
                 <question><para>I want to change the way this game looks. Can I? </para></question>
951
                 <answer><para>Yes. To change the way &kajongg; looks use the menubar to open the <link linkend="configuration">configuration utility</link>.</para></answer>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
952
953
954
        </qandaentry>
        <qandaentry>
                 <question><para>Can I use the keyboard to assign tiles to players?</para></question>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
955
                 <answer><para>Yes. See  <link linkend="enterhand-tiles">Have &kajongg; compute the score</link>.</para></answer>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
956
957
        </qandaentry>
<!--Please add more Q&As if needed-->
958

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
959
</qandaset>
960
</appendix>
961

962
<appendix id="credits"><title>Credits and License</title> <!-- do not change this! -->
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
963
964
<!--This chapter is for credits and licenses.-->
	<para>
965
		&kajongg; for &kde;
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
966
967
968
	</para>

	<para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
969
		Program Copyright &copy; 2009-2017 &Wolfgang.Rohdewald; &Wolfgang.Rohdewald.mail;
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
970
971
	</para>
	<para>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
972
		Documentation Copyright &copy; 2009-2017 &Wolfgang.Rohdewald; &Wolfgang.Rohdewald.mail;
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
973
	</para>
974

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
975
976
977
978
<!-- !!!do not change ANYTHING after this line!!!! -->
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
&underGPL;
979

980
981
982
</appendix>

<appendix id="bibliography">
Yuri Chornoivan's avatar
Yuri Chornoivan committed
983
<title>Bibliography</title>
984
985
986
987
988
989
990
        <itemizedlist>
		<listitem><para>Das Chinesische Mah-Jongg-Spiel by Uwe Martens 2005, Books on Demand GmbH, Norderstedt. This book is an excellent German reference containing everything you
		  want to know about the rules used in Germany and many other aspects of the game.</para></listitem>
                <listitem><para>The Complete Book of Mah-Jongg by A. D. Millington, 1977 (with several paperback editions up to 2003), Weidenfeld &amp; Nicolson, London.
		  This is the ultimate reference for Classical Chinese Mah Jong as played in the Western world. It can give you valuable hints about game strategies.</para></listitem>
		<listitem><para>Mah-Jong by Gwyn Headley and Yvonne Seeley, 3rd edition, 2008, A &amp; C Black Publishers Ltd., London. This book is a very easy to use reference, concentrating
		  on the rules as used in Great Britain, defined by the BMJA (The British Mah Jong Association).</para></listitem>
Friedrich W. H. Kossebau's avatar
Friedrich W. H. Kossebau committed
991
		<listitem><para><ulink url="https://en.wikipedia.org/wiki/Mahjong"></ulink></para></listitem>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
992
		<listitem><para><ulink url="https://de.wikipedia.org/wiki/Mah-Jongg"></ulink></para></listitem>
993
994
        </itemizedlist>
</appendix>
995

Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
996
<appendix id="installation">
997
<title>Installation</title>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
998
<para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
999
1000
1001
1002
For Linux: Your distribution should have it packaged for you.
</para>
<para>
For Windows: Please see <ulink url="https://www.linux-apps.com/p/1109453/"></ulink> for a Windows installer.
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1003
</para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1004
1005
<para>
If you want to download the source and install manually:
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1006
<itemizedlist>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
1007
<listitem><para> <literal>git clone https://invent.kde.org/games/kajongg.git</literal> </para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1008
<listitem><para> For Linux: <literal>cd kajongg ; mkdir build ; cd build; cmake .. &amp;&amp; make &amp;&amp; make install</literal> </para></listitem>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
1009
<listitem><para> For Windows: Please read <filename>README.windows</filename></para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1010
1011
1012
1013
1014
1015
1016
</itemizedlist>
</para>
<para>
Kajongg depends on those packages: (debian package names in parentheses)
<itemizedlist>
	<listitem><para>Python 3.5 or higher (python3)</para></listitem>
	<listitem><para>Qt5.7 or higher (python3-pyqt5 and python3-pyqt5.qtsvg)</para></listitem>
Antoni Bella Pérez's avatar
Antoni Bella Pérez committed
1017
	<listitem><para>the python bindings for Qt5 (python3-pyqt5)</para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1018
1019
        <listitem><para>the python twisted library 16.6.0 or higher (python3-twisted)</para></listitem>
        <listitem><para>sqlite3 (libsqlite3-0)</para></listitem>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1020
</itemizedlist>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1021
</para>
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1022
1023

</appendix>
1024
1025

&documentation.index;
Wolfgang Rohdewald's avatar
Wolfgang Rohdewald committed
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-omittag:t
sgml-shorttag:t
sgml-namecase-general:t
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->