Book: mark more functions static.
[gnushogi.git] / doc / gnushogi.texi
1 \input texinfo   @c -*-texinfo-*-
2
3 @c % **  Start of header.
4 @setfilename gnushogi.info
5 @settitle GNU Shogi manual
6 @c % **  End of header.
7
8 @dircategory Games
9 @direntry
10 * gnushogi: (gnushogi).          Japanese chess
11 @end direntry
12
13 @setchapternewpage odd
14
15 @c ==================================
16 @c TeX-specific macros
17 @c ==================================
18
19 @c None yet!
20
21 @c ==================================
22 @c info-specific macros
23 @c ==================================
24
25 @c None yet!
26
27 @c ==================================
28 @c Summary description and copyright.
29 @c ==================================
30
31 @ifinfo
32
33 This file describes how to use GNU shogi, 
34 a program which plays Shogi (Japanese chess).
35
36 Copyright (C) 2013 Yann Dirson and the Free Software Foundation, Inc.
37 Copyright (C) 1999 Michael C. Vanier and the Free Software Foundation, Inc.
38
39 Permission is granted to make and distribute verbatim copies of
40 this manual provided the copyright notice and this permission notice
41 are preserved on all copies.
42
43 @ignore
44 Permission is granted to process this file through TeX and print the
45 results, provided the printed document carries copying permission
46 notice identical to this one except for the removal of this paragraph
47 (this paragraph not being relevant to the printed manual).
48 @end ignore
49
50 Permission is granted to copy and distribute modified versions of this
51 manual under the conditions for verbatim copying, provided that the entire
52 resulting derived work is distributed under the terms of a permission
53 notice identical to this one.
54
55 Permission is granted to copy and distribute translations of this manual
56 into another language, under the above conditions for modified versions,
57 except that this permission notice may be stated in a translation approved
58 by the Free Software Foundation.
59
60 @end ifinfo
61
62 @c =========================================
63 @c End of summary description and copyright.
64 @c =========================================
65
66
67 @c ====================
68 @c Title and copyright.
69 @c ====================
70
71 @titlepage
72 @sp 10
73 @comment The title is printed in a large font.
74 @center @titlefont{GNU Shogi (Japanese chess)}
75 @author   Mike Vanier
76
77 @c  The following two commands start the copyright page.
78 @page
79 @vskip 0pt plus 1filll
80 Copyright @copyright{} 2013-2014 Yann Dirson and the Free Software Foundation
81 Copyright @copyright{} 1999 Michael C. Vanier and the Free Software Foundation
82
83 @end titlepage
84
85 @c ===========================
86 @c End of title and copyright.
87 @c ===========================
88
89
90 @c =========================
91 @c Top node and master menu.
92 @c =========================
93
94 @node    Top, (dir), (dir), (dir)
95 @top     GNU Shogi (Japanese chess)
96
97 @ifnottex
98 @menu
99 * Introduction::         What is GNU shogi?
100 * About shogi::          General information, rules, etc.
101 * gnushogi::             How to play GNU shogi (gnushogi).
102 * References and links:: Where to go for more information.
103 * Acknowledgements::
104 * Bugs::                 Where and how to report bugs.
105 * Index::        
106 @end menu
107 @end ifnottex
108
109 @iftex
110 This document describes GNU shogi, a program which plays Japanese chess
111 (shogi) against a human opponent.
112 @end iftex
113
114 @c ================================
115 @c End of top node and master menu.
116 @c ================================
117
118
119 @c =====
120 @c Body.
121 @c =====
122
123 @node Introduction, About shogi, Top, Top
124 @chapter Introduction
125 @cindex Introduction
126
127 GNU shogi is a program that plays shogi, the Japanese version of chess,
128 against a human (or computer) opponent.  This file describes how to use
129 GNU shogi and also gives background information about the game of shogi.
130
131 In 1994, GNU Shogi 1.2p02, then developed by Matthias Mutz, played in
132 the 5th Computer Shogi Championship, and finished 17th out of 22
133 opponents.
134
135 This file describes GNU Shogi version 1.4.1, but most of it was
136 written for version 1.3.2 by Mike Vanier
137 @email{mvanier@@cs.caltech.edu}, maintainer of GNU shogi at that time.
138
139 GNU Shogi is currently maintained by Yann Dirson
140 @email{ydirson@@free.fr}.
141
142
143 GNU Shogi is actually one program, 'gnushogi', the text-based program
144 which also contains the game-playing engine.  By default it will play
145 Standard Shogi, but can be built to play Mini Shogi (with GNU Shogi
146 1.4.x, you will need to do that explicitely using `./configure
147 --enable-minishogi', but 1.5 will make this more straightforward).
148
149 Most players will just run GNU Shogi through one of the compatible
150 graphical interfaces:
151
152 @enumerate
153 @item
154 @uref{http://www.gnu.org/software/xboard/, XBoard/Winboard}, a GUI for
155 much more than Shogi, part of the GNU Project.  While XBoard has been
156 supporting Shogi for a long time, current version only makes it easy
157 to use a Chessified western-looking set of pieces; upcoming version
158 XBoard 4.8 will allow easy usage of traditional japanese pieces.
159 Supported by GNU Shogi since version 1.5.0 only: 1.4.x and earlier
160 versions cannot talk to it.
161
162 @item
163 @uref{http://repo.or.cz/w/tagua/yd.git, Tagua}, a KDE-based GUI for
164 Chess and Shogi. Developement stopped several years ago, and it is
165 still somewhat maintained at Debian.  Probably the most sophisticated
166 and best-looking free GUI available today.
167
168 @item
169 @uref{https://alioth.debian.org/projects/omaha/, Omaha}, a generic
170 board-game GUI, supporting Shogi and other games, with currently only
171 a Gtk2-based UI.  Still under developement, but already usable for
172 casual games.
173
174 @item
175 @uref{https://github.com/pcapriotti/kaya, Kaya}, a small KDE-based GUI
176 successor to Tagua, but development of this still young program seem
177 to have stalled.
178
179 @item
180 @uref{http://ftp.gnu.org/gnu/gnushogi/, XShogi}, an X Window graphical
181 interface to gnushogi, forked off GNU XBoard years ago, and far from
182 today's UI standards. It has barely been maintained recently, while
183 XBoard has grown much and is able to play Shogi; XShogi is now
184 deprecated and will soon be retired.
185
186 The GNU Shogi distribution used to contain the 'xshogi' program, In
187 future versions, GNU Shogi will be able to use XBoard as a GUI and
188 XShogi will be retired, replaced by XBoard.  XShogi is still available
189 as a separate source archive on the GNU project FTP server.
190
191 @end enumerate
192
193
194 Disclaimer: I use the personal pronouns ``him'', ``his'' etc. to refer
195 to a shogi player regardless of gender.  That's easier than writing
196 ``his or her'' all over the place.  I don't mean to infer that women
197 don't play shogi; in fact shogi is very popular in Japan among women as
198 well as men.
199
200
201 @node    About shogi, gnushogi, Introduction, Top
202 @chapter About the game of shogi
203      
204
205 @quotation
206 ``Japanese chess cedes nothing in depth or beauty to the European
207 game... it is at least as interesting.''
208
209 --- Alexander Alekhine @*
210 (quoted in David Pritchard, @cite{The Encyclopedia of Chess Variants}) 
211
212 ``... shogi [is] by far the most complex form of chess that has ever
213 achieved widespread popularity.''
214
215 --- R. Wayne Schmittberger, @cite{New Rules for Classic Games}
216 @end quotation
217
218 Shogi is the version of chess played in Japan.  It is strikingly
219 different from standard chess (which I shall refer to henceforth as
220 ``international chess'') and also to all other regional variants,
221 because captured pieces can re-enter play on the side of the capturer.
222 This has several interesting effects on the play of the game:
223
224 @enumerate
225 @item
226 Shogi is much more complex than international chess, at least in
227 terms of the average number of possible moves per turn (estimated at
228 about 35 for chess and at about 80 for shogi).
229
230 @item
231 There are almost no draws (about 1-2% of all games in professional play).
232
233 @item
234 Exchanges complicate the play rather than simplifying it.
235
236 @item
237 There are no ``endgames'' in the standard chess sense; all pieces remain
238 in play throughout the game.  Games typically end in a race to
239 checkmate the other player before being checkmated oneself.
240
241 @item
242 Ownership of a piece is not indicated by the color of the piece;
243 instead, pieces are wedge-shaped and point towards the opponent.  The
244 name of the piece is inscribed in Kanji characters on the front of the
245 piece.
246
247 @item
248 Most importantly: it's more fun than other forms of chess :-)
249
250 @end enumerate
251
252 Shogi is extremely popular in Japan; it has been estimated that 20
253 million Japanese can play shogi, of which perhaps 1 million are active
254 players.  It is even more popular there than the game of go, Japan's
255 other favorite board game.  There are a number of professional players
256 who make a considerable amount of money playing in shogi tournaments,
257 and the game receives extensive newpaper and television coverage.
258 Despite this, the game has yet to become popular outside of Japan.  Part
259 of this is because the Kanji characters on the pieces scare away some
260 people, but mostly it's due, I think, to lack of exposure to the game
261 and to the difficulty of finding opponents.  I hope that GNU shogi will
262 help introduce shogi to a wider audience.
263
264 @ifnottex
265 @menu
266 * The rules of shogi::
267 * Sample game::
268 * Mating problems::
269 * Shogi variants::
270 * Differences between shogi and chess::
271 @end menu
272 @end ifnottex
273
274
275 @c -------------------------------------------------------
276 @c 
277 @c The rules of shogi.
278 @c
279 @c -------------------------------------------------------
280
281 @node    The rules of shogi, Sample game, About shogi, About shogi
282 @section The rules of shogi
283 @cindex  Rules
284
285 Shogi is a two-person abstract strategy board game with full information
286 (i.e. all pieces and moves are visible to both players at all times).
287 It is in the chess family, being descended from the same ancestral game
288 as international chess: the Indian game of Chaturanga.  The two players
289 are referred to as ``Black'' and ``White'', with Black moving first
290 (unlike in international chess, where White moves first), and with
291 movement alternating between the two players.  Note that ``Black'' and
292 ``White'' are just names; the pieces are not colored.  Instead, they are
293 flat, wedge-shaped pieces which point towards the opponent.  The
294 identity of a given piece is indicated by two Japanese Kanji characters
295 on each piece.  In fact, only the top character is needed to identify
296 the piece and thus only the top character is used in shogi diagrams.  I
297 will use alphabetical equivalents in the diagrams here; to see what the
298 Kanji characters look like, start up a graphical interface
299 (@pxref{Introduction}) and compare the starting setup there with the
300 starting setup in this file (@pxref{The opening setup}).
301
302 The object of the game is to capture the opponent's King.  The board is
303 a grid of 9x9 uncolored squares, and pieces are placed on the squares.
304 Each player begins with 20 pieces, described in the next section.
305 Capture is by displacement, as in international chess.
306
307 @ifnottex
308 @menu
309 * The moves of the pieces::
310 * The opening setup::
311 * Promotion of pieces::
312 * Drops::
313 * Winning the game::
314 * Draws::
315 * Handicaps::
316 * Notes for chess players::
317 @end menu
318 @end ifnottex
319
320 @c The moves of the pieces.
321
322 @node       The moves of the pieces, The opening setup, The rules of shogi, The rules of shogi
323 @subsection The moves of the pieces
324 @cindex     Piece moves
325
326 Each player at the beginning of a shogi game has a total of 20 pieces of
327 eight different types.  The moves of the shogi pieces can be divided
328 into three classes: ``stepping'' pieces, that only move one square at a
329 time; ``ranging'' pieces that move any number of unobstructed squares in
330 a line, and ``jumping'' pieces that can jump over obstructing pieces to
331 reach their destination squares.  Most pieces can also promote to
332 different (usually stronger) pieces under certain circumstances (see the
333 next section).  All pieces capture the same way that they move (even
334 pawns).  The piece moves and promotions are as follows; each piece name
335 is followed by the standard piece abbreviation:
336
337 @enumerate
338
339 @item
340 The king (K).  The king can move one square in any horizontal, vertical,
341 or diagonal direction, just like the king in international chess.  The
342 king does not promote.
343
344 @item
345 The rook (R).  The rook can move any number of squares in a horizontal
346 or vertical direction.  The rook is the same as the rook in
347 international chess (except that it can promote).  A rook promotes to a
348 ``dragon king'' or ``dragon'' for short (often just referred to as a
349 ``promoted rook''), which can move as a rook or can move one square in
350 any diagonal direction.
351
352 @item
353 The bishop (B).  The bishop can move any number of squares in a diagonal
354 direction.  The bishop is the same as the bishop in international chess
355 (except that it can promote).  A bishop promotes to a ``dragon horse''
356 or ``horse'' for short (often just referred to as a ``promoted
357 bishop''), which can move as a bishop or can move one square in any
358 horizontal or vertical direction.  Note: the horse should not be
359 confused with a knight (see below), as they are two completely different
360 pieces.
361
362 @item
363 The gold general (G).  A gold general can move one square in any
364 horizontal or vertical direction, or one square in a forward diagonal
365 direction.  Gold generals do not promote.
366
367 @item
368 The silver general (S).  A silver general can move one square in any
369 diagonal direction, or one square straight forward.  A silver general
370 promotes to a gold general.
371
372 @item
373 The knight (N).  A knight can move one square straight forward followed
374 by one square to either forward diagonal, jumping over intervening
375 pieces if any.  In other words, a knight moves like its international
376 chess counterpart, but forward only.  A knight promotes to a gold
377 general.  The knight is the only jumping piece, as in chess.
378
379 @item
380 The lance (L).  A lance can move any number of squares straight forward.
381 A lance promotes to a gold general.
382
383 @item
384 The pawn (P).  A pawn can move one square straight forward.  The pawn
385 captures the same way that it moves, in contrast to international chess.
386 There is also no initial two-space move for pawns and no
387 @emph{en-passant} capture.  A pawn promotes to a gold general; a
388 promoted pawn is usually known as a ``Tokin''.
389
390 @end enumerate
391
392
393 @c The opening setup.
394
395 @node       The opening setup, Promotion of pieces, The moves of the pieces, The rules of shogi
396 @subsection The opening setup
397 @cindex     Opening setup
398
399 The opening setup for shogi is as follows:
400
401 @ifnottex
402 @verbatim
403    9    8    7    6    5    4    3    2    1
404 +--------------------------------------------+
405 | wL | wN | wS | wG | wK | wG | wS | wN | wL |  a
406 +--------------------------------------------+
407 |    | wR |    |    |    |    |    | wB |    |  b
408 +--------------------------------------------+
409 | wP | wP | wP | wP | wP | wP | wP | wP | wP |  c
410 +--------------------------------------------+
411 |    |    |    |    |    |    |    |    |    |  d
412 +--------------------------------------------+
413 |    |    |    |    |    |    |    |    |    |  e
414 +--------------------------------------------+
415 |    |    |    |    |    |    |    |    |    |  f
416 +--------------------------------------------+
417 | bP | bP | bP | bP | bP | bP | bP | bP | bP |  g
418 +--------------------------------------------+
419 |    | bB |    |    |    |    |    | bR |    |  h
420 +--------------------------------------------+
421 | bL | bN | bS | bG | bK | bG | bS | bN | bL |  i
422 +--------------------------------------------+
423 @end verbatim
424 @end ifnottex
425
426 @c The following TeX macros are taken with permission from 
427 @c "TeX for the Beginner" by Wynter Snow.
428
429 @tex
430 \def\startline{\par\nobreak\noindent}
431
432 {\obeylines\obeyspaces%
433 \gdef\beginVerbatim{\bigbreak%
434 \begingroup%
435 \parskip=0pt%
436 \obeylines\obeyspaces%
437 \let^^M=\startline%
438 \tt}}
439 \gdef\endVerbatim{\endgroup\bigbreak}
440 \beginVerbatim
441
442
443    9    8    7    6    5    4    3    2    1
444 +--------------------------------------------+     
445 | wL | wN | wS | wG | wK | wG | wS | wN | wL |  a   
446 +--------------------------------------------+     
447 |    | wR |    |    |    |    |    | wB |    |  b   
448 +--------------------------------------------+     
449 | wP | wP | wP | wP | wP | wP | wP | wP | wP |  c   
450 +--------------------------------------------+     
451 |    |    |    |    |    |    |    |    |    |  d   
452 +--------------------------------------------+     
453 |    |    |    |    |    |    |    |    |    |  e   
454 +--------------------------------------------+     
455 |    |    |    |    |    |    |    |    |    |  f   
456 +--------------------------------------------+     
457 | bP | bP | bP | bP | bP | bP | bP | bP | bP |  g   
458 +--------------------------------------------+     
459 |    | bB |    |    |    |    |    | bR |    |  h   
460 +--------------------------------------------+     
461 | bL | bN | bS | bG | bK | bG | bS | bN | bL |  i   
462 +--------------------------------------------+
463
464 \endVerbatim
465 @end tex
466
467 Here, ``b'' stands for ``black'' and ``w'' stands for ``white'', so
468 that, for instance, ``bL'' means ``black lance''.  The numbers above the
469 files and the letters to the right of the ranks represent the most
470 common notation system used for shogi by westerners (the Japanese also
471 use Arabic numerals for the files but use Japanese numerals for the
472 ranks).  
473
474
475 @c Promotion of pieces.
476
477 @node       Promotion of pieces, Drops, The opening setup, The rules of shogi
478 @subsection Promotion of pieces
479 @cindex     Piece promotion
480
481 In sharp contrast to international chess, where only pawns can promote
482 to higher-ranked pieces, most of the pieces in shogi can promote.  The
483 promoted ranks are discussed in the section on piece moves (@pxref{The
484 moves of the pieces}) but are repeated here for reference:
485
486 @table @asis
487
488 @item Pawn
489 promotes to gold general (called a `tokin' in this case only).
490
491 @item Lance
492 promotes to gold general.
493
494 @item Knight
495 promotes to gold general.
496
497 @item Silver general
498 promotes to gold general.
499
500 @item Gold general
501 does not promote.
502
503 @item Bishop
504 promotes to ``dragon horse'' or just ``horse'' for short.  The horse can
505 move as a bishop or can move one square in any orthogonal direction.
506
507 @item Rook
508 promotes to ``dragon king'' or just ``dragon'' for short.  The dragon
509 can move as a rook or can move one square in any diagonal direction.
510
511 @item King
512 does not promote.
513
514 @end table
515
516 The three ranks furthest away from each player constitute his/her
517 ``promotion zone''.  A player may, but is not required to, promote a
518 piece after making a move in which the piece begins and/or ends in the
519 promotion zone.  Thus you can promote a piece when moving the piece into
520 the promotion zone, out of the promotion zone, or entirely within the
521 promotion zone.  Promotion is mandatory in these cases:
522
523 @enumerate
524
525 @item You must promote a pawn or a lance after moving it to the last rank.
526
527 @item You must promote a knight after moving it to either of the last
528 two ranks.
529
530 @end enumerate
531
532 These forced promotions ensure that a piece cannot be moved to a square
533 from which it would have no further move.
534
535 Pieces ``dropped'' onto the board (@pxref{Drops}) always drop in the
536 unpromoted state, even if they drop into the promotion zone.
537
538
539
540 @c Drops.
541
542 @node       Drops, Winning the game, Promotion of pieces, The rules of shogi
543 @subsection Drops
544 @cindex     Drops
545
546 When a player captures a piece, that piece is not removed from play.
547 Instead, it becomes the property of the capturer and can re-enter play
548 by being placed on (almost) any vacant square during the player's move.
549 This is known as a ``drop'' and counts as a full move (in other words,
550 you can either move a piece on the board or drop a piece onto the board
551 during your move, but not both).  All pieces drop in the unpromoted
552 state.  Pieces may be legally dropped in their promotion zone, but they
553 do not promote on that turn.
554
555 There are several restrictions on drops:
556
557 @enumerate
558
559 @item A pawn may not be dropped onto a file if there is already an
560 unpromoted pawn belonging to the same player on that file.  It is legal
561 to drop a pawn on a file which contains a @emph{promoted} pawn belonging
562 to the same player, however.
563
564 @item A pawn may not be dropped to give immediate checkmate on the
565 move.  A pawn is, however, permitted to be moved on the board to give
566 immediate checkmate.  This is a curious rule, and if anyone knows the
567 reason for it I would appreciate it if they would contact me and explain
568 it to me :-)
569
570 @item A pawn or piece may not be dropped onto a square from which they
571 would have no legal move.  This means that pawns and lances may not be
572 dropped onto the last rank, and the knight may not be dropped onto the
573 last or second-to-last rank.
574
575 @end enumerate
576
577 It is entirely permissible (and often advisable) to drop a piece or pawn
578 between one's King and an attacking ranging piece.  For this reason,
579 the final checkmating move is nearly always an attack on the King from
580 an adjacent square (except for an attack by a Knight).
581
582 Captured pieces are said to be pieces ``in hand''.
583
584 The drop is the primary distinguishing feature of Japanese chess, shared
585 with no other popular chess-type game.  It gives shogi a very aggressive
586 quality, and dramatically increases the number of possible moves once a
587 few pieces have been captured.  Another interesting feature of shogi is
588 that exchanges complicate play rather than simplifying it (as in
589 international chess), because of the drop rule.
590
591
592 @c Winning.
593
594 @node       Winning the game, Draws, Drops, The rules of shogi
595 @subsection Winning the game
596 @cindex     Winning the game
597
598 A game of shogi is won by capturing the opponent's king.  In general,
599 this is done by checkmating the king: attacking the king in such a way
600 that the king cannot be defended no matter what the defending player
601 moves.  Note, though, that there is no rule that requires a player to
602 defend a king which is being attacked.  However, if he does not defend
603 his king, the opponent is entirely free to capture it on the next move,
604 thus winning the game.  As in international chess, in practice most
605 games end by resignation when one player realizes that he cannot escape
606 checkmate. 
607
608
609 @c Draws.
610
611 @node       Draws, Handicaps, Winning the game, The rules of shogi
612 @subsection Draws
613 @cindex     Draws
614
615 There are very few draws in shogi; only about 1-2% of professional games
616 end in a draw.  One reason for this is that material can never be
617 depleted as in chess, because captured pieces are constantly re-entering
618 play as a consequence of the drop rule.  In fact, most of the ways a
619 game can be drawn in chess are not allowed in shogi:
620
621 @itemize @bullet
622
623 @item Draws cannot be offered.
624
625 @item There is no fifty-move rule.
626
627 @item A stalemate counts as a win for the stalemater.  Stated otherwise:
628 if you can't move, you lose.
629
630 @item Perpetual check is illegal (see below).
631
632 @end itemize
633
634 There are only two legal ways in which a draw can occur:
635
636 @enumerate
637
638 @item A position (including the pieces in hand) occurs 4 times with the same
639 player to move (called ``Sennichite'').  However, if this is caused by
640 consecutive checks (direct attacks on the King, threatening to capture
641 it on the next move) by one side, the player giving these checks loses
642 the game.  In other words, perpetual check results in a loss for the
643 attacker who recreates the same position the 4th time.
644
645 @item Both players have moved their King into the the promotion zone (or they
646 cannot be prevented from doing so) and the Kings cannot be checkmated.
647 A King who has entered the promotion zone is known as an ``entering
648 King''; due to the forward orientation of most shogi pieces, it is very
649 hard to mate such a King.  In that case the players may decide to count
650 their pieces as follows: the King does not count, the Rook and Bishop
651 count as 5 points, and all other pieces as one point.  Promotion is
652 disregarded.  If both players have at least 24 points the game is a draw
653 (called ``Jishogi'').  If a player has less, he loses the game.
654
655 Of course, a player can refuse to count pieces when he still has mating
656 chances or chances to gain material which would affect the outcome of
657 the counting.  There is no strict rule about what to do if this is not
658 the case, but nonetheless a player refuses to count up (e.g. because he
659 does not have enough points for a draw).  It has been generally accepted
660 that in such a case the game ends and the pieces are counted after one
661 player has managed to get all his pieces protected in the promotion
662 zone.
663
664 @end enumerate
665
666 @c Handicaps.
667
668 @node       Handicaps, Notes for chess players, Draws, The rules of shogi
669 @subsection Handicaps
670 @cindex     Handicaps
671
672 Unlike international chess, shogi has a well-established handicap system
673 which is used when players of different strengths play against each
674 other.  Handicaps range from small to huge, which makes it possible for
675 weak players to play against even very strong players and have an even
676 chance of winning.
677
678 Shogi players are ranked as follows: the weakest rank is around 15
679 ``kyu'', which represents a beginner.  14 kyu is higher than 15 kyu, 13
680 kyu is higher still, and so on until you get to 1 kyu.  The next highest
681 rank is 1 ``dan'', followed by 2 dan, 3 dan and so forth.  The highest
682 amateur rank is 6 dan; professionals go up to 9 dan.  However,
683 professional ranks are not the same as amateur ranks; a professional 1
684 dan is @emph{much} stronger than an amateur 1 dan.  This system is
685 similar to that used by go players (and also other Japanese sports such
686 as karate).
687
688 A handicap consists of the stronger player playing White and removing
689 one or more pieces from his side of the board at the start of the game.
690 These pieces are permanently removed from play; they are not in hand.
691
692 The following is a list of the accepted handicaps, from weakest to
693 strongest.  The degree of the handicap, represented by the position in
694 the list, represents the difference in rank between the two players for
695 which the handicap is appropriate.  These rules are taken from the books
696 ``Shogi for Beginners'' by John Fairbairn and ``The Art of Shogi'' by
697 Tony Hoskings (@pxref{References and links}) and, I believe, represent
698 current Japanese practice.
699
700 @enumerate
701
702 @item 
703 The stronger player removes his left lance (on 1a).
704
705 @item 
706 The players play a two-game match; in the first game the stronger player
707 removes his left lance (on 1a), while in the second game he removes his
708 bishop.
709
710 @item 
711 The stronger player removes his bishop.
712
713 @item 
714 The stronger player removes his rook.
715
716 @item 
717 The stronger player removes his rook and left lance.
718
719 @item 
720 The players play a two-game match; in the first game the stronger player
721 removes his rook and left lance (on 1a), while in the second game he
722 removes his rook and bishop.
723
724 @item 
725 The stronger player removes his rook and bishop.  This is usually called
726 a ``two-piece'' handicap.
727
728 @item 
729 The stronger player removes his rook, bishop, and both lances.  This is
730 called a ``four-piece'' handicap.
731
732 @item 
733 The stronger player removes his rook, bishop, both lances, and both
734 knights.  This is called a ``six-piece'' handicap.
735
736 @item 
737 The stronger player removes his rook, bishop, both lances, both knights,
738 and both silvers.  This is called an ``eight-piece'' handicap.
739
740 @end enumerate
741
742 Another advantage of playing handicap games is that the handicaps alter
743 the optimal strategy for both players.  For instance, handicaps all have
744 their own opening lines which may bear little or no resemblance to those
745 used in non-handicap shogi.  This means that when learning handicap
746 shogi, you are essentially learning completely new games which use the
747 same equipment!
748
749 The reader may wonder how on earth a player giving an eight-piece
750 handicap, say, could possibly hope to win.  Don't forget, though, that
751 in shogi the opponent's pieces can be captured and then become part of
752 one's own army.  Thus, if the opponent plays badly enough, the number of
753 pieces will soon even out.
754
755
756 @c Notes for chess players.
757
758 @node       Notes for chess players,  , Handicaps, The rules of shogi
759 @subsection Notes for chess players
760
761 Here are a few miscellaneous things that may confuse chess players.
762 Some of these have been mentioned elsewhere, but they bear repeating.
763
764 @enumerate
765 @item There is no queen.
766
767 @item Pawns capture the same way they move.  There is no initial
768 two-space pawn move and no @emph{en-passant} move.
769
770 @item There is no special castling move.  There @emph{are} a large
771 number of possible defensive formations referred to as ``castles''
772 (@pxref{Sample game}) but there is no need for special moves to create
773 them.
774
775 @item A given piece can only promote to @emph{one} other kind of piece.
776
777 @end enumerate
778
779 @c 
780 @c Sample game.
781 @c 
782
783 @node    Sample game, Mating problems, The rules of shogi, About shogi
784 @section Sample game
785 @cindex  Sample game
786
787 @c This will have to be spruced up for the TeX version...
788
789 This game was annotated by Pieter Stouten (@pxref{References and
790 links}).  I have made some minor corrections.  Note that captures are
791 denoted by the ``x'' symbol e.g. Rx3f and drops are denoted by the ``*''
792 symbol e.g. R*3f.  Check is indicated by a ``+'' after the move,
793 e.g. R3f+.  I recommend you use a graphical interface to play along with this
794 game.  In XBoard or XShogi simply hit the ``Force Moves'' button after starting
795 up, while in gnushogi enter the word ``force'' at the prompt.  This will
796 allow you to enter moves for both sides.
797
798 Note also that the move numbering system used here is the chess-type
799 system where one move means one move by each player.  The Japanese count
800 one move made by each player as two moves.
801
802 ---------------------------------------------------------------------------
803
804 Below you will find (the English translation of) an annotated game which
805 was published in the Dutch Shogi magazine ``81'' and in the Dutch
806 beginners booklet.  It has proven to be a very useful game to explain
807 some basic principles of Shogi.  Also, it is a rather straightforward
808 game compared to professional games where in most cases very diffuse
809 middle game fights take place.
810
811    Pieter Stouten, 14th May 1990.
812
813 ---------------------------------------------------------------------------
814
815 Black: Michael Trent (1-dan).  White: David Murphy (2-dan).
816
817    1. P2f P3d  2. P2e B3c @*
818 [ This move is necessary, as otherwise white can exchange pawns: 3. P2d
819 Px2d 4. Rx2d.  He would thus get a pawn in hand and open up his rook
820 file. ]
821
822    3. P7f P4d @*
823 [ White closes the bishop diagonal again.  He plans to play ranging rook
824 (the rook goes to 5b, 4b, 3 or 2b; a defensive strategy) and in that
825 case he'd better avoid an exchange of bishops.  One of the reasons is
826 that he will have problems developing his pieces without leaving holes
827 for bishop drops. ]
828
829    4. S4h R3b  5. P3f S4b  6. K6h K6b @*
830 [ In general the rook plays an important role in the attacks.  It is
831 wise to move the king away from the area where the initial fights will
832 be and both players act according to the Shogi proverb ``keep the rook
833 and king apart''. ]
834
835    7. K7h K7b  8. P5f P5d  9. G4i-5h G4a-5b @*
836 [ Both players use their second gold general to build their castle. ]
837
838    10. S6h @*
839 [ In itself this move is not bad.  However, it will become clear that
840 black plans a quick attack and in that case it is wiser to omit this
841 move. ]
842
843    10... S5c  11. P1f P1d @*
844 [ The advance of the edge pawns must be timed very well.  The remark at
845 black's tenth move applies here too: this move is good if black wants to
846 play a slow game, because it eliminates a future B1e. ]
847
848    12. P4f K8b  13. N3g S7b @*
849 [ Black develops his knight in order to start an attack over the second,
850 third and fourth files.  White strengthens his king's position and
851 awaits the attack.  He aims at a counterattack as soon as black has
852 broken through into the white camp.  Probably white's breakthrough will
853 take place later, but he has good compensation in the form of a stronger
854 castle.  This theme occurs very often in static rook versus ranging rook
855 games. ]
856
857    14. P4e R4b @*
858 [ Black starts his attack and white puts up a very passive defence.  His
859 rook has a hard task now to penetrate the black position.  Moreover, he
860 blocks his own bishop.  It seems much better to start a counterattack
861 with 14... P3e, later to be followed by B2b, B5a or Bx4d in order to use
862 his rook more actively. ]
863
864    15. Px4d Sx4d  16. P*4e S5c @*
865 [ 16... Sx4e is more active.  A silver general is normally more valuable
866 than a knight, but white gets two pawns in hand and black none, while
867 the knight might come in handy for white too. ]
868
869    17. Bx3c+ Nx3c  18. P2d Px2d @*
870 [ Black threatens to break through and white has to consider taking the
871 pawn on 2d or starting a counterattack with Nx4e.  If he chooses the
872 latter, black can play Px2c+ followed by +P3c.  The disadvantage is the
873 black ``tokin'' (=promoted pawn) that white will get in his camp; the
874 advantage is that it will cost black two more moves to promote his rook.
875 Because white did not trust that the result after engaging in a
876 ``semeai'' (=mutual attack) with 18...Nx4e would give a positive result,
877 he captured the pawn on 2d.  Making the right decision in moments like
878 this often makes the difference between a win and a loss: miss one
879 attacking chance and you will be forced to defend the whole game until
880 the unavoidable defeat; on the other hand, an unsound attack can destroy
881 all ``aji'' (=potential, meaning possibilities, threats) without getting
882 anything in return. ]
883
884    19. Rx2d Nx4e  20. Nx4e Rx4e  21. R2a+ P*4g @*
885 [ Now it becomes clear why black's 10. S6h was not good.  Had this move
886 been omitted, then white would not have had the time to play 13... S7b
887 and after R2a+ the gold on 6a would hang.  Thus black would have kept
888 ``sente'' (=initiative).  Instead of 21... P*4g, B*6d is a very good
889 move, because after 22. P*2h black does not have a pawn in hand anymore
890 and he is being threatened with the annoying 22... N*4f 23. G5g N3h+
891 24. S4g +N4h also.  Black can also counter 21... B*6d with 22. N*3g.
892 White would then reply with 22... R4b 23. B*3c P*4g 24. Bx4b+ Sx4b.  The
893 white rook has played its role and instead of spending moves on saving
894 it white starts to scatter black's defences by successive pawn drops on
895 the fourth file: 25. Gx4g P*4f 26. G5g N*6e 27. G5h P4g+ 28. Gx4g P*4f.
896 This analysis was provided by Kato Hifumi, 9-dan professional (the
897 highest regular grade).  Destroying the coherence of the enemy pieces
898 (their shape) by dropping pawns is one of the most important Shogi
899 techniques.  With the actual move 21... P*4g white missed a good
900 chance. ]
901
902    22. Sx4g P*4f  23. B*3g Px4g+  24. +Rx6a +Px3g @*
903 [ 23. B*3g seems pointless, but a closer look reveals that it is
904 actually quite mean.  On move 24 white cannot capture black's ``Ryu''
905 (=dragon =promoted rook) with his silver: 24... Sx6a 25. N*7d K7b
906 26. G*8b mate.  By attacking the front of the white castle and
907 threatening to mate him there, black has the chance to break down the
908 white defences from the side. ]
909
910    25. +Rx5b S*6b @*
911 [ Here 25... B*4d would be much better, because it is defensive and
912 attacking at the same time.  After e.g. 26. G*4c Bx9i+ 27. Gx5c black
913 threatens 28. +Rx7b Kx7b 29. S*6a K8b 30. S*7a Kx7a 31. G*7b mate.
914 White is one move quicker, however.  He has the following beautiful
915 ``tsume'' (mating sequence where every move is check): 27... N*8f 28. Px8f
916 S*8g 29. Kx8g B*9h 30. K7h Bx8i+ 31. K8g +B8i-8h 32. K9f L*9e mate.
917 This illustrates the sharpness of Shogi: one move can make the
918 difference between winning and losing. ]
919
920    26. P*4f Rx4f @*
921 [ This move eliminates white's last chances.  26... R4b 27. +Rx4b Sx4b
922 28. R*4a seems annoying, but after 28... B*3c 29. S7g B*3b white wins
923 the rook and with his ``tokin'' on 3g there still is some hope. ]
924
925    27. N*6e +P4g @*
926 [ White cannot defend anymore, so he starts a desperate attack.  Black
927 does not lose the right track, however. ]
928
929    28. Nx5c+ +Px5h  29. +Nx6b +Px6h  30. Gx6h N*8f  31. Px8f B*6i  32. Gx6i
930    R4h+  33. N*6h +Rx6h  34. Gx6h S*8g  35. Kx8g N*9e  36. K7h Resigns @*
931 [ White resigns here, because after 36... B*8g 27. K7g his attack has
932 petered out. ]
933
934 @page
935
936
937 @c 
938 @c Mating problems.
939 @c 
940
941 @node    Mating problems, Shogi variants, Sample game, About shogi
942 @section Mating problems
943
944 One good way to improve at shogi is to solve mating problems.  There are
945 several types of these problems, but the most common is called a
946 ``tsume-shogi'' problem, or ``tsume'' problem for short.  In a tsume
947 problem, all pieces that are not on the board are assumed to be in the
948 opponent's hand (except for your King, which is usually not shown).
949 Every move you make must be check until the final checkmate.  Your
950 opponent may play any piece on the board or drop any of his pieces in
951 hand in order to prevent the mate.  In a properly constructed tsume
952 problem, all of your pieces on the board and in hand must be essential
953 to the solution.  One consequence of this is that all of your pieces in
954 hand must be played during the solution.  There should only be one
955 correct solution for the given number of moves.  Tsume problems use
956 Japanese-style move numbering; thus, a problem where you move (and give
957 check), your opponent moves, and you move to give checkmate is called a
958 three-mover.  Here is a really trivial three-mover:
959
960 @ifnottex
961 @verbatim
962    3    2    1
963 ----------------+
964  |    |    |    |  a
965 ----------------+
966  |    |    | wK |  b
967 ----------------+
968  |    |    |    |  c
969 ----------------+
970  | bN |    |    |  d
971 ----------------+
972  |    |    |    |  e
973 ----------------+
974  |    | bN |    |  f
975 ----------------+
976
977 Black in hand: S, G
978 @end verbatim
979 @end ifnottex
980
981
982 @tex
983 \def\startline{\par\nobreak\noindent}
984
985 {\obeylines\obeyspaces%
986 \gdef\beginVerbatim{\bigbreak%
987 \begingroup%
988 \parskip=0pt%
989 \obeylines\obeyspaces%
990 \let^^M=\startline%
991 \tt}}
992 \gdef\endVerbatim{\endgroup\bigbreak}
993 \beginVerbatim
994
995    3    2    1            
996 ----------------+         
997  |    |    |    |  a         
998 ----------------+           
999  |    |    | wK |  b         
1000 ----------------+           
1001  |    |    |    |  c       
1002 ----------------+         
1003  | bN |    |    |  d       
1004 ----------------+         
1005  |    |    |    |  e       
1006 ----------------+         
1007  |    | bN |    |  f       
1008 ----------------+
1009      
1010 Black in hand: 2G
1011
1012 \endVerbatim
1013 @end tex
1014
1015 Here, Black plays G*2b, White plays K1c, and Black plays G*1d mate.
1016 More typical tsume problems range from 5 moves to arbitrarily high
1017 numbers of moves, and they can be quite brain-busting.  Tsume problems
1018 may seem artificial, but in the closing stages of the game where both
1019 players have a lot of pieces in hand, it is often necessary to give
1020 check at every move, or else your opponent will start a counterattack
1021 and will mate you before you mate him.  A tsume problem is a worst-case
1022 scenario for the attacker: you have to mate your opponent even though he
1023 has every piece not on the board in hand, which means you have to
1024 develop sharp attacking skills.  Many more tsume problems can be found
1025 on the internet; I particularly recommend Patrick Davin's ``Shogi
1026 Nexus'' (@pxref{References and links}).
1027
1028 @page
1029
1030 @c 
1031 @c Shogi variants.
1032 @c 
1033
1034 @node    Shogi variants, Differences between shogi and chess, Mating problems, About shogi
1035 @section Shogi variants
1036 @cindex  Shogi variants
1037 @cindex  Variants
1038 @cindex  Tori Shogi
1039 @cindex  Wa Shogi
1040 @cindex  Chu Shogi
1041 @cindex  Dai Shogi
1042 @cindex  Tenjiku Shogi
1043 @cindex  Dai-dai Shogi
1044 @cindex  Maka-dai-dai Shogi
1045 @cindex  Tai Shogi
1046 @cindex  Kyoku Tai Shogi
1047
1048 Several historical variants of shogi exist.  Most of these were invented
1049 before modern shogi (in some cases hundreds of years before), are much
1050 larger than modern shogi and are not played with drops.  Thus, in many
1051 ways they are really more like giant chess games than like modern shogi.
1052 The only one of these games to have survived in Japan is Chu (middle)
1053 shogi, which is still played a little bit.  Thanks to the efforts of
1054 George Hodges and John Fairbairn of the Shogi Association (two British
1055 shogi enthusiasts), these games were resurrected and rules and sets for
1056 them can still be purchased from George Hodges (@pxref{References and
1057 links}).  I hope to eventually extend GNU shogi so that it can play at
1058 least some of these games.  There are also several non-historical
1059 variants of shogi; I don't know much about them but you can find
1060 information about them on the internet (@pxref{References and links}).
1061
1062 The historical variants include:
1063
1064 @enumerate
1065
1066 @item
1067 Tori (bird) shogi, played on a 7x7 board with 32 pieces in all; this is
1068 the only variant that is known to have been played with drops.
1069
1070 @item
1071 Wa shogi, played on an 11x11 board with 54 pieces.  This game can be
1072 played with or without drops but the historical evidence favors the view
1073 that it was played without drops.  However, most people who have tried
1074 it claim it is a much better game with drops, being even more intricate
1075 than standard shogi.
1076
1077 @item
1078 Chu (middle) shogi, played on a 12x12 board with 92 pieces.  This was
1079 (and is) by far the most popular of the variants, and has 21 different
1080 kinds of pieces in the starting line-up alone (along with several others
1081 that appear upon promotion).  Unlike modern shogi, there are a
1082 tremendous number of ranging pieces and the game is definitely not
1083 played with drops.  There is also an amazing piece called the Lion which
1084 has a double king move and can capture two pieces at once!  Chu shogi
1085 has a small but fanatical following, some of whom consider it better
1086 than modern shogi.
1087
1088 @item
1089 Dai (great) shogi, played on a 15x15 board with 130 pieces.  Other than
1090 the larger board, this game is very similar to Chu shogi.
1091
1092 @item
1093 Tenjiku (exotic) shogi, played on a 16x16 board with 176 pieces.  This
1094 game is possibly the most complex tactical game in existence.  There are
1095 many astoundingly powerful pieces, including one (the Fire Demon) that
1096 can capture up to eight opposing pieces in a single move!  Despite the
1097 size of the game, checkmates can occur very suddenly (and often very
1098 early on) if one player makes a wrong move.  Tenjiku also has a small
1099 but fanatical following, one of whom (Colin Adams) has written a book on
1100 the game which is available for download at
1101 @uref{http://wayback.archive.org/web/20120717085827/http://www.colina.demon.co.uk/tenjiku.html}.
1102
1103 @item
1104 Dai-dai (great-great) shogi, played on a 17x17 board with 192 pieces.
1105 The opening setup alone has 64 different kinds of pieces!  This game and
1106 the larger ones that follow sound pretty outlandish, but they have
1107 actually been played; a game of Dai-dai can supposedly be played in
1108 about 12 hours.
1109
1110 @item
1111 Maka-dai-dai (great-great-great) shogi, played on a 19x19 board with 192
1112 pieces.  For those for whom Dai-dai shogi is just too small :-)
1113
1114 @item
1115 Tai (grand) shogi, played on a 25x25 board with 354 pieces!  Until
1116 recently, this was thought to be the biggest chess game ever devised,
1117 but now there is...
1118
1119 @item
1120 Kyoku tai (extremely grand?) shogi, played on a 36x36 board with 402
1121 pieces.  The rules for this have just been unearthed in an old Japanese
1122 book.  Hopefully someone will soon organize a postal Kyoku tai shogi
1123 championship; maybe their distant ancestors could finish it :-)
1124
1125 It is thought that the really huge games (Dai-dai and up) were never
1126 really played to any significant extent (gee, wonder why?) and were
1127 devised merely so that the creators could have the fun of inventing
1128 enormous games, amazing their friends and confounding their enemies.
1129 However, the games up to Tenjiku shogi at least appear to be quite
1130 playable, assuming one has the time.
1131
1132 @end enumerate
1133
1134 Many modern variants have also been devised, usually on small boards,
1135 and often by western people.  Those include:
1136
1137 @enumerate
1138
1139 @item
1140 Mini Shogi, played on a 5x5 board with 12 pieces.  Its rules are
1141 nearly identical to Standard Shogi, and GNU Shogi has some support for
1142 it.
1143
1144 @item
1145 Judkins Shogi, similar to Mini Shogi on a 6x6 board.
1146
1147 @item
1148 Cannon Shogi, played on a 9x9 board, adds pieces inspired by the
1149 Cannon found in Xiang Qi (chinese chess)
1150
1151 @item
1152 Sannin Shogi, a 3-player variant on an hexagonal board, with specific
1153 rules governing alliance between two players
1154
1155 @item
1156 Kyoto Shogi, Micro Shogi, and several others are much more different.
1157
1158 @end enumerate
1159
1160 @c
1161 @c Differences between shogi and chess.
1162 @c
1163
1164 @node    Differences between shogi and chess,  ,  Shogi variants, About shogi
1165 @section Differences between shogi and chess
1166 @cindex  Shogi vs. Chess
1167
1168 Some differences between shogi and international chess have been
1169 mentioned elsewhere in this document; I summarize them here for people
1170 who are interested in game comparisons.  I won't try to deal with the
1171 thorny question of which game is ``better'' although my bias may have
1172 already come through :-) In fact, the drop rule makes the two games so
1173 different in character that arguing over which game is better is like
1174 comparing apples to oranges (you'd be better off comparing chess to Chu
1175 shogi (@pxref{Shogi variants}).  However, I believe that if you are a
1176 chess fan you'll really like shogi as well, and shogi is also popular
1177 with many people who don't particularly like chess.
1178
1179 Here are the significant differences between chess and shogi:
1180
1181 @enumerate
1182
1183 @item
1184 In shogi, captured pieces become the property of the capturer and can
1185 re-enter play by being dropped onto almost any vacant square.  In chess,
1186 captured pieces are out of the game.  Thus, in shogi, piece exchanges
1187 complicate the play significantly while in chess they simplify it.
1188
1189 @item
1190 The shogi board is 9x9; the chess board is 8x8.
1191
1192 @item
1193 Shogi has five pieces with no counterpart in chess: the gold and silver
1194 generals, the lance, the promoted rook and the promoted bishop.  Chess
1195 has one piece with no counterpart in shogi: the queen.  The knight's
1196 move in shogi is much more restrictive than in chess.  Pieces in shogi
1197 generally have a much smaller range of movement than in chess (unless
1198 they are in hand).
1199
1200 @item
1201 In shogi, all pieces except the gold general and the king can promote,
1202 but only to one kind of piece.  Promotion is easier in shogi because the
1203 promotion zone is closer to the starting position of the pieces
1204 (especially pawns).  In chess, only the pawn can promote, but it can
1205 promote to any other piece except the king.
1206
1207 @item
1208 In shogi, pawns capture the same way they move.  There is no initial
1209 two-space pawn move and hence no @emph{en-passant} captures.  In chess,
1210 pawns capture diagonally which means that opposing pawns can block each
1211 other.
1212
1213 @item
1214 In shogi, you only have one rook and one bishop.  Note that the bishop
1215 is not restricted to only one ``color'' square (squares in shogi aren't
1216 colored, but never mind) because promoted bishops can also move one
1217 square orthogonally.
1218
1219 @item
1220 There is no special castling move in shogi.  The term ``castle'' is
1221 used in shogi to denote a defensive formation consisting of (usually)
1222 three generals which protect the king.  There are many such castles
1223 (about 40 or so have names).  @xref{Sample game}.
1224
1225 @item
1226 Draws are much rarer in shogi than in chess.  Perpetual check is not
1227 allowed.  Stalemate is a virtual impossibility, and is a loss for the
1228 stalematee. 
1229
1230 @item
1231 Since pieces are never out of play in shogi, chess-type endgames
1232 involving only a few pieces do not occur.
1233
1234 @item
1235 Shogi games are generally longer than chess games (about 60-70 moves is
1236 typical).
1237
1238 @item
1239 Shogi has a well-developed handicap system which is in general use;
1240 chess does not.
1241
1242 @end enumerate
1243
1244 The effects of all these differences on play include (in my opinion):
1245
1246 @enumerate
1247
1248 @item
1249 Piece/pawn structures in chess are more rigid than in shogi.  Pawns
1250 block each other and pawns, once advanced, cannot ever retreat.  In
1251 shogi, you can repair the hole caused by a pawn advance by exchanging
1252 the pawn and dropping it back where you want it.  Thus shogi is more
1253 fluid than chess and less ``structural''.
1254
1255 @item
1256 Counterattack is MUCH more common in shogi than in chess.  Games
1257 typically end in mutual mating attacks, where each player is trying to
1258 checkmate the other player before being checkmated himself.  This makes
1259 tempo incredibly important and also makes sacrificial play quite common.
1260
1261 @item
1262 Attacks involving only ranging pieces are more a feature of chess than
1263 of shogi.  A shogi attack typically uses a ranging piece or pieces to
1264 support an attack by short-range pieces (especially generals).  It is
1265 very rare to mate a king with a non-adjacent ranging piece in shogi
1266 since the player whose king is threatened can almost always interpose by
1267 dropping a piece.
1268
1269 @end enumerate
1270
1271
1272 @c --------------------
1273 @c gnushogi.
1274 @c --------------------
1275
1276 @node    gnushogi, References and links, About shogi, Top
1277 @chapter gnushogi
1278 @cindex  gnushogi
1279
1280 This section describes how to run the ``gnushogi'' program.
1281
1282 SYNOPSIS
1283      
1284 gnushogi [ [[-]a] [-b bookfile] [-B binbookfile] [-C] [-h langfile] 
1285 [-L langfile] [-r length] [-R] [-s pathname] [-l pathname] [-S binbooksize]
1286 [-t] [-c size] [-T size] [-v] [-x] [-X] arg1 arg2 ]
1287
1288 DESCRIPTION
1289
1290 GNU shogi (gnushogi) plays a game of japanese chess (shogi) against the
1291 user or it plays against itself.
1292
1293 At startup gnushogi reads the binbook file if it is present.  It then
1294 looks for a book file.  If it is present it adds its contents to the
1295 binbook data.  If the binbook file is writable a new combined binbook
1296 file is written.
1297
1298 Gnushogi is a modified version of the gnuchess program.  It has a
1299 simple alphanumeric board display, or it can be used with a graphical
1300 interface like XBoard under X Window, or Winboard under Windows.  The
1301 program gets its opening moves from the file gnushogi.bbk which is
1302 located in a directory specified in the Makefile.  To invoke the
1303 program type:
1304
1305 @table @samp
1306
1307 @item  gnushogi -C
1308 simple curses based version
1309
1310 @item  gnushogi -X (or just gnushogi)
1311 XBoard/XShogi compatible version
1312
1313 @item gnushogi -R
1314 raw test display version
1315 @end table
1316
1317 TIME CONTROLS
1318
1319 If one argument is given, it is the search time per move in
1320 [minutes:]seconds.  So gnushogi 30 will generate one move every 30
1321 seconds, while gnushogi 5:00 will generate one move every 5 minutes.
1322
1323 If two or more arguments are given, they will be used to set tournament
1324 time controls with the first argument of each pair being the number of
1325 moves and the second being the total clock time in minutes[:seconds].
1326 Thus, entering gnushogi 60 5 will set the clocks for 5 minutes (300
1327 seconds) for the first 60 moves, and gnushogi 30 3:30 will allow 3
1328 minutes and 30 seconds for 30 moves.
1329
1330 gnushogi 30 5 1 :30 will allow 5 minutes for the first 30 moves and 30
1331 seconds for each move after that.  Up to 4 pairs of controls may be
1332 specified.
1333
1334 If no argument is given the program will prompt the user for level of
1335 play.
1336
1337 @page
1338
1339 BOOK
1340
1341 The book gnushogi.tbk consists of a sequence of openings.  An opening
1342 begins with a line starting with a # (the rest of the line is a comment).
1343 Following this is a series of moves in algebraic notation alternating
1344 between black and white separated by whitespace.  A move may have a ?
1345 after it indicating this move should never be made in this position.  Moves
1346 are stored as position:move so transpositions between openings can take
1347 place.
1348
1349 HASHFILE
1350
1351 The hashfile if created should be on the order of 4 megabytes; you can
1352 create such a hashfile by typing ``gnushogi -c 22'' (see below).  This
1353 file contains positions and moves learned from previous games.  If a
1354 hashfile is used the computer makes use of the experience it gained in
1355 past games.  Tests run so far show that it plays no worse with the
1356 hashfile than without, but it is not clear yet whether it provides a
1357 real advantage.
1358
1359 LEGAL MOVES
1360
1361 Note: Piece letters are determined by the language file.  What is
1362 specified here is the default (English).
1363
1364 Once gnushogi is invoked, the program will display the board and prompt
1365 the user for a move.  To enter a move, use the notation 7g7f where the
1366 first letter-number pair indicates the origin square and the second
1367 letter-number pair indicates the destination square.  An alternative is
1368 to use the notation P7f where the first letter indicates the piece type
1369 (P,L,N,S,G,B,R,K).  To promote append a + the type of the new piece to
1370 the move, as in 2d2c+ or P2c+. Note that you must use capital letters
1371 for the pieces by default.
1372
1373 COMMAND-LINE OPTIONS
1374
1375 @table @samp
1376
1377 @item -a
1378 Do not search on opponent's time.
1379
1380 @item a
1381 Do search on opponent's time.
1382
1383 @item -b @var{bookfile}
1384 Use bookfile for opening book.
1385
1386 @item -B @var{binbookfile}
1387 Use binbookfile for binary opening book.
1388
1389 @item -c @var{size}          
1390 Create a new HASHFILE.  File size is 2^size entries of approximately 65+?
1391 bytes.
1392
1393 @item -C
1394 Use curses-based display mode.
1395
1396 @item -h   
1397 Do not use hashfile.
1398
1399 @item h    
1400 Do use hashfile.
1401
1402 @item -l @var{pathname}
1403 Pathname of the loadfile used with get or xget.
1404
1405 @item -L @var{lang}
1406 Use language lang from the file gnushogi.lang.  If -L is not specified
1407 it uses the first language in the file.
1408
1409 @item  -P @var{plylevels}
1410 Number of plys to include in the binbookfile.  For generating a
1411 binbookfile.
1412
1413 @item  -r @var{length}
1414 Rehash @emph{length} times in searching entries for position in
1415 transposition table.
1416
1417 @item  -R  
1418 Use raw text display mode.  This can be used for dumb terminals or for
1419 systems that don't have curses.
1420
1421 @item  -s @var{pathname}
1422 Pathname of the save file to use with the save command.
1423
1424 @item  -S @var{size}
1425 Size of binbookfile for memory based books.  For creating a binbookfile.
1426
1427 @item  -t   
1428 Show statistics for HASHFILE.
1429
1430 @item  -T @var{size}
1431 Set the transposition table size to 2^size entries.
1432
1433 @item  -v   
1434 Show version and patchlevel.
1435
1436 @item  -x @var{value}
1437 Use value as the evaluation window xwndw.
1438
1439 @item  -X   
1440 Use XBoard/XShogi display mode (the default).
1441
1442 @end table
1443
1444
1445 COMMANDS
1446
1447 In addition to legal moves, the following commands can be entered at the
1448 gnushogi prompt.  Note: command names are determined by the language
1449 file and may vary with the implementation.  The default language is
1450 English.
1451
1452 @table @samp
1453
1454 @item alg
1455 allow algebraic input (not implemented).
1456
1457 @item Awindow 
1458 change Alpha window (default score + 90).
1459
1460 @item Bwindow 
1461 change Beta window (default score - 90).
1462
1463 @item beep 
1464 toggles beeping after each move (default: on).
1465
1466 @item bd 
1467 updates the current board position on the display.
1468
1469 @item book 
1470 turns off use of the opening library.
1471
1472 @item both 
1473 causes the computer to play both sides of a shogi game.
1474
1475 @item black 
1476 causes the computer to play as White, if the computer was to move
1477 first.
1478
1479 @item bsave 
1480 saves a game to disk as a book textfile.  The program will prompt the
1481 user for a file name.
1482
1483 @item gamein 
1484 toggles game mode time control.  Assumes the time specified for time
1485 control is the time for a complete game.  Input with the level command
1486 should be the game time and the expected number of moves in a game.  go
1487 command must be given.
1488
1489 @item coords 
1490 show coordinates on the display (visual only).
1491
1492 @item contempt 
1493 allows the value of @emph{contempt} to be modified.
1494
1495 @item debug 
1496 asks for a piece as color piece, as wb or bn, and shows its calculated
1497 value on each square.
1498
1499 @item debuglevel 
1500 sets level of debugging output if compiled with debug options.
1501
1502 @item depth 
1503 allows the user to change the search depth of the program.  The maximum
1504 depth is 29 ply.  Normally the depth is set to 29 and the computer
1505 terminates its search based on elapsed time rather than depth.  If depth
1506 is set to (say) 4 ply, the program will search until all moves have been
1507 examined to a depth of 4 ply (with extensions up to 11 additional ply
1508 for sequences of checks and captures).  If you set a maximum time per
1509 move and also use the depth command, the search will stop at the
1510 specified time or the specified depth, whichever comes first.
1511
1512 @item easy 
1513 toggles easy mode (thinking on opponents time) on and off. The default
1514 is easy mode ON.  If easy mode is disabled, the keyboard is polled for
1515 input every so often and when input is seen the search is terminated. It
1516 may also be terminated with a sigint.
1517
1518 @item edit 
1519 allows the user to set up a board position.
1520 @itemize @minus
1521
1522 @item #    
1523 clear the board.
1524
1525 @item c
1526 toggle piece color.
1527
1528 @item .
1529 command will exit setup mode.
1530
1531 @item p3b
1532 place a pawn on 3b
1533
1534 @item p3b+
1535 place a promoted pawn on 3b
1536
1537 @item p*
1538 place a pawn in hand (among the captured pieces)
1539
1540 @end itemize
1541
1542 Pieces are entered by typing a letter (p,l,n,s,g,b,r,k)  for
1543 the piece followed by the coordinate.  Here, letter case is ignored.
1544
1545 The usual warning about the language file applies.
1546
1547 @item exit 
1548 exits gnushogi.
1549
1550 @item first 
1551 tells the computer to move first.  Computer begins searching for a move.
1552 (same as ``go'').
1553
1554 @item force 
1555 allows the user to enter moves for both sides.  To get the program to
1556 play after a sequence of moves has been entered use the ``black'' or
1557 ``white'' commands.
1558
1559 @item get 
1560 retrieves a game from disk.  The program will prompt the user for a file
1561 name.
1562
1563 @item go 
1564 tells the computer to move first.  Computer begins searching for a move.
1565 (same as ``first'').
1566
1567 @item hash 
1568 use/don't use hashfile.
1569
1570 @item hashdepth 
1571 allows the user to change the minimum depth for using the hashfile and
1572 the number of moves from the beginning of the game to use it.
1573
1574 @item help 
1575 displays a short description of the commands and the current status of
1576 options.
1577
1578 @item hint 
1579 causes the program to supply the user with its predicted move.
1580
1581 @item level 
1582 allows the user to set time controls such as 60 moves in 5 minutes etc.
1583 In tournament mode, the program will vary the time it takes for each
1584 move depending on the situation.  If easy mode is disabled (using the
1585 ``easy'' command), the program will often respond with its move
1586 immediately, saving time on its clock for use later on.
1587
1588 @item list 
1589 writes the game moves and some statistics on search depth, nodes, and
1590 time to the file ``shogi.lst''.
1591
1592 @item material 
1593 toggle material flag - draws on no pawns and both sides < rook.
1594
1595 @item new 
1596 starts a new game.
1597
1598 @item p 
1599 evaluates the board and shows the point score for each piece.  The total
1600 score for a position is the sum of these individual piece scores.
1601
1602 @item post 
1603 causes the program to display the principal variation and the score
1604 during the search.  A score of 100 is equivalent to a 1 pawn advantage
1605 for the computer.
1606
1607 @item quit 
1608 exits the game.
1609
1610 @item random 
1611 causes the program to randomize its move selection slightly.
1612
1613 @item rcptr 
1614 set recapture mode.
1615
1616 @item remove 
1617 backout the last level for both sides.  Equal to 2 undo's.
1618
1619 @item reverse 
1620 causes the board display to be reversed.  That is, the Black's pieces will
1621 now appear at the top of the board.
1622
1623 @item rv 
1624 reverse board display.
1625
1626 @item save 
1627 saves a game to disk.  The program will prompt the user for a file name.
1628
1629 @item switch 
1630 causes the program to switch places with the opponent and begin
1631 searching.
1632
1633 @item test 
1634 performs some speed tests for MoveList and CaptureList generation, and
1635 ScorePosition position scoring for the current board.
1636
1637 @item time 
1638 set computer's time remaining, intended for synchronizing clocks among
1639 multiple players.
1640
1641 @item tsume 
1642 toggle tsume mode. In tsume mode, not all possible moves will be
1643 generated. If a king is in check, only moves that get the king out of
1644 check are generated.  If the king is not in check, only moves that give
1645 check to the opponent's king are generated.
1646
1647 @item undo 
1648 undoes the last move whether it was the computer's or the human's.  You
1649 may also type ``remove''.  This is equivalent to two ``undo'''s
1650 (e.g. retract one move for each side).
1651
1652 @item white 
1653 causes the computer to play as Black; if the computer is to move
1654 first the go command must be given.
1655
1656 @item xget 
1657 read an XShogi position file.
1658
1659 @item xsave 
1660 save as an XShogi position file.
1661
1662 @item xwndw 
1663 change X window. The window around alpha/beta used to determine whether
1664 the position should be scored or just estimated.  Note: this has
1665 @emph{nothing} to do with XBoard, XShogi or X Window; the terms are
1666 completely separate.
1667
1668 @end table
1669
1670
1671 @c ---------------------
1672 @c References and links.
1673 @c ---------------------
1674
1675 @node    References and links, Acknowledgements, gnushogi, Top
1676 @chapter References and links
1677 @cindex  References
1678 @cindex  Books
1679 @cindex  Mailing lists
1680 @cindex  Web sites
1681
1682
1683 There are very few English-language books for people learning shogi.
1684 The two I recommend are:
1685
1686 @enumerate
1687
1688 @item
1689 @cite{Shogi for Beginners, 2nd. Edition}, by John Fairbairn.  This is a
1690 superb beginner's book in every way, covering all phases of the game.
1691 It was out of print for a long time, but has now been reprinted and is
1692 available either from Kiseido (@uref{http://www.labnet.or.jp/~kiseido})
1693 or from George Hodges (see below).
1694
1695 @item
1696 @cite{The Art of Shogi}, by Tony Hoskings.  This is one step up from the
1697 Fairbairn book.  It covers a lot of ground, and is especially noteworthy
1698 for its detailed treatment of opening lines.  You can order this book
1699 from Amazon.com's UK branch (@uref{http://www.amazon.co.uk}).
1700
1701 @end enumerate
1702
1703 Another book you may find is @cite{Shogi: Japan's Game of Strategy} by
1704 Trevor Leggett.  This book is very elementary and is somewhat outdated,
1705 having been published first in 1966.  However, it does feature a paper
1706 shogi board and punch-out pieces, so if you want a really cheap shogi
1707 set you might pick this book up.  It is still in print.
1708
1709 Two books that are no longer in print but are definitely worth getting
1710 if you find them are @cite{Guide to Shogi Openings} and @cite{Better
1711 Moves for Better Shogi}, both by Aono Teriuchi.  They are published in a
1712 bilingual edition (English/Japanese) and are the only books on shogi in
1713 English written by a Japanese professional shogi player.  John Fairbairn
1714 did the translation from Japanese to English.
1715
1716 Shogi sets are available from:
1717
1718 @quotation
1719 George F. Hodges @*
1720 P.O. Box 77 @*
1721 Bromley, Kent @*
1722 United Kingdom BR1 2WT
1723 @end quotation
1724
1725 George also sells equipment for all the historical shogi variants
1726 (@pxref{Shogi variants}) (except for Kyoku tai shogi) and also sells
1727 back issues of the magazine ``Shogi'' which he published for 70 issues
1728 in the late 70's to late 80's.  This magazine is STRONGLY recommended;
1729 it contains more information about shogi in English than you will ever
1730 find anywhere else.
1731
1732 Here are some useful URLs:
1733
1734 @table @asis
1735
1736 @item Pieter Stouten's shogi page: @uref{http://www.shogi.net}
1737 This is the main shogi-related site on the internet, with links to
1738 almost all the other sites.
1739
1740 @item Roger Hare's shogi page: @uref{http://www.ed.ac.uk/~rjhare/shogi}
1741 This has lots of information, including full rules to most of the shogi
1742 variants.
1743
1744 @item Patrick Davin's Shogi Nexus: @uref{http://www.vega.or.jp/~patrick/shogi/}
1745 There's lots of cool stuff on this site; my favorite is the extensive
1746 collection of Tsume-shogi (mating) problems, both for beginners and
1747 more advanced players.
1748
1749 @item Steve Evans' shogi page: @uref{http://www.netspace.net.au/~trout/index.html} 
1750 Steve has written a program that plays almost all of the shogi variants,
1751 unfortunately it only runs on Windows :-(
1752
1753 @item Hans Bodlaender's chess variant pages: @uref{http://www.cs.ruu.nl/~hansb/d.chessvar}
1754 This page has an almost unimaginable variety of rules for different
1755 chess variants, including many shogi variants (historical and non-historical).
1756
1757 @item Wikipedia's shogi variant pages: @uref{http://en.wikipedia.org/wiki/Category:Shogi_variants}
1758 Those pages contain a large number of variant rules, both ancient and
1759 modern.
1760
1761 @end table
1762
1763 @c -----------------
1764 @c Acknowledgements.
1765 @c -----------------
1766
1767 @node    Acknowledgements, Bugs, References and links, Top
1768 @chapter Acknowledgements
1769 @cindex  Acknowledgements
1770
1771 I would like to thank the following people:
1772
1773 @itemize @bullet
1774
1775 @item
1776 Matthias Mutz, who originally developed GNU shogi as a spin-off of GNU
1777 chess and who very kindly let me take over the maintenance of this very
1778 interesting project.
1779
1780 @item
1781 Richard Stallman and the Free Software Foundation, for creating an
1782 organization where anyone can contribute software for the common good of
1783 all, for making GNU/Linux possible, and especially for writing emacs and
1784 gcc, without which my working life would be intolerable.
1785
1786 @item
1787 Georges Hodges, for starting the Shogi Association in England, without
1788 which I would probably never have heard of shogi, for supplying shogi
1789 equipment, for publishing the excellent magazine ``Shogi'' (now sadly
1790 defunct), for personally answering all my silly questions by mail, and
1791 for being the ambassador of shogi to the West.
1792
1793 @item
1794 Pieter Stouten, for having the most comprehensive shogi site on the
1795 World Wide Web (@uref{http://www.shogi.net}), and for
1796 maintaining the shogi-l mailing list.  Go to Pieter's web site for more
1797 information on subscribing to the list.  Also thanks to everyone who
1798 contributes and has contributed to that list.
1799
1800 @item
1801 Matt Casters, for testing GNU shogi.  Matt and I will be working
1802 together on improving the solution engine in future versions of this
1803 program.
1804
1805 @end itemize
1806
1807 @c -----
1808 @c Bugs.
1809 @c -----
1810
1811 @node    Bugs, Index, Acknowledgements, Top
1812 @chapter Bugs
1813
1814 The motto of GNU shogi is ``100% bug-free or you don't pay!'' :-) In
1815 the extremely unlikely case (*ahem*) that you do find a bug, please
1816 report it to the bug tracker at
1817 @uref{https://savannah.gnu.org/projects/gnushogi/}.  Also, feel free
1818 to post comments, complaints, out-and-out raves, suggestions and such
1819 to one of the mailing lists at
1820 @uref{https://savannah.gnu.org/mail/?group=gnushogi}.
1821
1822
1823 @c ============
1824 @c End of body.
1825 @c ============
1826
1827
1828
1829 @c ====
1830 @c End.
1831 @c ====
1832
1833 @node    Index,  , Bugs, Top
1834 @chapter Index
1835
1836 @printindex cp
1837
1838 @contents
1839
1840 @bye
1841
1842