Each menu has it's own print function pointer.

[cboard.git] / doc / cboard.man

.\" Copyright (C) 2002-2006  Ben Kibbey <bjk@luxsci.net>
.\" 
.\" 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 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" 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.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
.
.Dd January 09, 2003
.Os
.Dt CBOARD 6
.
.Sh NAME
.
.Nm cboard
.Nd an ncurses PGN browser, editor and chess engine frontend
.
.Sh SYNOPSIS
.
.Nm cboard
.Op Fl hvN
.Op Fl E Fl t Fl V Fl S 
.Op Fl p Ar pgnfile
.
.Sh DESCRIPTION
.
.Nm cboard 
is an
.Xr ncurses
PGN browser, editor and frontend to various chess engines supporting the
XBoard protocol.
.
.Pp
The following command line options are available:
.
.Bl -tag -width
.It Fl p Ar pgnfile
Load a PGN formatted file. If the filename extension ends with .Z, .bz, .bz2,
\&.gz or \&.zip, then it will be uncompressed (and compressed if saving)
automatically provided you have
.Xr compress 1 ,
.Xr bzip2 1 ,
.Xr gzip 1
and
.Xr zip 1
installed.
.It Fl E
Stop processing a file when a parse error occurs. Overrides configuration
parameter.
.It Fl N
Enable two human player mode disabling the chess engine.
.It Fl V
Validate the specified file only. If a parse error occurs
.Nm cboard
will return a nonzero exit status.
.It Fl S
Validate the specified file and output the PGN formatted game to stdout. If a
parse error occurs 
.Nm cboard
will return a nonzero exit status.
.It Fl R
Like
.Fl S
but output a reduced PGN formatted game which includes only the seven tag
roster and move text without any annotations.
.It Fl t
Normally when
.Fl S
is specified custom tags aren't written. This option enables custom tags in
.Pa ~/.cboard/config
to be added to the output.
.It Fl v
Version information.
.It Fl h
Program help text.
.El
.
.Sh "CONFIGURATION FILE"
Empty lines and lines beginning with a '#' are ignored. Other lines are
parameter and value pairs which must be on the same line and separated with
one or more space or TAB characters. Options which are noted to accept a value
of
.Ar BOOL
can be one of:
.Ar true ,
.Ar 1 ,
.Ar on ,
.Ar yes
OR
.Ar false ,
.Ar 0 ,
.Ar off ,
.Ar no .
.Pp
.Bl -tag -compact
.It Cm engine_cmd Ar command Op args ...
The chess engine command to execute with any arguments. The default is
\&"
.Ar gnuchess --xboard
\&". Others haven\&'t been tested but any engine that supports the XBoard
protocol should work.
.Pp
.It Cm engine_init Ar command
A command to send to the chess engine each time a new game or round is started
or reset. Can be specified more than once.
.Pp
.It Cm bind Ar type Ar key Ar command
Bind the specified
.Ar key
to the engine command
.Ar command .
The bound key will only be available in play mode and will only be sent to the
engine if it doesn't conflict with other play mode keys. The
.Ar type
argument specifies how a repeat count is treated. When
.Ar set ,
typing a number then pressing the bound 
.Ar key
will append that number to
.Ar command .
When
.Ar repeat ,
typing a number then pressing
.Ar key
will send
.Ar command
the repeat amount of times. If
.Ar none ,
then
.Ar command
will be sent without modification.
.Pp
.It Cm jump_count Ar integer
When viewing move history, you can jump more than one move to the next or
previous move with the UP and DOWN keys. This sets the number of moves to
jump. The default is
.Ar 5 .
.Pp
.It Cm tag Ar name Op Ar value
Custom PGN tags to add to new games. This can also be used to overwrite
default tag values. It can also be used more than once.
.Pp
.It Cm line_graphics Ar BOOL
Enable or disable board line graphics. The default is
.Ar off .
.Pp
.It Cm board_details Ar BOOL
When enabled castling availability and the en passasnt square will be shown on
the board. This can be toggled with the `d' key.
.Pp
.It Cm save_directory Pa path
If set, the default directory where games will be saved and restored from.
Tildes `~' and environment variables are supported.
.Pp
.It Cm mpl Ar integer
The maximum number of full moves to write per line when saving. If
.Ar 0
then write the maximum number of moves that will fit in 80 columns. 
.Pp
.It Cm save_prompt Ar BOOL
When saving a game, prompt to edit PGN tag data. Or when saving in history
mode, prompt for additional save commands. The default is
.Ar on .
.Pp
.It Cm delete_prompt Ar BOOL
Prompt before deleting games with the \&"D\&" command. The default is
.Ar on .
.Pp
.It Cm stop_on_error Ar BOOL
Stop processing a file when a parsing error occurs. Normally a game or round
will be flagged and the rest of the file will still be parsed.
.Pp
.It Cm valid_moves Ar BOOL
When a piece is selected, show valid squares the piece can move to. The
.Cm color_board_white_moves
and
.Cm color_board_black_moves
color parameters can specify alternate colors for the valid move squares.
The
default is 
.Ar on .
.Pp
.It Cm pattern Ar filter
When in the file browser you can filter what is displayed with this value.
Directories, including hidden directories, are always displayed reguardless of
the pattern. The default is `*.pgn'.
.El
.
.Sh COLORS
.Bl -tag -compact
.It Cm color_board_window Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_board_selected Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_board_cursor Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_board_black Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_board_white Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_board_graphics Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_board_coords Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_board_white_moves Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_board_black_moves Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_status_window Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_status_title Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_status_border Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_status_notify Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_status_engine Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_tag_window Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_tag_title Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_tag_border Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_history_window Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_history_title Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_history_border Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_message_window Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_message_title Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_message_border Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_message_prompt Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_input_window Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_input_title Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_input_border Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_input_prompt Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_menu Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_menu_selected Ar foreground Ar background Op Ar cattr Op Ar attr
.It Cm color_menu_highlight Ar foreground Ar background Op Ar cattr Op Ar attr
.El
.Pp
Color and attributes can be modified from the configuration file. There are up
to four values for each parameter. The first two are the foreground and
background colors which must be one of:
.Ar black ,
.Ar white ,
.Ar blue ,
.Ar green ,
.Ar yellow ,
.Ar cyan ,
.Ar magenta
or
.Ar red .
.Pp
The third and fourth values are optional and set terminal attributes. The
third sets attributes for color terminals and the fourth for non-color
terminals. Multiple attributes may be assigned by separating them with a
comma. Note that not all terminals support all attributes. The following
attributes are recognized:
.Ar bold ,
.Ar reverse ,
.Ar dim ,
.Ar standout ,
.Ar underline ,
.Ar blink ,
.Ar invisible 
and
.Ar none .
.Pp
Some color parameters have a _window extension. This will set the default
color and attibutes for all characters for the given parameter set.
.
.Sh RETURN VALUE
.Nm cboard
will return 0 on success or 1 on failure. Failures are file access errors,
parsing errors or command line usage errors.
.
.Sh FILES
.Bl -tag -compact -width ~/.cboard/nag.data
.It Pa ~/.cboard/config
Configuration file.
.It Pa ~/.cboard/cc.data
Country codes. Used when editing the \&"Site\&" tag.
.It Pa ~/.cboard/nag.data
Appending to this file is fine for custom NAG types, but lines before 140 are
reserved by the PGN standard.
.El
.
.Sh SEE ALSO
.Xr gnuchess 6 ,
.Xr ncurses 3 ,
.Xr wordexp 3 ,
.Xr regex 7
.
.Sh AUTHORS
.An "Ben Kibbey" Aq bjk@luxsci.net