PGN with arrows and circles

Question

I recently imported a PGN file that I got from chesscafe.com into lichess.org, and was surprised to see arrows and circles on the board! Looking at the file, I figured that these graphical elements are encoded in comments like this:

{[%csl Rd4,Gd5][%cal Rc8f5,Ra8d8,Re8c8] Black will try...}

where %csl gives the color and locations of the circles and %cal gives the color, beginning, and end of each arrow.

This doesn't seem to be documented in any PGN spec I've seen, so I suppose it is an extension. My questions are: who introduced this extension, which other software supports it, and is it documented anywhere?

Answer 1

The original PGN standard was created and published in 1994 by Stephen J Edwards. Here is a copy of his original standard: Portable Game Notation Specification and Implementation Guide.

Here it mentions the use of "%" as an escape string:

There is a special escape mechanism for PGN data. This mechanism is triggered by a percent sign character ("%") appearing in the first column of a line; the data on the rest of the line is ignored by publicly available PGN scanning software. This escape convention is intended for the private use of software developers and researchers to embed non-PGN commands and data in PGN streams.

So, % in the original specification was for "the private use of software developers".

By 2001 this was already being used with Stephen Edwards dropping out from maintenance of the standard as remarked in this supplement for enhanced PGN:

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.

The document's main proposal is the further definition of how "%" should be used for embedding commands in PGN. This was targeted at time commands:

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 ]

%csl and %cal are relatively new commands following the 2001 extension definition. I found references to their use on the ChessTempo website in their Comment Markup Annotations Chapter 18. PGN Viewer BETA Version

The PGN viewer supports some special markup that allows arrows, square highlighting and mini-board insertion to be rendered on the board or move list.

Arrows To have a move show arrows on the board when it is played, you can embed the following type of string into a comment on the move: [%cal Gc2c3,Rc3d4]

the '[' and '] characters are the start and end of the arrow markup. The %cal indicates you are requesting a coloured arrow to be drawn. This example will draw two arrows a Green arrow from the c2 to c3 squares, and a Red arrow from the c3 to d4 squares. The colour letters supported are R=Red, G=Green, Y=Yellow and B=Blue. Square Colouring To have a move highlight squares on the board when it is played, you can embed the following type of string into a comment on the move: [%csl Ra3,Ga4]

The %csl indicates you are requesting a coloured square. This example will highlight two squares, a3 will be highlighted Red, and a4 will be highlighted Green. The colour letters supported are the same as used by the arrow annotations.

It looks like Chesscafe and lichess are following this beta version.