doc/cboard.man

   1 .\" Copyright (C) 2002-2006  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 .
  17 .Dd January 09, 2003
  18 .Os
  19 .Dt CBOARD 6
  20 .
  21 .Sh NAME
  22 .
  23 .Nm cboard
  24 .Nd an ncurses PGN browser, editor and chess engine frontend
  25 .
  26 .Sh SYNOPSIS
  27 .
  28 .Nm cboard
  29 .Op Fl hvN
  30 .Op Fl E Fl t Fl V Fl S
  31 .Op Fl p Ar pgnfile
  32 .
  33 .Sh DESCRIPTION
  34 .
  35 .Nm cboard
  36 is an
  37 .Xr ncurses
  38 PGN browser, editor and frontend to various chess engines supporting the
  39 XBoard protocol.
  40 .
  41 .Pp
  42 The following command line options are available:
  43 .
  44 .Bl -tag -width
  45 .It Fl p Ar pgnfile
  46 Load a PGN formatted file. If the filename extension ends with .Z, .bz, .bz2,
  47 \&.gz or \&.zip, then it will be uncompressed (and compressed if saving)
  48 automatically provided you have
  49 .Xr compress 1 ,
  50 .Xr bzip2 1 ,
  51 .Xr gzip 1
  52 and
  53 .Xr zip 1
  54 installed.
  55 .It Fl E
  56 Stop processing a file when a parse error occurs. Overrides configuration
  57 parameter.
  58 .It Fl N
  59 Enable two human player mode disabling the chess engine.
  60 .It Fl V
  61 Validate the specified file only. If a parse error occurs
  62 .Nm cboard
  63 will return a nonzero exit status.
  64 .It Fl S
  65 Validate the specified file and output the PGN formatted game to stdout. If a
  66 parse error occurs
  67 .Nm cboard
  68 will return a nonzero exit status.
  69 .It Fl R
  70 Like
  71 .Fl S
  72 but output a reduced PGN formatted game which includes only the seven tag
  73 roster and move text without any annotations.
  74 .It Fl t
  75 Normally when
  76 .Fl S
  77 is specified custom tags aren't written. This option enables custom tags in
  78 .Pa ~/.cboard/config
  79 to be added to the output.
  80 .It Fl v
  81 Version information.
  82 .It Fl h
  83 Program help text.
  84 .El
  85 .
  86 .Sh "CONFIGURATION FILE"
  87 Empty lines and lines beginning with a '#' are ignored. Other lines are
  88 parameter and value pairs which must be on the same line and separated with
  89 one or more space or TAB characters. Options which are noted to accept a value
  90 of
  91 .Ar BOOL
  92 can be one of:
  93 .Ar true ,
  94 .Ar 1 ,
  95 .Ar on ,
  96 .Ar yes
  97 OR
  98 .Ar false ,
  99 .Ar 0 ,
 100 .Ar off ,
 101 .Ar no .
 102 .Pp
 103 .Bl -tag -compact
 104 .It Cm engine_cmd Ar command Op args ...
 105 The chess engine command to execute with any arguments. The default is
 106 \&"
 107 .Ar gnuchess --xboard
 108 \&". Others haven\&'t been tested but any engine that supports the XBoard
 109 protocol should work.
 110 .Pp
 111 .It Cm engine_init Ar command
 112 A command to send to the chess engine each time a new game or round is started
 113 or reset. Can be specified more than once.
 114 .Pp
 115 .It Cm key Ar key Ar command
 116 Bind the specified
 117 .Ar key
 118 to the engine command
 119 .Ar command .
 120 The bound key will only be available in play mode and will only be sent to the
 121 engine if it doesn't conflict with other play mode keys.
 122 .Pp
 123 .It Cm jump_count Ar integer
 124 When viewing move history, you can jump more than one move to the next or
 125 previous move with the UP and DOWN keys. This sets the number of moves to
 126 jump. The default is
 127 .Ar 5 .
 128 .Pp
 129 .It Cm agony Ar BOOL
 130 Display agony strings in the status window when a capture is made. The default
 131 is
 132 .Ar on .
 133 .Pp
 134 .It Cm history_agony Ar BOOL
 135 Display agony strings when browsing move history. If
 136 .Cm agony
 137 is disabled, then this will be disable also. The default is
 138 .Ar off .
 139 .Pp
 140 .It Cm tag Ar name Op Ar value
 141 Custom PGN tags to add to new games. This can also be used to overwrite
 142 default tag values. It can also be used more than once.
 143 .Pp
 144 .It Cm line_graphics Ar BOOL
 145 Enable or disable board line graphics. The default is
 146 .Ar off .
 147 .Pp
 148 .It Cm save_directory Pa path
 149 If set, the default directory where games will be saved and restored from.
 150 Tildes `~' and environment variables are supported.
 151 .Pp
 152 .It Cm mpl Ar integer
 153 The maximum number of full moves to write per line when saving. If
 154 .Ar 0
 155 then write the maximum number of moves that will fit in 80 columns.
 156 .Pp
 157 .It Cm save_prompt Ar BOOL
 158 When saving a game, prompt to edit PGN tag data. Or when saving in history
 159 mode, prompt for additional save commands. The default is
 160 .Ar on .
 161 .Pp
 162 .It Cm delete_prompt Ar BOOL
 163 Prompt before deleting games with the \&"D\&" command. The default is
 164 .Ar on .
 165 .Pp
 166 .It Cm stop_on_error Ar BOOL
 167 Stop processing a file when a parsing error occurs. Normally a game or round
 168 will be flagged and the rest of the file will still be parsed.
 169 .Pp
 170 .It Cm valid_moves Ar BOOL
 171 When a piece is selected, show valid squares the piece can move to. The
 172 .Cm color_board_white_moves
 173 and
 174 .Cm color_board_black_moves
 175 color parameters can specify alternate colors for the valid move squares.
 176 The
 177 default is
 178 .Ar on .
 179 .Pp
 180 .It Cm pattern Ar filter
 181 When in the file browser you can filter what is displayed with this value.
 182 Directories, including hidden directories, are always displayed reguardless of
 183 the pattern. The default is `*.pgn'.
 184 .Pp
 185 .It Cm fifty_move_draw Ar BOOL
 186 Enable the fifty move draw rule. The fifty move draw is a drawing rule that
 187 causes a game to be ended when no captures or pawn advances have occured in
 188 the last fifty moves on either playing side. The default is
 189 .Ar off .
 190 .El
 191 .
 192 .Sh COLORS
 193 .Bl -tag -compact
 194 .It Cm color_board_window Ar foreground Ar background Op Ar cattr Op Ar attr
 195 .It Cm color_board_selected Ar foreground Ar background Op Ar cattr Op Ar attr
 196 .It Cm color_board_cursor Ar foreground Ar background Op Ar cattr Op Ar attr
 197 .It Cm color_board_black Ar foreground Ar background Op Ar cattr Op Ar attr
 198 .It Cm color_board_white Ar foreground Ar background Op Ar cattr Op Ar attr
 199 .It Cm color_board_graphics Ar foreground Ar background Op Ar cattr Op Ar attr
 200 .It Cm color_board_coords Ar foreground Ar background Op Ar cattr Op Ar attr
 201 .It Cm color_board_white_moves Ar foreground Ar background Op Ar cattr Op Ar attr
 202 .It Cm color_board_black_moves Ar foreground Ar background Op Ar cattr Op Ar attr
 203 .It Cm color_status_window Ar foreground Ar background Op Ar cattr Op Ar attr
 204 .It Cm color_status_title Ar foreground Ar background Op Ar cattr Op Ar attr
 205 .It Cm color_status_border Ar foreground Ar background Op Ar cattr Op Ar attr
 206 .It Cm color_status_notify Ar foreground Ar background Op Ar cattr Op Ar attr
 207 .It Cm color_status_engine Ar foreground Ar background Op Ar cattr Op Ar attr
 208 .It Cm color_tag_window Ar foreground Ar background Op Ar cattr Op Ar attr
 209 .It Cm color_tag_title Ar foreground Ar background Op Ar cattr Op Ar attr
 210 .It Cm color_tag_border Ar foreground Ar background Op Ar cattr Op Ar attr
 211 .It Cm color_history_window Ar foreground Ar background Op Ar cattr Op Ar attr
 212 .It Cm color_history_title Ar foreground Ar background Op Ar cattr Op Ar attr
 213 .It Cm color_history_border Ar foreground Ar background Op Ar cattr Op Ar attr
 214 .It Cm color_message_window Ar foreground Ar background Op Ar cattr Op Ar attr
 215 .It Cm color_message_title Ar foreground Ar background Op Ar cattr Op Ar attr
 216 .It Cm color_message_border Ar foreground Ar background Op Ar cattr Op Ar attr
 217 .It Cm color_message_prompt Ar foreground Ar background Op Ar cattr Op Ar attr
 218 .It Cm color_input_window Ar foreground Ar background Op Ar cattr Op Ar attr
 219 .It Cm color_input_title Ar foreground Ar background Op Ar cattr Op Ar attr
 220 .It Cm color_input_border Ar foreground Ar background Op Ar cattr Op Ar attr
 221 .It Cm color_input_prompt Ar foreground Ar background Op Ar cattr Op Ar attr
 222 .It Cm color_menu Ar foreground Ar background Op Ar cattr Op Ar attr
 223 .It Cm color_menu_selected Ar foreground Ar background Op Ar cattr Op Ar attr
 224 .It Cm color_menu_highlight Ar foreground Ar background Op Ar cattr Op Ar attr
 225 .El
 226 .Pp
 227 Color and attributes can be modified from the configuration file. There are up
 228 to four values for each parameter. The first two are the foreground and
 229 background colors which must be one of:
 230 .Ar black ,
 231 .Ar white ,
 232 .Ar blue ,
 233 .Ar green ,
 234 .Ar yellow ,
 235 .Ar cyan ,
 236 .Ar magenta
 237 or
 238 .Ar red .
 239 .Pp
 240 The third and fourth values are optional and set terminal attributes. The
 241 third sets attributes for color terminals and the fourth for non-color
 242 terminals. Multiple attributes may be assigned by separating them with a
 243 comma. Note that not all terminals support all attributes. The following
 244 attributes are recognized:
 245 .Ar bold ,
 246 .Ar reverse ,
 247 .Ar dim ,
 248 .Ar standout ,
 249 .Ar underline ,
 250 .Ar blink ,
 251 .Ar invisible
 252 and
 253 .Ar none .
 254 .Pp
 255 Some color parameters have a _window extension. This will set the default
 256 color and attibutes for all characters for the given parameter set.
 257 .
 258 .Sh RETURN VALUE
 259 .Nm cboard
 260 will return 0 on success or 1 on failure. Failures are file access errors,
 261 parsing errors or command line usage errors.
 262 .
 263 .Sh FILES
 264 .Bl -tag -compact -width ~/.cboard/agony.data
 265 .It Pa ~/.cboard/config
 266 Configuration file.
 267 .It Pa ~/.cboard/agony.data
 268 A list of agony strings, one per line, which is displayed randomly when a
 269 capature has been made.
 270 .It Pa ~/.cboard/cc.data
 271 Country codes. Used when editing the \&"Site\&" tag.
 272 .It Pa ~/.cboard/nag.data
 273 Appending to this file is fine for custom NAG types, but lines before 140 are
 274 reserved by the PGN standard.
 275 .It Pa ~/.cboard/fifo
 276 A FIFO read by the chess engine for resuming games.
 277 .El
 278 .
 279 .Sh SEE ALSO
 280 .Xr wordexp 3 ,
 281 .Xr ncurses 3 ,
 282 .Xr gnuchess 6
 283 .
 284 .Sh AUTHORS
 285 .An "Ben Kibbey" Aq bjk@luxsci.net