pgn-standard-proposed-supplement.txt

Standard: Portable Game Notation Specification and Implementation Guide 
(Supplement)
Revised: 8 September 2001
Status: Final draft
Authors:  Alan Cowderoy (Palamede), Ben Bulsink (DGT Projects), Andrew Templeton 
(Palamede/Palview), Eric Bentzen (Enpassant.dk, Palamede), Mathias Feist 
(Chessbase), Victor Zakharov (Chess Assistant).
Contact: alan@cowderoy.com

1. Introduction

PGNs combination of a formal specification for computer use with easy 
readability and manipulation by humans has firmly established it as the data 
format of choice for representing chess games. This is a major success and a 
tribute to the quality of the work done by the original authors.

Steven Edwards, the author, appears unfortunately to be no longer involved with 
PGN and there is now no defined means of arbitrating and implementing proposed 
changes. There is also a huge body of software which implements the current 
standard and would break in various ways if it were changed.

At the same time the increased use of DGT boards in major tournaments for the 
retransmission of live games  has rendered one of the features that was planned 
for PGN but never implemented increasingly important, namely the possibility of 
encoding time information relating to each move.

Without the possibility of encoding time information in PGN its usefulness in 
the retransmission of live games is significantly weakened forcing developpers 
either to resort to proprietary formats or to break the standard.

Computer chess program authors are also now finding that they have no accepted 
way to encode such simple and recognised concepts as numeric position 
evaluations or search depth. 

Given this situation some have understandably set about defining wholly new XML 
based definitions for encoding chess games. While this work is interesting, as 
of today there is no widely accepted and supported XML schema. 

It thus seems important to us to attempt an incremental improvement to PGN 
intended to eliminate the functional weaknesses described above.

This document proposes an extension to PGN designed to offer an immediate 'work 
around' solution to the problems outlined above.

2. Design aims
2.1 The enhancements must not break the existing standard. 

This rules out new syntactical elements. Steve Edwards himself proposed a format 
(BIF) that would have resolved these problems but it was never implemented and 
doing so now would break large quantities of software.

2.2  The enhancements should maintain the ease of use and legibility so 
characteristic of PGN.

This rules out very precise but possibly more computer readable formats in 
favour of clearer human readable ones.

2.3 If new command structures are to be introduced they should be specified in 
such a way that they are usable for other extensions if needed.

The intention here is to provide a generalised syntax that will enable other 
extensions rather than only solving one particular problem (time handling in our 
case).

3. Proposals
3.1 Introduction

The only way to extend the syntax without breaking the standard is to embed the 
new command syntax into PGN comments. This is a kludge and such an obvious one 
that it was already suggested when Steve Edwards proposed the BIF format in 
1996. It is still the only option available.

Apart from a general command syntax we propose several specific commands 
designed for the handling of time information. 

We also propose the addition of a tag to the header to handle the state of the 
"running clock" where the game is being transmitted live and two other optional 
tags designed to handle special cases where the clock start times are needed.

These additions are not problematic as the standard concedes the possibility of 
adding new tags to the header (outside the mandatory seven tag roster)

Interpreting time information for a game is either difficult or impossible if 
the time controls in force are not known. PGN has a TimeControl tag for this and 
it should be regarded as mandatory when time information is to be embedded into 
the pgn.

3.2 A generalised format for embedding commands in comments.
3.2.1 Position
An embedded  command may occur at any position in a standard PGN comment, ie 
between { } .
For example:
{Optional leading comments [%clk 1:05:23] optional trailing comments} where 
[%clk 1:05:23]  is the embedded command string.

3.2.2 Structure
The command string is structured as follows.

A leading tag of [%
A command name consisting of one or more alphanumeric characters.
A space character.
Either a single parameter or a comma delimited list of parameter values.
A closing tag of ]

For example:
[%clk 1:05:23] 

3.2.3 Opening delimiter
The characters [% are redefined to indicate the start of a command sequence when 
found in between pgn comment tags.

As all ASCII characters are legal in a comment string it is not possible to rely 
on any single character as an unambiguous opening delimiter. We have chosen to 
use [%. While this also could technicaly occur in some other context it seems 
highly unlikely.

3.2.3 Commands

Command names start immediately after the [%.
They consist of one or more alphanumeric characters
They are terminated by the first space character encountered.

We are *not* proposing any fixed canonical list of commands. The idea is to 
describe a generalised command syntax, not to impose a particular set of 
commands.

We *are* proposing a set of commands to deal with time handling. "clk" in the 
example above is the proposed command name for recording move times. See section 
4 for the detailed specification of this and other time related commands.

In general software encountering an embedded command it does not understand 
should take no special action and pass the string through unchanged as part of 
the comment. 

For display purposes only presentation software, such as pgn readers, should by 
default strip out all commands before display in order to improve legibility. 

3.2.4 Parameters

This parameter syntax is based on the epd opcode syntax described at 16.2.4 of 
the pgn spec. 

A command is followed by a single space and then either by a single operand or 
by a comma separated list of operands.

An operand is either:
i) a set containing any ascii characters except the comma and right hand square 
bracket
or
ii) a double quoted string containing a set of any ascii characters except the 
double quote.

For instance:
[%command 1:45:12,Nf6,"very interesting, but wrong"]

This command has four operands, a time value, a san move value and a double 
quote delimitted string. Note that the quote delimitted string may contain 
commas.

Commas are illegal in non quote delimitted strings because the comma serves as 
the operand list separator.

Right hand square brackets are illegal in non quote delimitted strings because 
they terminate both the last operand and the command.

We have thus departed from the epd opcode specification in two ways:
i) The operand list is separated using a comma rather than a space. 
ii) Space characters are allowed in non quote delimited operands

So it is possible to pass a full FEN string as an unquoted operand as in the 
example below.
 
[%command "very tense start to the 
game",4r1k1/pp1b2r1/2n1pq1p/3p2pP/2pP2B1/P1P1Q3/2P2PPB/R4RK1 w - - 0 1,e4,d4]

This command has four operands, the first is a double quote delimitted string, 
the second is a FEN, the third is e4 and the fourth is d4.

3.2.5 Terminator
The command is terminated by a single ] character.

3.2.6 Multiple commands.
A single comment tag may contain multiple embedded commands.
For instance:
{[%clk 0:00:07][%eval -6.05] White is toast}

4. Time handling commands.
4.1 Introduction.
We propose the following commands for time handling  The first is  the command 
that DGT boards will be using to transmit times via pgn.
 
The other commands are optional and cover times that can be derived from the 
clock time. They are technicaly redundant but may be usefull for highlighting 
aspects of the game and the players use of time.

All these commands take one and only one parameter which is a time value in the 
format h:mm:ss (except for the mct command which requires hh:mm:ss)

The comments containing the embedded commands are to be taken as referring to 
the move immediately preceding them.

4.2 The clk command.

{[%clk 1:55:21]}

This is the time displayed on the players clock. It represents the time 
remaining to the next time control. It is proposed that future versions of 
software producing pgn from games played on DGT boards include this command 
after every move. 

The clk command is intended for the *automatic* recording of time values by 
digital clock/board combinations. It is not normaly intended for use with 
mechanical clocks which show a clock time rather than the time remaining to the 
next control.

4.3 Elapsed Game Time : the egt command

{[%egt 1:25:42]}

The elapsed time that a player has used for all moves in the game up to that 
point.
Takes one parameter in the format h:mm:ss 

4.4 Elapsed Move Time : the emt command

{[%emt 0:05:42]}

The elapsed time that a player used for the commented move.
Takes one parameter in the format h:mm:ss

4.5 Mechanical Clock Time : the mct command

{[%mct 17:10:42]}
The time actualy displayed on a mechanical clock. Notice that here the time 
format is hh:mm:ss. 
 
5. The "Running Clock"
The syntax described above allows us to encode a move time for a *completed 
move*. This is all well and good but during transmission of a live game it can 
also be interesting to know the state of the clock of the player whose turn it 
is to move *but who has not yet done so*.

5.1 The Clock tag
We propose that this information should be encoded in a new header tag.

[Clock "B/0:45:56"]

As only one clock is running at a time only one tag is necessary. 

In the example above Blacks clock is running and is currently showing the time 
indicated by the string following the /.

Clock is the name of the tag.
It is followed by a string constructed as follows:
The first character is either "W" (whites clock is running), "B"  (blacks clock 
is running) or "N" (the clocks are stopped).
This information is technicaly redundant as it could be calculated by looking at 
which side last moved. Encoding it here avoids this calculation and also covers 
the situation where a player forgets to switch the clocks. It also allows us to 
cover the admittedly rare case where the clocks are stopped.

The second character is a "/" seperator.
The rest of the string is a time in the format h:mm:ss which indicates the 
currently displayed clock time of the running clock. As for the clk command this 
represents the remaining time to the next time control.

6. Clock Start Time.
6.1 Introduction.
Two optional tags are proposed to record the clock setting at the start of the 
play.
While it may be helpfull to record normal clock start values here (as is done in 
the example below) they are mainly intended to cover the case where a game is 
adjourned and the displayed clock times at start of play are thus non standard. 

eg.
[WhiteClock "1:07:00"]
[BlackClock "0:56:00"]

7. As explained above the existing pgn tag [TimeControl]  (cf 9.6 and following 
of the standard) should be regarded as mandatory when move times are supplied. 
Clearly when manipulating time information about a game details of the time 
controls in use are vital. 

8. Example game.

[Event "?"]
[Site "Madrid"]
[Date "1995.??.??"]
[White "Beliavsky, A "]
[Black "Timman, J "]
[Result "1-0"]
[ECO "E35"]
[Round "2"]
[TimeControl "40/7200:3600"]
[WhiteClock "2:00:00"]
[BlackClock "2:00:00"]
[Clock "W/1:34:56"]

1. d4 {[%clk 1:59:01]} Nf6 {[%clk 1:59:32] Timman hesitates slightly} 2. c4 
{[%clk 1:58:00]} e6 {[%clk 1:57:01]} 3. Nc3 {[%clk 1:37:00] Beliavsky clearly 
suprised here takes a full [%emt 0:20:00] on this move} Bb4 {[%clk 1:54:25]} 

Game notes:

8.1. The time control is specified as 40 moves in two hours and then one hour to 
finish. This tag must be specified in order to permit calculation of such 
information as elapsed time since start of game. It is also particularly 
important that it be specified when fischer or bronstein time controls are used.

8.2. In the example we have given the White and BlackClock tags but in this case 
this was redundant as the clocks were set as normal to show that two hours 
remained to the first time control. If the White and BlackClock tags are absent 
start times should be derived from the TimeControl tag and/or the Time tag, 
where they are specified they take precedence.

8.3. The Clock tag, which is only relevant during live transmission of a game, 
here shows that it is whites turn to move and that he/she has 1 hour 34 minutes 
and 56 seconds remaining on their clock.

8.4. PGN generated directly from DGT boards will have a clk command like the one 
following the first move after *all* subsequent moves.
 
8.5. In this example we imagine that the pgn has been further edited to include 
additional text comments and commands (cf the %emt command after whites third 
move.) 

8.6. Notice that commands can appear at any point inside comments and that there 
may be multiple commands in a single comment.

8.7. The Beliavsky/Timman game is real, all the rest is pure invention.

9 Authors websites:
DGT Projects: http://www.dgtprojects.com/
Chess Base: http://www.chessbase.com/
Chess Assistant: http://www.chessassistant.com/
Palview: http://www.enpassant.dk/chess/palview/

10. Thanks
Many thanks to Axel Fritz and Robert Ericsson

*additional notes:

1. Cf Steve Edwards discussion of the planned implementation of BIF format here: 
http://groups.google.com/groups?hl=en&safe=off&ic=1&th=1fe06718d5ec89a5,20&seekm
=4psfnl%24i5m%40darkstar.UCSC.EDU
We ruled out the use of < > as delimiters specified in the BIF format because if 
this syntax is pasted into an html document then parsers will ignore the 
contents as an unrecognised tag.  This is not the effect we want.
 
2. While the seven tag roster is very precisely specified the PGN specification 
does envisage the specification of new optional tags. We have taken advantage of 
this to specify several new tags.

Note also that there is already a [Time] tag - this denotes the time of the game 
start (and not anything else).

3. For reference the current pgn standard is here 
http://www.clark.net/pub/pribut/standard.txt