analyze arbitrary positions.
To run engines that use the UCI standard XBoard will draw upon
the Polyglot adapter fully transparently, but you will need to have
-the polyglot package installed for this tio work.
+the polyglot package installed for this to work.
@item xboard -ics -icshost hostname [options]
As Internet Chess Server (ICS) interface, XBoard
lets you play against other ICS users, observe games
These shortcut keystrokes are mostly non-printable characters.
Typing a letter or digit while the board window has focus
will bring up a type-in box with the typed letter already in it.
-You can use that to type a move in siuations where it is your
+You can use that to type a move in situations where it is your
turn to enter a move,
type a move number to call up the position after that move
in the display,
be able to play the selected variant, or the corresponding choice will be disabled.
XBoard supports all major variants, such as xiangqi, shogi, chess, chess960,
makruk, Capablanca Chess, shatranj, crazyhouse, bughouse.
-But not every board size has built-in bitmaps for un-orthodox pieces!
-Only sizes bulky (72) and middling (49) have all pieces,
-while size petite (33) has most.
-These sizes would have to be set at startup through the @code{size}
-command-line option when you start up XBoard for such variants to be playable.
You can overrule the default board format of the selected variant,
(e.g. to play suicide chess on a 6 x 6 board),
To clear the board you can click the clock of the side that
already has the move (which is highlighted in black).
If you repeat this the board will cycle from empty to a
-'pallette board' containing every piece once to the initial
+@code{pallette board} containing every piece once to the initial
position to the one before clearing.
The quickest way to set up a position is usually to start
with the pallette board, and move the pieces to were you
The old behavior with a piece menu can still be configured
with the aid of the @code{pieceMenu} option.
Dragging empty squares off board can create boards with
-'holes' (inaccessible black squares) in them.
+holes (inaccessible black squares) in them.
Selecting @samp{Edit Position} causes XBoard to discard
all remembered moves in the current game.
You can then edit this list, and the new list will be stored
back into the book when you press 'save changes'.
When you press the button 'add next move', and play a move
-on the board, ithat move will be added to the list with weight 1.
+on the board, that move will be added to the list with weight 1.
Note that the listed percentages are neither used, nor updated when
you change the weights; they are just there as an optical aid.
When you right-click a move in the list it will be played.
command. The shifted @kbd{Alt+G} key is a keyboard equivalent.
The line describing each game is built from a selection of the PGN tags.
Which tags contribute, and in what order, can be changed by the @samp{Game list tags}
-menu dialog, which can be popped up through the 'Tags' button below the Game List.
+menu dialog, which can be popped up through the @samp{Tags} button below the Game List.
Display can be restricted to a sub-set of the games meeting certain criteria.
A text entry below the game list allows you to type a text that the game lines
must contain in order to be displayed.
Games can also be selected based on their Elo PGN tag,
as set in the @samp{Load Game Options} dialog, which can be popped up through the
-'Thresholds' button below the Game List.
+@samp{Thresholds} button below the Game List.
Finally they can be selected based on containing a position similar to the one
currently displayed in the main window, by pressing the 'Position' button below
the Game List, (which searches the entire list for the position), or the 'Narrow'
(ending with <Enter>).
Everything you type in the lowest field will then automatically be sent to
the mentioned party, while everything that party sends to you will
-appear in the central text box, rather than appear in the ICS console.
+appear in the central text pane, rather than appear in the ICS console.
The row of buttons allow you to choose between chat;
to start a new chat, just select an empty button,
and complete the @samp{Chat partner} field.
There are several keyboard accelerators to control this window:
-<Esc> will close the private chat, and assign the input field to the
+Ctrl-H will hide the private chat, and dedicates the input field to
+giving ICS commands.
+Ctrl-E will erase the current chat and chat partner.
+Ctrl-N will open a new chat with a yet unspecified partner.
+Ctrl-O will open a new chat with the last person from which you received
+a tell in the ICS console pane.
+<Esc> will transfer keyboard focus to the board window,
+allowing you to invoke menu items through accelerator keys;
+typing a printable character there transfers focus back to the input field
+of the chat window.
+<Tab> will switch to another busy chat,
+giving priority to those with content you have not seen yet.
+(The buttons for selecting such chats turn orange.)
+Up and down arrow keys can be used to recall previous input lines.
@item Board
@cindex Board, Menu Item
Summons a dialog where you can customize the look of the chess board.
To set up a position to analyze, you do the following:
-1. Select Edit Position from the Mode Menu
+1. Set up the position by any means. (E.g. using @samp{Edit Position}
+mode, pasing a FEN or loading a game and stepping to the position.)
-2. Set up the position. Use the middle and right buttons to
-bring up the white and black piece menus.
-
-3. When you are finished, click on either the Black or White
-clock to tell XBoard which side moves first.
-
-4. Select Analysis Mode from the Mode Menu to start the analysis.
+2. Select Analysis Mode from the Mode Menu to start the analysis.
You can now play legal moves to create follow-up positions for the
engine to analyze, while the moves will be remembered as a stored game,
a sufficiently modern version of the Polyglot adapter needed to run UCI engines,
e.g. Polyglot 2.0.1.) For native XBoard engines this is less common.
-@subsection Common Settings
+@item Common Settings
@cindex Common Settings, Menu Item
-Pops up a sub-menu where you can set some engine parameters common to most engines,
+Pops up a menu dialog where you can set some engine parameters common to most engines,
such as hash-table size, tablebase cache size, maximum number of processors
that SMP engines can use.
The shifted @kbd{Alt+U} key is a keyboard equivalent.
so you won't have to search for it in your list of installed engines,
if that is very long.
The maximum number of displayed engine names is set by the
-@code{recentEngines}command-line option.
+@code{recentEngines} command-line option.
@end table
@node Options Menu
and the ICS may award you a draw instead of a win if you have
insufficient mating material. In local chess engine mode,
XBoard
-may call either player's flag and will not take material into account (?).
+may call either player's flag.
@item Auto Flip View
@cindex Auto Flip View, Menu Item
If the Auto Flip View option is on when you start a game, the board
Causes the highlighting described in Highlight Last Move to be done
by drawing an arrow between the highlighted squares,
so that it is visible even when the width of the grid lines is set to zero.
-@item Move Sound
-@cindex Move Sound, Menu Item
-Enables the sounding of an audible signal when the computer performs a move.
-For the selection of the sound, see @samp{Sound Options}.
-If you turn on this option when using XBoard with the Internet
-Chess Server, you will probably want to give the
-@kbd{set bell 0}
-command to the ICS, since otherwise the ICS will ring the terminal bell
-after every move (not just yours). (The @file{.icsrc} file
-is a good place for this; see @ref{ICS options}.)
@item One-Click Moving
@cindex One-Click Moving, Menu Item
If this option is on, XBoard does not wait for you to click both the
on, the Analysis Window will be updated every two seconds.
@item Play Move(s) of Clicked PV
@cindex Play Move(s) of Clicked PV, Menu Item
-If this option is on, right-clicking a PV in the Engine Output window
+If this option is on, right-clicking on the first move of a PV
+or on the data fields left of it in the Engine Output window
during Analyze mode will cause the first move of that PV to be played.
You could also play more than one (or no) PV move by moving the mouse
to engage in the PV walk such a right-click will start,
to seek out another position along the PV where you want to continue
the analysis, before releasing the mouse button.
+Clicking on later moves of the PV only temporarily show the moves
+for as long you keep the mouse button down,
+without adding them to the game.
@item Ponder Next Move
@cindex Ponder Next Move, Menu Item
If this option is off, the chess engine will think only when it is on
yellow (non-captures) or red (captures).
Special moves might have other colors
(e.g. magenta for promotion, cyan for a partial move).
-Legality testing must be on for XBoard to know how the piece moves.
+Legality testing must be on for XBoard to know how the piece moves,
+but with legality testing off some engines would offer this information.
@item Sticky Windows
@cindex Sticky Windows, Menu Item
Controls whether the auxiliary windows such as Engine Output, Move History
when @samp{Animate Moving} is swiched on.
@item Zoom factor in Evaluation Graph
@cindex Zoom factor in Evaluation Graph, Menu Item
-Sets the valueof the @code{evalZoom} option,
+Sets the value of the @code{evalZoom} option,
indicating the factor by which the score interval (-1,1) should be
blown up on the vertical axis of the Evaluation Graph.
@end table
@cindex Background Observe, Menu Item
Setting this option will make XBoard suppress display of any boards
from observed games while you are playing.
-In stead the last such board will be remembered,
+Instead the last such board will be remembered,
and shown to you when you right-click the board.
This allows you to peek at your bughouse partner's game when you want,
without disturbing your own game too much.
@cindex ICS Alarm Time, Menu Item
When this option is on, an alarm sound is played when your clock
counts down to the icsAlarmTime in an ICS game.
-(By default, the time is 5 seconds, but you can pecify other values
+(By default, the time is 5 seconds, but you can specify other values
with the Alarm Time spin control.)
For games with time controls that include an increment, the
alarm will sound each time the clock counts down to the icsAlarmTime.
@itemx Tourney participants
@cindex Select Engine, Menu Item
@cindex Tourney participants, Menu Item
-With the Select Engine drop-down list you can pick an engine from your list
-of installed engines in the settings file, to be added to the tournament.
+From the Select Engine listbox you can pick an engine from your list
+of engines registered in the settings file, to be added to the tournament.
The engines selected so far will be listed in the ‘Tourney participants’ memo.
The latter is a normal text edit, so you can use normal text-editing functions
-to delete engines you selected by accident, or change their order.
-Do not type names yourself there, because names that do not exactly match
-one of the names from the drop-down list will lead to undefined behavior.
+to delete engines you selected accidentally, or change their order.
+Typing names here yourself is not recommended, because names that do not exactly match
+one of the names from the selection listbox will lead to undefined behavior.
@item Tourney type
@cindex Tourney type, Menu Item
Here you can specify the type of tournament you want.
as specified by the ‘number of games per pairing’,
or by repeating the entire tournament schedule a number of times
(specified by the ‘number of tourney cycles’).
-The total number of times two engine meet will be the product of these two.
-Default is 1 cycle;
+The total number of times two engines meet will be the product of these two.
+Default is 1 cycle;
the number of games per pairing is the same as the default number of match games,
stored in your settings file through the @code{defaultMatchGames} option.
@item Save Tourney Games
but the second (even) games will select the same moves from the book as the previous game.
(Note this leads to the same opening only if both engines use the GUI book!)
Default: No game or position file will be used. The default index if such a file is used is 1.
-@item Disable own engine bools be default
+@item Disable own engine books be default
@cindex Disable own engine books be default, Menu Item
Setting this option reverses the default situation for use of the GUI opening book
in tournaments from what it normally is, namely not using it.
You can then run a tourney with the same parameters
(possibly after changing the proposed name of the tourney file for the new tourney)
by pressing 'OK'.
+@item Continue Later
+@cindex Continue Later, Menu Item
+Pressing the @samp{Continue Later} button confirms the current value of all
+items in the dialog and closes it,
+but will not automatically start the tournament.
+This allows you to return to the dialog later without losing the settings you
+already entered, to adjust paramenters through other menu dialogs.
+(The @samp{Common Engine Setting}, @samp{Time Control} and @samp{General Options}
+dialogs can be accessed without closing the @samp{Tournament Options} dialog
+through the respective buttons at the bottom of the latter.)
@end table
@subsection Load Game Options
@table @asis
@item Elo of strongest player
@itemx Elo of weakest player
-@itemx year
+@itemx No games before year
@cindex Elo of strongest player, Menu Item
@cindex Elo of weakest player, Menu Item
-@cindex year, Menu Item
+@cindex No games before year, Menu Item
These numeric fields set thresholds (lower limits) on the Elo rating of the mentioned player,
or the date the game was played.
Defaults: 0
@item number of consecutive positions
@cindex number of consecutive positions, Menu Item
When you are searching by material, rather than for an exact match,
-this parameter indicates forhowmany consecutive game positions
+this parameter indicates for how many consecutive game positions
the same amount of material must be on the board before it is
considered a match.
@item Also match reversed colors
@subsection Sound Options
@cindex Sound Options, Menu Item
Summons a dialog where you can specify the sounds that should accompany
-various events that can occur XBoard.
+various events that can occur in XBoard.
Most events are only relevant to ICS play,
but the move sound is an important exception.
For each event listed in the dialog,
* Load and Save options:: Input/output options.
* User interface options:: Look and feel options.
* Adjudication Options:: Control adjudication of engine-engine games.
+* Install options:: Maintaining and extending the XBoard install.
* Other options:: Miscellaneous.
@end menu
over which it takes precedence if both are specified. (See there.)
Default: 0 (do not run a match).
@item -fcp or -firstChessProgram program
+@itemx -scp or -secondChessProgram program
@cindex fcp, option
@cindex firstChessProgram, option
-Name of first chess engine.
-Default: @file{Fairy-Max}.
-@item -scp or -secondChessProgram program
@cindex scp, option
@cindex secondChessProgram, option
-Name of second chess engine, if needed.
-A second chess engine is started only in Two Machines (match) mode.
-Default: @file{Fairy-Max}.
+Name of first and second chess engine, respectively.
+A second chess engine is started only in Two Machines (match) mode,
+or in Analyze mode with two engines.
+The second engine is by default the same as the first.
+Default for the first engine: @file{fairymax}.
@item -fe or -firstEngine nickname
+@itemx -se or -secondEngine nickname
+@cindex se, option
+@cindex secondEngine, option
@cindex fe, option
@cindex firstEngine, option
-This is an alternative to the @code{fcp} option for specifying the first engine,
-for engines that were already configured (using the @samp{Load Engine} dialog)
+This is an alternative to the @code{fcp} and @code{scp} options
+for specifying the first and second engine,
+for engines that were already registered (using the @samp{Load Engine} dialog)
in XBoard's settings file.
It will not only retrieve the real name of the engine,
but also all options configured with it.
(E.g. if it is UCI, whether it should use book.)
-@item -se or -secondEngine nickname
-@cindex se, option
-@cindex secondEngine, option
-As @code{fe}, but for the second engine.
@item -fb/-xfb or -firstPlaysBlack true/false
@cindex fb, option
@cindex firstPlaysBlack, option
By playing an match in this mode, a book will be built from scratch.
The only output are the saved games, which can be converted to an
actual book later, with the @samp{Save Games as Book} command.
-This command can also be used to pre-fill the book buffer
+The latter command can also be used to pre-fill the book buffer
before adding new games based on the probing algorithm.
@item -fn string or -firstPgnName string
@itemx -sn string or -secondPgnName string
@cindex sn, option
Indicates the name that should be used for the engine in PGN tags of
engine-engine games.
-Intended to allow you to install verions of the same engine with different settings,
+Intended to allow you to install versions of the same engine with different settings,
and still distinguish them.
Default: "".
@item -defaultHashSize n
If the name part matches that of a format that the engine requests through a feature command,
xboard will relay the path name for this format to the engine through an egtpath command.
One egtpath command for each matching format will be sent.
-Popular formats are "nalimov" DTM tablebases and "scorpio" bitbases.
+Popular formats are "nalimov" and "gaviota" DTM tablebases,
+syzygy DTZ tablebases and "scorpio" bitbases.
Default: "".
@item -firstChessProgramNames=@{names@}
+@cindex firstChessProgramNames, option
This option lets you customize the listbox with chess-engine names
that appears in the @samp{Load Engine} and @samp{Tournament Options} dialog.
It consists of a list of strings, one per line.
Volatile option, but stored in tourney file.
@item -results string
@cindex results, option
-The string of +=- characters lists the result of all played games in a toruney.
+The string of +=- characters lists the result of all played games in a tourney.
Games currently playing are listed as *,
-while a space indicates a game that is not yet played or playing .
+while a space indicates a game that is not yet played.
Volatile option, but stored in tourney file.
@item -defaultTourneyName string
@cindex defaultTourneyName, option
@cindex afterGame, option
@cindex afterTourney, option
When non-empty, the given string will be executed as a system command
-after each tournament game, orafterthe tourney completes, respectively.
+after each tournament game, or after the tourney completes, respectively.
This can be used, for example, to autmatically run a cross-table generator
on the PGN file where games are saved, to update the tourney standings.
Default: ""
Only a summary of time left and material of both players will appear
in the message field above the board.
XBoard will remember the last board it has received this way,
-and will display it in stead of the position in your own game
+and will display it instead of the position in your own game
when you press the right mouse button.
No other information is stored on such games observed in the background;
you cannot save such a game later, or step through its moves.
CShout is synonymous with SShout.
@item -soundMove filename
@cindex soundMove, option
-This sound is used by the Move Sound menu option. Default: "$".
+This sound is played when a player other than yourself makes a move.
+Default: "$".
+@item -soundRoar filename
+@cindex soundRoar, option
+This sound is played when a Lion makes a hit-and-run or double capture/
+Default: "" (no sound).
@item -soundIcsAlarm filename
@cindex soundIcsAlarm, option
This sound is used by the ICS Alarm menu option. Default: "$".
-saveSettingsFile or succesfull -settingsFile / -ini command,
if any, and in /etc/xboard/xboard.conf otherwise.
Usualy the latter is only accessible for the system administrator, though,
-and will be used to contain system-wide default setings, amongst which
+and will be used to contain system-wide default settings, amongst which
a -saveSettingsFile and -settingsFile options to specify a settings file
accessible to the individual user, such as ~/.xboardrc in the user's
home directory.
@cindex User interface options
@cindex Options, User interface
@table @asis
-@item -display
-@itemx -geometry
-@itemx -iconic
-@itemx -name
-@cindex display, option
-@cindex geometry, option
-@cindex iconic, option
-@cindex resource name, option
-These and most other standard Xt options are accepted.
@item -noGUI
@cindex noGUI, option
Suppresses all GUI functions of XBoard
Specify the images to be used as player logos when @code{logoSize}
is non-zero, next to the white and black clocks, respectively.
@item -autoLogo true/false
-@item -logoDir filename
+@itemx -logoDir filename
@cindex autoLogo, option
@cindex logoDir, option
When @code{autoLogo} is set, XBoard will search for a PNG image file
-with the name of the engine or ICS in the directory specified.
+with the name of the engine or ICS in the directory specified
+by @code{logoDir}.
For a human player it will look for a file <username>.png in this
directory, but only when ~/.logo.png does not provide one.
-by @code{logoDir}.
@item -recentEngines number
@itemx -recentEngineList list
@cindex recentEngines, option
Changes in the list will only become visible the next session,
provided you saved the settings.
Default: 6.
-@item -autoInstall list
-@cindex autoInstall, option
-When the list is set to a non-empty string, XBoard will scan the
-operating system's plugin directory for engines supporting UCI
-and XBoard protocol at startup.
-When it finds an engine that was installed after it last saved
-its settings, a line to launch that engine (as per specs in
-the plugin file) is appended to the -firstChessProgramNames
-list of installed engines.
-In the future it will be possible to use the autoInstall list to limit
-this automatic adding of engines based on the chess variant they play.
@item -oneClickMove true/false
@cindex oneClickMove, option
When set, this option allows you to enter moves by only clicking the to-
the font size, XBoard tries to choose an appropriate font for
the board size being used.
Default Xaw: -*-helvetica-medium-r-normal--*-*-*-*-*-*-*-*.
-Default GTK: Sans Bold %d.
+Default GTK: Sans Bold %d
+@item -tagsFont font
@cindex tagsFont, option
@cindex Font, tags
The font used in the Edit Tags dialog.
an appropriate font for the board size being used.
(Only used in GTK build.)
Default: Sans Normal %d.
+@item -commentFont font
@cindex commentFont, option
@cindex Font, comment
The font used in the Edit Comment dialog.
an appropriate font for the board size being used.
(Only used in GTK build.)
Default: Sans Normal %d.
+@item -icsFont font
@cindex icsFont, option
@cindex Font, ics
The font used to display ICS output in the ICS Chat window.
an appropriate font for the board size being used.
(Only used in GTK build.)
Default: Monospace Normal %d.
+@item -moveHistoryFont font
@cindex moveHistoryFont, option
@cindex Font, moveHistory
The font used in Move History and Engine Output windows.
an appropriate font for the board size being used.
(Only used in GTK build.)
Default: Sans Normal %d.
+@item -gameListFont font
@cindex gameListFont, option
@cindex Font, gameList
The font used in the listbox of the Game List window.
This option can be used by install scripts for board themes
to figure out where the currently active XBoard stores its data.
@item -date timestamp
-@xitem -saveDate timestamp
+@itemx -saveDate timestamp
@cindex date, option
@cindex saveDate, option
These options specify an epoch as an integer number.
following it were added to those files.
Some options will be ignored if the epoch specified by the latest @code{date} option
predates the -saveDate setting (implying they must have been seen before).
+@item -autoInstall list
+@cindex autoInstall, option
+When the list is set to a non-empty string, XBoard will scan the
+operating system's plugin directory for engines supporting UCI
+and XBoard protocol at startup.
+When it finds an engine that was installed after it last saved
+its settings, a line to launch that engine (as per specs in
+the plugin file) is appended to the -firstChessProgramNames
+list of installed engines.
+In the future it will be possible to use the autoInstall list to limit
+this automatic adding of engines based on the chess variant they play.
@item -addMasterOption string
@cindex addMasterOption, option
Adds the mentioned string as an additional line of XBoard's master settings file,
When XBoard is invoked with a single argument that is a file
with .trn extension, it will assume this argument to be the value
of a @code{tourneyFile} option,
-and apped the value of the persistent option @code{tourneyOptions}
+and append the value of the persistent option @code{tourneyOptions}
as stored in the settings file to the command line.
Thus the value of @code{tourneyOptions} can be
used to configure XBoard to automatically start running a
after 50 reversible moves in variants that have a 64-move rule,
or no similar rule at all.
+Default: "normal". Except when the first engine gave an explicit list
+of variants it supports, and 'normal' is not amongst those.
+In that case the first variant the engine mentioned it did play will
+be chosen.
@item -boardHeight N
@cindex boardHeight, option
Allows you to set a non-standard number of board ranks in any variant.
@item -pieceToCharTable string
@cindex pieceToCharTable, option
The characters that are used to represent the piece types XBoard knows in FEN
-diagrams and SAN moves. The string argument has to specify an even number of pieces
+diagrams and SAN moves.
+You should not have to use this option often: each variant has its own default
+setting for the piece representation in FEN, which should be sufficient in normal use.
+The string argument has to specify an even number of pieces
(or it will be ignored), as white and black pieces have to be given separately
(in that order). The last letter for each color will be the King.
The letters before that will be PNBRQ and then a whole host of fairy pieces
Pawn in crazyhouse-like games, i.e. on capture it turns back to a Pawn.
A '+' similarly indicates the piece is a shogi-style promoted piece, that should
revert to its non-promoted version on capture (rather than to a Pawn).
-Note that promoted pieces are represented by pieces 11 further in the list
-(27 in variant chu).
+By default the second 11 pieces known to XBoard are the promoted forms of the first 11.
+A piece specified by the character combination ^ plus letter will be assumed
+to be the promoted form of the piece indicated by that letter,
+and get a '+' assigned.
To get around the limitation of the alphabet,
piece IDs can also be 'dressed letters', i.e. a single letter
(upper case for white, lower case for black)
followed by a single quote or an exclamation point.
-You should not have to use this option often: each variant has its own default
-setting for the piece representation in FEN, which should be sufficient in normal use.
-Default: ""
+Default: "" (meaning the default for the variant is used).
@item -pieceNickNames string
@cindex pieceNickNames, option
The characters in the string are interpreted the same way as in the
projects / xboard.git / commitdiff