doc/cboard.6.in

   1 .\" Copyright (C) 2002-2018  Ben Kibbey <bjk@luxsci.net>
   2 .\"
   3 .\" This program is free software; you can redistribute it and/or modify
   4 .\" it under the terms of the GNU General Public License as published by
   5 .\" the Free Software Foundation; either version 2 of the License, or
   6 .\" (at your option) any later version.
   7 .\"
   8 .\" This program is distributed in the hope that it will be useful,
   9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 .\" GNU General Public License for more details.
  12 .\"
  13 .\" You should have received a copy of the GNU General Public License
  14 .\" along with this program; if not, write to the Free Software
  15 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  16 .de URL
  17 \\$2 \(laURL: \\$1 \(ra\\$3
  18 ..
  19 .if \n[.g] .mso www.tmac
  20 .TH CBOARD 6 "Jun 30 2018" "@VERSION@" "Curses Chess Board"
  21
  22 .SH NAME
  23 .B cboard
  24
  25 .SH SYNOPSIS
  26 .B cboard
  27 .I "[\-hvC]" "[-u [0|1]]" "[\-p [\-VtRSE] <filename>]"
  28
  29 .SH DESCRIPTION
  30 .B cboard
  31 is an
  32 .BR ncurses (3)
  33 PGN browser, editor and frontend to various chess engines supporting the
  34 XBoard protocol.
  35
  36 .SH OPTIONS
  37 The following command line options are available:
  38 .TP
  39 .I "\-p <pgnfile>"
  40 Load a PGN formatted file. If the filename extension ends with .Z, .bz2,
  41 \&.gz or \&.zip, then it will be uncompressed (and compressed if saving)
  42 automatically provided you have
  43 .BR compress (1)
  44 ,
  45 .BR bzip2 (1)
  46 ,
  47 .BR gzip (1)
  48 and
  49 .BR zip (1)
  50 installed.
  51
  52 .TP
  53 .I "\-E"
  54 Stop processing a file when a parse error occurs. Overrides configuration
  55 parameter.
  56
  57 .TP
  58 .I "\-V"
  59 Validate the specified file only. If a parse error occurs
  60 .B cboard
  61 will return a nonzero exit status.
  62
  63 .TP
  64 .I "\-S"
  65 Validate the specified file and output the PGN formatted game to stdout. If a
  66 parse error occurs
  67 .B cboard
  68 will return a nonzero exit status.
  69
  70 .TP
  71 .I "\-R"
  72 Like
  73 .I "\-S"
  74 but output a reduced PGN formatted game which includes only the seven tag
  75 roster and move text without any annotations.
  76
  77 .TP
  78 .I "\-t"
  79 Normally when
  80 .I "\-S"
  81 is specified custom tags aren't written. This option enables custom tags in
  82 .B ~/.cboard/config
  83 to be added to the output.
  84
  85 .TP
  86 .I "\-C"
  87 Enable strict castling. Useful when only validating a file. This option
  88 overrides the config value.
  89
  90 .TP
  91 .I "\-u [1|0]"
  92 Enable or disable UTF-8 chess pieces. This will override any
  93 .B utf8_pieces
  94 configuration setting.
  95
  96 .TP
  97 .I "\-v"
  98 Version information.
  99
 100 .TP
 101 .I "\-h"
 102 Program help text.
 103
 104 .SH "CONFIGURATION FILE"
 105 Empty lines and lines beginning with a '#' are ignored. Other lines are
 106 parameter and value pairs which must be on the same line and separated with
 107 one or more space or TAB characters. Options which are noted to accept a value
 108 of
 109 .I bool
 110 can be one of:
 111 .B true
 112 ,
 113 .B 1
 114 ,
 115 .B on
 116 ,
 117 .B yes
 118 OR
 119 .B false
 120 ,
 121 .B 0
 122 ,
 123 .B off
 124 ,
 125 .B no
 126 \&.
 127
 128 .TP
 129 .I utf8_pieces  <bool>
 130 Whether to show UTF-8 chess pieces on the board. The default is on.
 131
 132 .TP
 133 .I board_left <bool>
 134 When off, the chess board will be on the right side of the game status
 135 window. The default is on.
 136
 137 .TP
 138 .I coords_y_left <bool>
 139 Whether to show the board ranks on the left or right side of the chess
 140 board. The default is true.
 141
 142 .TP
 143 .I exit_dialog_box <bool>
 144 Confirm before quitting
 145 .B cboard
 146 \&. The default is on.
 147
 148 .TP
 149 .I engine_cmd_blacktag <bool>
 150 Set the Black tag to the chess engine command used during human/engine
 151 play. The default is on.
 152
 153 .TP
 154 .I engine_cmd <command> [<args>] [...]
 155 The chess engine command to execute with any arguments. The default is
 156 .B gnuchess --xboard
 157 Other engines haven't been tested but any engine that supports the XBoard
 158 protocol should work.
 159
 160 .TP
 161 .I engine_protocol <protocol>
 162 The version of the XBoard protocol to use. At the moment all this
 163 means is whether to send SAN formatted moves (protocol version 2) or
 164 regular FRFR formatted moves. The default is 1.
 165
 166 .TP
 167 .I engine_init <command>
 168 A command to send to the chess engine each time a new game or round is started
 169 or reset. Can be specified more than once.
 170
 171 .TP
 172 .I fm_polyglot <bool>
 173 Send the needed commands:
 174 .B go
 175 and
 176 .B white
 177 or
 178 .B black
 179 , due to a quirk when using
 180 .BR polyglot (6)
 181 as the chess engine.
 182
 183 .TP
 184 .I turn_cmd <command> [<args>] [...]
 185 A command to be run when it is a human turn when playing a against a chess
 186 engine. The first occurrence of an
 187 .B %m
 188 in the command will be expanded to the SAN move text of the previous move.
 189
 190 .TP
 191 .I bind <mode> <key> <command> [<description>]
 192 This allows you to change the default key bindings for each game mode.
 193 Each game
 194 .I mode
 195 has it's own set of commands
 196 .I command
 197 with an optional
 198 .I description
 199 which is shown in the help text. See
 200 .B config.example
 201 included in the archive for available game modes and commands.
 202
 203 .TP
 204 .I cbind <type> <key> <command>
 205 Bind the specified
 206 .I key
 207 to the engine command
 208 .I command .
 209 The bound key will only be available in play mode and will only be sent to the
 210 engine if it doesn't conflict with other play mode keys. The
 211 .I type
 212 argument specifies how a repeat count is treated. When
 213 .B set
 214 , typing a number then pressing the bound
 215 .I key
 216 will append that number to
 217 .I command
 218 \&. When
 219 .B repeat
 220 , typing a number then pressing
 221 .I key
 222 will send
 223 .I command
 224 the repeat amount of times. If
 225 .B none
 226 , then
 227 .I command
 228 will be sent without modification.
 229
 230 .TP
 231 .I macro <mode> <key> <description> <key_sequence>
 232 A
 233 .I macro
 234 behaves like pressing a series of keys automatically without
 235 interaction. The specified
 236 .I key
 237 "presses" the keys specified in
 238 .I key_sequence
 239 when in
 240 .I mode .
 241 The
 242 .I mode
 243 may be
 244 .B play
 245 ,
 246 .B history
 247 ,
 248 .B edit
 249 or
 250 .B any
 251 \&. When
 252 .B any
 253 , global keys may be accessed. Note that the description must be enclosed in
 254 double quotes when if it contains whitespace.
 255
 256 .TP
 257 .I jump_count <integer>
 258 When viewing move history, you can jump more than one move to the next or
 259 previous move with the UP and DOWN keys. This sets the number of moves to
 260 jump. The default is 5.
 261
 262 .TP
 263 .I tag <name> [<value>]
 264 Custom PGN tags to add to new games. This can also be used to overwrite
 265 default tag values. It can also be used more than once.
 266
 267 .TP
 268 .I line_graphics <bool>
 269 Enable or disable board line graphics. The default is off.
 270
 271 .TP
 272 .I board_details <bool>
 273 When enabled, castling availability, the en passasnt square and
 274 attacking pieces will be shown on the board. This can be toggled with
 275 the `^d' key by default.
 276
 277 .TP
 278 .I save_directory <path>
 279 If set, the default directory where games will be saved and restored from.
 280 A tilde `~' will be expanded to your home directory.
 281
 282 .TP
 283 .I mpl <integer>
 284 The maximum number of full moves to write per line when saving. If 0,
 285 then write the maximum number of moves that will fit in 80 columns.
 286
 287 .TP
 288 .I save_prompt <bool>
 289 When saving a game, prompt to edit PGN tag data. Or when saving in history
 290 mode, prompt for additional save commands. The default is on.
 291
 292 .TP
 293 .I delete_prompt <bool>
 294 Prompt before deleting games. The default is on.
 295
 296 .TP
 297 .I stop_on_error <bool>
 298 Stop processing a file when a parsing error occurs. Normally a game or round
 299 will be flagged and the rest of the file will still be parsed.
 300
 301 .TP
 302 .I valid_moves <bool>
 303 When a piece is selected, show valid squares the piece can move to. The
 304 .B color_board_white_moves
 305 and
 306 .B color_board_black_moves
 307 color parameters can specify alternate colors for the valid move squares.
 308 The default is on.
 309
 310 .TP
 311 .I strict_castling <bool>
 312 When enabled, a castling move will be invalid if the opponent can attack a
 313 castling square, beit the King, Rook or the squares between the two. The
 314 default is off.
 315
 316 .TP
 317 .I show_attacks <bool>
 318 When both this option and
 319 .I board_details
 320 is enabled, hilight the opponent pieces that can attack the square under
 321 the cursor.
 322
 323 .TP
 324 .I pattern <filter>
 325 When in the file browser you can filter what is displayed with a
 326 .BR glob (7)
 327 pattern. Directories, including hidden directories, are always
 328 displayed reguardless of the pattern. The default is `*.[Pp][Gg][Nn]*'.
 329
 330 .SH COLORS
 331 Colors and attributes can be modified from the configuration
 332 file. There are up to four values for each parameter. The first two
 333 are the foreground and background colors which must be one of:
 334 .B black
 335 ,
 336 .B white
 337 ,
 338 .B blue
 339 ,
 340 .B green
 341 ,
 342 .B yellow
 343 ,
 344 .B cyan
 345 ,
 346 .B magenta
 347 ,
 348 .B red
 349 or
 350 .B -
 351 for the default color.
 352
 353 .P
 354 The third and fourth values are optional and set terminal attributes. The
 355 third sets attributes for color terminals and the fourth for non-color
 356 terminals. Multiple attributes may be assigned by separating them with a
 357 comma. Note that not all terminals support all attributes. The following
 358 attributes are recognized:
 359 .B bold
 360 ,
 361 .B reverse
 362 ,
 363 .B dim
 364 ,
 365 .B standout
 366 ,
 367 .B underline
 368 ,
 369 .B blink
 370 ,
 371 .B invisible
 372 ,
 373 .B none
 374 or
 375 .B -
 376 for the default attribute.
 377
 378 .P
 379 Some color parameters have a
 380 .B _window
 381 extension. This will set the default color and attibutes for all
 382 characters of the given parameter set.
 383
 384 .TP
 385 .I color_board_window foreground background [<cattr>] [<attr>]
 386 .TP
 387 .I color_board_selected foreground background [<cattr>] [<attr>]
 388 .TP
 389 .I color_board_cursor foreground background [<cattr>] [<attr>]
 390 .TP
 391 .I color_board_black foreground background [<cattr>] [<attr>]
 392 .TP
 393 .I color_board_white foreground background [<cattr>] [<attr>]
 394 .TP
 395 .I color_board_graphics foreground background [<cattr>] [<attr>]
 396 .TP
 397 .I color_board_coords foreground background [<cattr>] [<attr>]
 398 .TP
 399 .I color_board_white_moves foreground background [<cattr>] [<attr>]
 400 .TP
 401 .I color_board_black_moves foreground background [<cattr>] [<attr>]
 402 .TP
 403 .I color_board_castling foreground background [<cattr>] [<attr>]
 404 .TP
 405 .I color_board_enpassant foreground background [<cattr>] [<attr>]
 406 .TP
 407 .I color_board_attack foreground background [<cattr>] [<attr>]
 408 .TP
 409 .I color_board_prev_move foreground background [<cattr>] [<attr>]
 410 .TP
 411 .I color_status_window foreground background [<cattr>] [<attr>]
 412 .TP
 413 .I color_status_title foreground background [<cattr>] [<attr>]
 414 .TP
 415 .I color_status_border foreground background [<cattr>] [<attr>]
 416 .TP
 417 .I color_status_notify foreground background [<cattr>] [<attr>]
 418 .TP
 419 .I color_status_engine foreground background [<cattr>] [<attr>]
 420 .TP
 421 .I color_tag_window foreground background [<cattr>] [<attr>]
 422 .TP
 423 .I color_tag_title foreground background [<cattr>] [<attr>]
 424 .TP
 425 .I color_tag_border foreground background [<cattr>] [<attr>]
 426 .TP
 427 .I color_history_window foreground background [<cattr>] [<attr>]
 428 .TP
 429 .I color_history_title foreground background [<cattr>] [<attr>]
 430 .TP
 431 .I color_history_border foreground background [<cattr>] [<attr>]
 432 .TP
 433 .I color_message_window foreground background [<cattr>] [<attr>]
 434 .TP
 435 .I color_message_title foreground background [<cattr>] [<attr>]
 436 .TP
 437 .I color_message_border foreground background [<cattr>] [<attr>]
 438 .TP
 439 .I color_message_prompt foreground background [<cattr>] [<attr>]
 440 .TP
 441 .I color_input_window foreground background [<cattr>] [<attr>]
 442 .TP
 443 .I color_input_title foreground background [<cattr>] [<attr>]
 444 .TP
 445 .I color_input_border foreground background [<cattr>] [<attr>]
 446 .TP
 447 .I color_input_prompt foreground background [<cattr>] [<attr>]
 448 .TP
 449 .I color_menu foreground background [<cattr>] [<attr>]
 450 .TP
 451 .I color_menu_selected foreground background [<cattr>] [<attr>]
 452 .TP
 453 .I color_menu_highlight foreground background [<cattr>] [<attr>]
 454 .TP
 455 .I color_menu_graphics foreground background [<cattr>] [<attr>]
 456
 457 .SH RETURN VALUE
 458 .B cboard
 459 will return 0 on success or 1 on failure. Failures are file access errors,
 460 parsing errors or command line usage errors.
 461
 462 .SH FILES
 463 .TP
 464 .I ~/.cboard/config
 465 Configuration file.
 466
 467 .TP
 468 .I ~/.cboard/cc.data
 469 Country codes. Used when editing the "Site" tag.
 470
 471 .TP
 472 .I ~/.cboard/nag.data
 473 Appending to this file is fine for custom NAG types, but lines before
 474 140 are reserved by the PGN standard.
 475
 476 .TP
 477 .I ~/.cboard/perl.pl
 478 If compiled with
 479 .BR perl (1)
 480 support, a file containing subroutines that
 481 .B CBoard
 482 can filter games through.
 483
 484 .SH SEE ALSO
 485 .BR gnuchess (6)
 486 ,
 487 .BR ncurses (3)
 488 ,
 489 .BR glob (3)
 490 ,
 491 .BR glob (7)
 492 ,
 493 .BR regex (7)
 494
 495 .SH AUTHORS
 496 Ben Kibbey <bjk@luxsci.net>
 497 .P
 498 .URL "https://gitlab.com/bjk/cboard/wikis" "CBoard homepage"