.TH duel 1
.SH NAME
\fBduel\fR - Stages a duel using two opposing instances of \fBbishbosh\fR
.SH SYNOPSIS
\fBbishbosh\fR [\fIOPTIONS\fR]
.SH DESCRIPTION
.PP
An application which automatically plays chess, by forking two independently configured instances of \fBbishbosh\fR.
One instance automates the moves of White & the other automates the moves of Black.
This application merely acts as an intermediary, passing moves between these instances to synchronise their positions,
while measuring the total time taken by either side & collating the game-results to permit comparison of the fitness of their respective configurations.
.PP
This process facilitates optimisation of the complex configuration of \fBbishbosh\fR.
.PP
CAVEAT: the population of games resulting from this statistical experiment must be diverse, but this application's logic is largely deterministic (& both players are configured to use it).
In order to introduce some randomness, PGN-databases must be configured in which the application may search for positions matching the current game.
When more than one match for the current position is found, one of them is \fIrandomly\fR selected at the source of the next move.
If the specified PGN-databases fail to provide such move-options, deterministic play will result.
.SH OPTIONS
.TP
\fB--verbosity=\fR(\fBSilent\fR|\fBNormal\fR|\fBVerbose\fR|\fBDeafening\fR), defaulting to "\fBNormal\fR".
Defines the quantity of ancillary output required.
.TP
\fB-d\fR \fIInt\fR, \fB--nDecimalDigits=\fR\fIInt\fR, defaulting to "\fB0\fR".
The precision with which to display the total time taken by each side.
.TP
\fB-n\fR \fIInt\fR, \fB--nGames=\fR\fIInt\fR, defaulting to "\fB1\fR".
The number of games to be played before presenting the results.
.TP
\fB-t\fR \fIInt\fR, \fB--readTimeout=\fR\fIInt\fR, defaulting to \fIindefinitely\fR.
The maximum number of seconds to wait for one of the forked processes to return a move, before aborting.
CAVEAT: the required period typically required depends on;
.IP \(bu
the machine's speed,
.IP \(bu
what else is running on the machine,
.IP \(bu
the size of the machine's RAM,
.IP \(bu
the time initially required to process any PGN-database,
.IP \(bu
\fBbishbosh\fR's configuration (e.g. search-depth or fitness-evaluation criteria).
.TP
.B --verifyConfiguration
Verify the mutual compatibility of the two configuration-files before forwarding each to a forked instance of \fBbishbosh\fR,
where the syntactic & semantic correctness will be independently verified.
The configurations are required to define the same move-notation & to define the logical colour of the automated player in the correct order to avoid deadlock.
N.B. since verification of this compatibility-requirement necessitates parsing, syntactic-verification is an inevitable side-effect.
.TP
\fB-i\fR \fIFile-path\fR, \fB--appendInputConfigFilePath=\fR\fIFile-path\fR; there is no default.
Define the path to a configuration-file to forward to \fBbishbosh\fR.
Two such paths are required, the first will be passed to the instance playing White & the second to the instance playing Black.
.SS "Generic Program-information"
.TP
\fB-v\fR, \fB--version\fR
Outputs version-information & then exits.
.TP
\fB-?\fR, \fB--help\fR
Displays a usage-message & then exits.
.SH EXIT-STATUS
\fB0\fR on success, & >\fB0\fR if an error occurs.
.SH EXAMPLES
.nf
.B duel --nGames=32 --verbosity='Verbose' --verifyConfiguration -i 'config/Raw/bishbosh_duel_white.xml' -i 'config/Raw/bishbosh_duel_black.xml'
.fi
.IP \(bu
The application has been instructed to provide a relatively large amount of feedback.
.IP \(bu
Two packaged configuration-files have been referenced.
.IP \(bu
The compatibility of the configuration-files is verified to confirm that they automate White & Black respectively, & that they use the same move-notation.
.IP \(bu
CAVEAT: assumes that the executable exists on \fB$PATH\fR, otherwise an explicit path will be required.
.PP
.nf
.B make duel
.fi
.IP \(bu
Much the same as the previous example, but verification is unnecessary since the configuration-files are hard-coded.
.IP \(bu
The current working directory must be \fBbishbosh\fR's installation-directory where the required \fBmakefile\fR is defined.
.SH FILES
.TS
lb	lb
l	l
lb	l	.
File-name	Contents
=========	========
config/Raw/bishbosh_duel_{black,white}.xml	Sample configuration-files.
makefile	Facilitates common tasks.
man/man1/bishbosh.1	The man-page for \fBbishbosh\fR.
.TE
.SH AUTHOR
Written by Dr. Alistair Ward.
.SH BUGS
.PP
In the absence of any configured \fBpgnOptions\fR, the game is completely deterministic & will reproduce the previous result endlessly.
Even when PGN-databases have been configured, they may introduce insufficient randomness to produce a large population of unique games on which to perform statistical analysis.
.SS "REPORTING BUGS"
Report bugs to "\fBbishbosh@functionalley.com\fR".
.SH COPYRIGHT
Copyright \(co 2021 Dr. Alistair Ward
.PP
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
.PP
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along with this program. If not, see <\fBhttps://www.gnu.org/licenses/\fR>.
.SH "SEE ALSO"
.IP \(bu
Home-page: <\fBhttps://functionalley.com/BishBosh/bishbosh.html\fR>.
.IP \(bu
<\fBhttps://hackage.haskell.org/package/bishbosh\fR>.
.IP \(bu
<\fBhttps://github.com/functionalley/BishBosh\fR>.
.IP \(bu
Source-documentation is generated by "\fBHaddock\fR", & is available in the distribution.
.IP \(bu
<\fBhttps://www.haskell.org/haddock/\fR>.