| blob | c78b9817368693cf17a7bf04f7dc9040bd4b8828 |
1 .\" Copyright (C) 2002-2007 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 May 27, 2007
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 hvC
30 .Op Fl E Fl t Fl V Fl S Fl R
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, .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 V
59 Validate the specified file only. If a parse error occurs
60 .Nm cboard
61 will return a nonzero exit status.
62 .It Fl S
63 Validate the specified file and output the PGN formatted game to stdout. If a
64 parse error occurs
65 .Nm cboard
66 will return a nonzero exit status.
67 .It Fl R
68 Like
69 .Fl S
70 but output a reduced PGN formatted game which includes only the seven tag
71 roster and move text without any annotations.
72 .It Fl t
73 Normally when
74 .Fl S
75 is specified custom tags aren't written. This option enables custom tags in
76 .Pa ~/.cboard/config
77 to be added to the output.
78 .It Fl C
79 Enable strict castling. Useful when only validating a file. This option
80 overrides the config value.
81 .It Fl v
82 Version information.
83 .It Fl h
84 Program help text.
85 .El
86 .
87 .Sh "CONFIGURATION FILE"
88 Empty lines and lines beginning with a '#' are ignored. Other lines are
89 parameter and value pairs which must be on the same line and separated with
90 one or more space or TAB characters. Options which are noted to accept a value
91 of
92 .Ar BOOL
93 can be one of:
94 .Ar true ,
95 .Ar 1 ,
96 .Ar on ,
97 .Ar yes
98 OR
99 .Ar false ,
100 .Ar 0 ,
101 .Ar off ,
102 .Ar no .
103 .Pp
104 .Bl -tag -compact
105 .It Cm engine_cmd Ar command Op args ...
106 The chess engine command to execute with any arguments. The default is
107 \&"
108 .Ar gnuchess --xboard
109 \&". Others haven\&'t been tested but any engine that supports the XBoard
110 protocol should work.
111 .Pp
112 .It Cm engine_protocol Ar protocol
113 The version of the XBoard protocol to use. At the moment all this means is
114 whether to send SAN formatted moves (protocol version
115 .Ar 2 )
116 or regular FRFR formatted moves. The default is
117 .Ar 1 .
118 .Pp
119 .It Cm engine_init Ar command
120 A command to send to the chess engine each time a new game or round is started
121 or reset. Can be specified more than once.
122 .Pp
123 .It Cm bind Ar mode Ar key Ar command Op description
124 This allows you to change the default key bindings for each game mode.
125 Each game
126 .Ar mode
127 has it's own set of commands
128 .Ar command
129 with an optional
130 .Ar description
131 which is shown in the help text. See
132 .Pa config.example
133 included in the archive for available game modes and commands.
134 .Pp
135 .It Cm cbind Ar type Ar key Ar command
136 Bind the specified
137 .Ar key
138 to the engine command
139 .Ar command .
140 The bound key will only be available in play mode and will only be sent to the
141 engine if it doesn't conflict with other play mode keys. The
142 .Ar type
143 argument specifies how a repeat count is treated. When
144 .Ar set ,
145 typing a number then pressing the bound
146 .Ar key
147 will append that number to
148 .Ar command .
149 When
150 .Ar repeat ,
151 typing a number then pressing
152 .Ar key
153 will send
154 .Ar command
155 the repeat amount of times. If
156 .Ar none ,
157 then
158 .Ar command
159 will be sent without modification.
160 .Pp
161 .It Cm macro Ar mode Ar key Ar key_sequence
162 A
163 .Ar macro
164 is like pressing a series of keys automatically without interaction. The
165 specified
166 .Ar key
167 "presses" the keys specified in
168 .Ar key_sequence
169 when in
170 .Ar mode .
171 The
172 .Ar mode
173 may be
174 .Ar play ,
175 .Ar history ,
176 .Ar edit
177 or
178 .Ar any .
179 When
180 .Ar any ,
181 global keys may be accessed.
182 .Pp
183 .It Cm jump_count Ar integer
184 When viewing move history, you can jump more than one move to the next or
185 previous move with the UP and DOWN keys. This sets the number of moves to
186 jump. The default is
187 .Ar 5 .
188 .Pp
189 .It Cm tag Ar name Op Ar value
190 Custom PGN tags to add to new games. This can also be used to overwrite
191 default tag values. It can also be used more than once.
192 .Pp
193 .It Cm line_graphics Ar BOOL
194 Enable or disable board line graphics. The default is
195 .Ar off .
196 .Pp
197 .It Cm board_details Ar BOOL
198 When enabled castling availability and the en passasnt square will be shown on
199 the board. This can be toggled with the `d' key.
200 .Pp
201 .It Cm save_directory Pa path
202 If set, the default directory where games will be saved and restored from.
203 A tilde `~' will be expanded to your home directory.
204 .Pp
205 .It Cm mpl Ar integer
206 The maximum number of full moves to write per line when saving. If
207 .Ar 0
208 then write the maximum number of moves that will fit in 80 columns.
209 .Pp
210 .It Cm save_prompt Ar BOOL
211 When saving a game, prompt to edit PGN tag data. Or when saving in history
212 mode, prompt for additional save commands. The default is
213 .Ar on .
214 .Pp
215 .It Cm delete_prompt Ar BOOL
216 Prompt before deleting games with the \&"D\&" command. The default is
217 .Ar on .
218 .Pp
219 .It Cm stop_on_error Ar BOOL
220 Stop processing a file when a parsing error occurs. Normally a game or round
221 will be flagged and the rest of the file will still be parsed.
222 .Pp
223 .It Cm valid_moves Ar BOOL
224 When a piece is selected, show valid squares the piece can move to. The
225 .Cm color_board_white_moves
226 and
227 .Cm color_board_black_moves
228 color parameters can specify alternate colors for the valid move squares.
229 The
230 default is
231 .Ar on .
232 .Pp
233 .It Cm strict_castling Ar BOOL
234 When enabled a castling move will be invalid if the opponent can attack a
235 castling square, beit the King, Rook or the squares between the two. The
236 default is
237 .Ar off .
238 .Pp
239 .It Cm pattern Ar filter
240 When in the file browser you can filter what is displayed with a
241 .Xr glob 7
242 pattern. Directories, including hidden directories, are always
243 displayed reguardless of the pattern. The default is `*.[Pp][Gg][Nn]*'.
244 .El
245 .
246 .Sh COLORS
247 .Bl -tag -compact
248 .It Cm color_board_window Ar foreground Ar background Op Ar cattr Op Ar attr
249 .It Cm color_board_selected Ar foreground Ar background Op Ar cattr Op Ar attr
250 .It Cm color_board_cursor Ar foreground Ar background Op Ar cattr Op Ar attr
251 .It Cm color_board_black Ar foreground Ar background Op Ar cattr Op Ar attr
252 .It Cm color_board_white Ar foreground Ar background Op Ar cattr Op Ar attr
253 .It Cm color_board_graphics Ar foreground Ar background Op Ar cattr Op Ar attr
254 .It Cm color_board_coords Ar foreground Ar background Op Ar cattr Op Ar attr
255 .It Cm color_board_white_moves Ar foreground Ar background Op Ar cattr Op Ar attr
256 .It Cm color_board_black_moves Ar foreground Ar background Op Ar cattr Op Ar attr
257 .It Cm color_board_castling Ar foreground Ar background Op Ar cattr Op Ar attr
258 .It Cm color_board_enpassant Ar foreground Ar background Op Ar cattr Op Ar attr
259 .It Cm color_status_window Ar foreground Ar background Op Ar cattr Op Ar attr
260 .It Cm color_status_title Ar foreground Ar background Op Ar cattr Op Ar attr
261 .It Cm color_status_border Ar foreground Ar background Op Ar cattr Op Ar attr
262 .It Cm color_status_notify Ar foreground Ar background Op Ar cattr Op Ar attr
263 .It Cm color_status_engine Ar foreground Ar background Op Ar cattr Op Ar attr
264 .It Cm color_tag_window Ar foreground Ar background Op Ar cattr Op Ar attr
265 .It Cm color_tag_title Ar foreground Ar background Op Ar cattr Op Ar attr
266 .It Cm color_tag_border Ar foreground Ar background Op Ar cattr Op Ar attr
267 .It Cm color_history_window Ar foreground Ar background Op Ar cattr Op Ar attr
268 .It Cm color_history_title Ar foreground Ar background Op Ar cattr Op Ar attr
269 .It Cm color_history_border Ar foreground Ar background Op Ar cattr Op Ar attr
270 .It Cm color_message_window Ar foreground Ar background Op Ar cattr Op Ar attr
271 .It Cm color_message_title Ar foreground Ar background Op Ar cattr Op Ar attr
272 .It Cm color_message_border Ar foreground Ar background Op Ar cattr Op Ar attr
273 .It Cm color_message_prompt Ar foreground Ar background Op Ar cattr Op Ar attr
274 .It Cm color_input_window Ar foreground Ar background Op Ar cattr Op Ar attr
275 .It Cm color_input_title Ar foreground Ar background Op Ar cattr Op Ar attr
276 .It Cm color_input_border Ar foreground Ar background Op Ar cattr Op Ar attr
277 .It Cm color_input_prompt Ar foreground Ar background Op Ar cattr Op Ar attr
278 .It Cm color_menu Ar foreground Ar background Op Ar cattr Op Ar attr
279 .It Cm color_menu_selected Ar foreground Ar background Op Ar cattr Op Ar attr
280 .It Cm color_menu_highlight Ar foreground Ar background Op Ar cattr Op Ar attr
281 .It Cm color_menu_graphics Ar foreground Ar background Op Ar cattr Op Ar attr
282 .El
283 .Pp
284 Color and attributes can be modified from the configuration file. There are up
285 to four values for each parameter. The first two are the foreground and
286 background colors which must be one of:
287 .Ar black ,
288 .Ar white ,
289 .Ar blue ,
290 .Ar green ,
291 .Ar yellow ,
292 .Ar cyan ,
293 .Ar magenta ,
294 .Ar red
295 or
296 .Ar -
297 for the default color.
298 .Pp
299 The third and fourth values are optional and set terminal attributes. The
300 third sets attributes for color terminals and the fourth for non-color
301 terminals. Multiple attributes may be assigned by separating them with a
302 comma. Note that not all terminals support all attributes. The following
303 attributes are recognized:
304 .Ar bold ,
305 .Ar reverse ,
306 .Ar dim ,
307 .Ar standout ,
308 .Ar underline ,
309 .Ar blink ,
310 .Ar invisible ,
311 .Ar none
312 or
313 .Ar -
314 for the default attribute.
315 .Pp
316 Some color parameters have a _window extension. This will set the default
317 color and attibutes for all characters for the given parameter set.
318 .
319 .Sh RETURN VALUE
320 .Nm cboard
321 will return 0 on success or 1 on failure. Failures are file access errors,
322 parsing errors or command line usage errors.
323 .
324 .Sh FILES
325 .Bl -tag -compact -width ~/.cboard/nag.data
326 .It Pa ~/.cboard/config
327 Configuration file.
328 .It Pa ~/.cboard/cc.data
329 Country codes. Used when editing the \&"Site\&" tag.
330 .It Pa ~/.cboard/nag.data
331 Appending to this file is fine for custom NAG types, but lines before 140 are
332 reserved by the PGN standard.
333 .It Pa ~/.cboard/perl.pl
334 If compiled with PERL support, a file containing subroutines that
335 .Nm CBoard
336 can filter games through.
337 .El
338 .
339 .Sh SEE ALSO
340 .Xr gnuchess 6 ,
341 .Xr ncurses 3 ,
342 .Xr glob 3 ,
343 .Xr glob 7 ,
344 .Xr regex 7
345 .
346 .Sh AUTHORS
347 .An "Ben Kibbey" Aq bjk@luxsci.net