Palview3 Manual  *   The Palview Pages  *   The Palview Developers Forum  *   Home  *   Palamede

Palview3 and Portable Game Notation (PGN)

Palview3 expects the games you want to publish to be in a special file type called Portable Game Notation. Essentially a Portable Game Notation file is a simple text file, but it has the extension PGN. You can load and edit a PGN file using any simple text editor such as Notepad. A PGN file can contain one or more games, as many as you want to publish as an Html-JavaScript page.

The best and easiest way to obtain a PGN file of the games you want to publish with Palview3, is to create the games using the software that you use to maintain your chess database. Use your software to enter the moves of the game, add any commentary that you want, and add any variations as well. Once you have entered your games you can have your software export them to a PGN file. Just about every chess program these days supports PGN, so you shouldn't have any difficulty doing this. Consult your program's documentation if you don't already know how to export to PGN.



Palview3 PGN Index


PGN Basics A quick tutorial

New PGN Tags

Palview3 and PGN Comments

Chess Symbols

Continuations and Null Moves Something new to play with



PGN Basics

Once you have a PGN file, you may want to edit the file by hand, using an editor like Notepad, in order to take advantage of Palview3's new features. This means that you will need a basic working knowledge of PGN. The actual details of PGN are too numerous to be completely covered here, so we recommend that you get a copy of the PGN Standard to use as a reference. What we will cover here are the PGN basics and the special features and extensions of Palview3 and how to access them from PGN.

Here is a short PGN example:

[Event "State Ch."]
[Site "New York, USA"]
[Date "1910.??.??"]
[Round "?"]
[White "Capablanca"]
[Black "Jaffe"]
[Result "1-0"]
[ECO "D46"]
[Opening "Queen's Gambit Dec."]
[Annotator "Reinfeld, Fred"]
[WhiteTitle "GM"]
[WhiteCountry "Cuba"]
[BlackCountry "United States"]

1. d4 d5 2. Nf3 Nf6 3. e3 c6 4. c4 e6 5. Nc3 Nbd7 6. Bd3 Bd6
7. O-O O-O 8. e4 dxe4 9. Nxe4 Nxe4 10. Bxe4 Nf6 11. Bc2 h6
12. b3 b6 13. Bb2 Bb7 14. Qd3 g6 15. Rae1 Nh5 16. Bc1 Kg7
17. Rxe6 Nf6 18. Ne5 c5 19. Bxh6+ Kxh6 20. Nxf7+ 1-0

Notice that there are basically two sections to a PGN game. The first part is called the Tag Section while the second part, where the moves are recorded, is called the Movetext Section. The Tag Section consists of a set of lines that take the form:

[TagName "TagValue"]

These tags are used to record information about the game, such as the names of the players, where the game was played, the date, etc. Note that the case of the Tag name is sensitive, that is, WhiteTitle is NOT the same as whitetitle. The first seven tags in the above game, Event, Site, Date, Round, White, Black, and Result, are all considered mandatory for each and every game in a PGN file. There are many other tags that are also commonly used to record other game information, such as the ECO tag, but these tags are not mandatory.

The Movetext Section records the moves played in the game using SAN, or Standard Algebraic Notation. The Movetext Section ends with the game result, which must be one of "1-0", "0-1", "1/2-1/2", or "*". The last, "*", is used to indicate that the result of the game is unknown.

Comments can be added to the moves of your game by surrounding them in the curly brackets { and }. You can also use a hard Return, or newline, inside the comment. Here is an example:

1. e4 e5 2. Nf3 Nf6
{These are the opening moves of the Petroff Defense.}

You can add symbols to your chess moves using any combination of the '!' and '?' characters. PGN supports:

!  - A good move
!! - An excellent move
?  - A bad move
?? - A blunder
!? - An interesting move worthy of attention
?! - A doubtful, or dubious move

The above combinations can be placed directly after any move, as in this example:

1. e4 e5 2. Nf3! Nf6!?

PGN also supports a set of chess symbols that are referred to as NAGs, or Numeric Annotation Glyphs. These NAGs are formed by the '$' character immediately followed by a number from 0 to 255. Each of the NAGs from 1 to 139 have meanings assigned to them by the PGN Standard , while NAGs from 140 to about 167 have been given additional meaning by ChessBase to support a number of their chess symbols. The value 0 is reserved by PGN for software testing purposes, so it does not have any meaning. (Please consult the PGN Standard for the meaning of the symbols from 1 to 139.)

A NAG can be placed after any move, as in the following example:

1. e4 e5 2. Nf3 $1 Nf6 $28 $32

Your chess software will export most chess symbols you use in your games to PGN using NAGs. This is probably the best way to get these symbols into your games, since it is difficult for people to remember the NAG numbers associated with each symbol.

The only other vital piece of basic PGN knowledge that you need is how to enter variations into your game. This is done using the round brackets ( and ) to enclose the sequence of moves in the variation. Consider the following short example:

1. e4 e5 2. Nf3 Nf6
(2... Nc6 {is the usual reply here, and it generally
leads to the Ruy Lopez opening with} 3. Bb5)
3. Nxe5 d6 4. Nf3 Nxe4 5. d4 d5

In the above example you can see that the moves inside ( and ) form the variation, namely 2... Nc6 3. Bb5. In PGN the start of every variation takes back the last move played before the variation is played. In our example, the move 2... Nf6 was taken back. You can have variations inside variations, simply by introducing another set of moves enclosed inside ( and ) inside the original variation.

This should provide you with enough of the basics of PGN to be able to create your own PGN files and to understand and edit any PGN files created by your own software. For a more detailed understanding of PGN, please read the PGN Standard itself. It is an exciting read, with a surprise cliff-hanger ending. (I can hardly wait for the movie.)



New PGN Tags

Palview3 has introduced a number of new PGN Tags. These tags were created in order to supply new game information to the program in order to take advantage of new features.

[AnnoCountry "country_name | FIDE code"]
[BlackCountry "country_name | FIDE code"]
[WhiteCountry "country_name | FIDE code"]

For example:

[AnnoCountry "United States"]
[BlackCountry "USA"]
[WhiteCountry "USSR"]

The first of these new tags is the Country group. Each of these tags is used to indicate the player's Country, or the Annotator's Country in the case of AnnoCountry. This information is used by Palview3 to provide an image of the flag for the player's country. (This assumes that you have set the flags INI option.) You can provide the country itself by using either the name, as in United States, or the FIDE code, as in USA. It is recommended that you use the FIDE code in order to avoid spelling errors. A complete list of the country names and FIDE codes are provided in the section, The Palview3 Flags.

One other special case where country information can be scanned for by Palview3 is in the player's name tag. Sometimes people will place the FIDE code of a player's country at the end of the name inside round brackets, as in this example:

[White "Kasparov, Garry (RUS)"]

It is not recommended that you use this method to pass country information to Palview3, but the program will look for it just in case.

[AnnoElo "2600"]
[AnnoTitle "GM"]

These two tags are provided to round out the available tags for the game annotator, indicated by the Annotator tag. (The White and Black player's each have their own Elo and Title tags.) The values will be used by Palview3 when formatting the Annotator's name at the end of the game. For example, if Kasparov was the Annotator, you might see something like this at the end of a game:

[Kasparov GM (2820)]

[BlackClock "h:mm:ss"]
[WhiteClock "h:mm:ss"]

The new clock tags above are new to PGN and were introduced for Live game broadcast. They reflect the starting clock times for White and Black in the case where a game has been resumed from adjournement, in which case the player's clocks would be different. These tags will only be written by special software that writes PGN files while directly monitoring DGT boards. There will be no reason for you to enter these tags, but at least you know that Palview3 supports them. (See Palview3 and Live Game Broadcast for more information.)

[JsCom "p3command(s)"]

The JSCom is not completely new to Palview as it was introduced in Palview2. You can use this tag to preflip the chess board on the Html page or to preposition the chess board to a particular move in the game. The two commands that can be passed inside the JsCom are: flip and startply. The flip command can have a value of 0 or 1. The value 1 will preflip the board so that the black pieces appear at the bottom of the screen. The startply command is passed the ply number of the move you want to prepostion to. If you use both commands in the same JsCom tag, then you use a ':' to separate them as in this example:

[JsCom "startply 4:flip 1"]

In the above example the board will be flipped and the board will be prepositioned after Black's 2nd move.



Palview3 and PGN Comments

Intro Comments

Because Palview3 is a publishing tool, it provides an extensive set of options that can be used from within PGN comments. In fact, the comments themselves can have more or less significance, depending upon where they occur. For example, some chess database software, ChessBase for example, allows you to provide a comment before a move, as well as after. This means that the very first move in a game can have a comment before it. Palview3 treats all comments before the first move of the game as a special Game Introduction comment (or comments if there are more than one). What Palview3 does is write this comment to the Html file using a special CSS class named .pintro. This provides the webmaster with the option of providing special formatting for these comments. For example, you might use a different font and italics as in the example below:

For more information on the .pintro CSS class, please see the section Palview3 and Cascading Stylesheets.

Linebreaks and Multiple Paragraphs

As suggested above, Palview3 allows multiple comments to appear in a row. The program will treat each of these comments as a separate paragraph. But these multiple paragraphs will only appear in the Html page as separately indented if the INI option linebreaks is set to on, otherwise they will appear to be merged together with no linebreaks. The ability to treat separate multiple PGN comments as paragraphs is especially useful for deeply commented games. In this case, you would likely want to use an IFRAME for the game itself by using the htmltype = iframe.

Chess Moves in Different Languages

Palview3 also performs special processing inside the comments themselves. For example, the program will look for chess moves in the comments and will replace the piece letters P,N,B,R,Q,K with the pcletters from the selected language. So if you have set the pcletters = "BSLTDK", then Palview3 will replace each instance of a chess move using PNBRQK with BSLTDK.

Figurines Within Comments

The program will also look for the special instances of a slashed piece letter as in: \P \N \B \R \Q \K and will replace each of them with either a figurine, using the special .pf CSS class, or with the appropriate piece letter from pcletters. These special slashed piece letters are used to provide figurines where they are not actually a part of a chess move inside a comment. For example, you might write something like:

35 ... Kxg7
{And after this move we are left with a 
drawn \K + \P vs \K + \P ending.}

In the above example, if figurines is on, then Palview3 will replace each \K and \P with the appropriate figurine using the special .pf CSS class. Otherwise the slashed piece letter is simply replaced with the appropriate piece letter from the pcletters INI option. (For more information on the .pf CCS class, see Palview3 and Cascading Stylesheets. For more information on using figurines with Palview3, see Palview3 and Figurines.)

The Diagram Marker and Board Caption

Palview3 also looks for the special Diagram Marker command that ChessBase exports to PGN as a '#' character as the first character in a comment. Whenever Palview3 encounters a Diagram Marker, it will generate a static diagram of the current board position in the game. The program also allows an optional Board Caption to follow the Diagram Marker, which is surrounded by the square brackets [ and ]. The text in the Board Caption will be placed under the static diagram itself. An example is:

1. e4 e5 2. Nf3 Nf6
{#[The Petroff Defense]This is the starting
position of the Petroff Defense.}

The use of the Diagram Marker, and Board Caption, is really intended for the special htmltype = static page, but it is also legal in the other page types and will generate the appropriate static diagram. This is almost never useful except in rare instances. But for the static page, the Diagram Marker is the only way to get Palview3 to generate a diagram for you. So it is an indispensable feature for static pages.

New PGN Command Extension

Palview3 has begun to take advantage of a new extension to PGN championed by our own Alan Cowderoy and DGT's Ben Bulsink. The new extension provides a method for inserting new PGN data or new publishing commands into the comment of a game. Essentially, the idea is to enclose the command and its operand(s) inside square brackets and to prefix the command name with a '%' character. These commands can only appear inside a comment, this way older software will still be able to read the PGN file. Here is an example:

1. e4 e5
{I would have played 1... c5 here, myself. [%anno "Kasparov"]}

The above example shows how the new PGN extension is used. Palview3 understands the %anno command extension and will replace the entire [%anno "Kasparov"] with a SPAN of Kasprov's name using the .panno CSS class. This allows for comments from multiple sources to be correctly attributed to each of the annotators.

The Captioned Diagram

Another possibly useful command extension is the Captioned Diagram. With this new feature you can embed a diagram directly inside a comment. When Palview3 generates an Html-JavaScript page for you, your viewers will see a small chessboard image inside the comment that has a hand pointing to it. They can click on this image and the embedded diagram will be shown on the chess board along with any caption that you may optionally provide. Below is an example of what your viewers would see.

Palview3 remembers the 'state' of the game, so showing a Captioned Diagram does not affect the playing of the moves. Your viewers can simply click on the Forward button and the next move in the game will be played.

Entering a Captioned Diagram requires you to provide the FOR of the position (the FOR is just the position part of a FEN) along with the optional caption text. Here is the Movetext portion of the PGN file that was used to create the above game:

{This very short example illustrates the use of the new
Captioned Diagram feature. You can insert a CD in any PGN
comment. If you click on the small board square the CD
will be shown on the chess board.}

1. e4 {Here is a Captioned Diagram:
 [%cap 8p4ppp82pp484P3PP3PPP8,"The Hanging Pawns"]
 And here is the same caption with some important squares marked:
 [%cap 8p4ppp82ppO32VVX31P2P3P4PPP8,"Important Squares"].}
1-0

The actual Captioned Diagram command has the format:

[%cap FOR,"caption string"]

In the above, the "caption string" is optional, but if you provide one you must separate it from the FOR of the position using a comma. The caption string must be surrounded in quotes. The FOR portion of the Captioned Diagram does not require you to add the '/' character between the ranks of the chess board position. You can add them if you wish, for the sake of clarity, but they are not mandatory.

Special Board Markers

You will also notice in the above diagram that a number of the board squares have been marked with a dot, cross, and circle. These are new to Palview3 and can be used to mark special squares. You use these special board markers just as if they were new piece types and you enter their piece letter into the FOR just like any other piece. In the FOR that was used to create the position, the dot is a 'V', the cross is an 'X', and the circle is an 'O' (upper case o).

For further information about the new PGN extension, see the document PGN Supplement. For more information on FEN and FOR, see the PGN Standard .



Chess Symbols

Palview3 understands the chess symbols used by ChessBase software. Those who are familiar with ChessBase 8.0 or 7.0 will recognize the table of chess symbols below. When you export a game to PGN from ChessBase 8.0 it will convert any chess symbols you have used to the NAG values below. Sometimes it will convert special symbols you use inside your comments to the CSMs as shown in the tables.

How Palview3 converts your PGN file's use of NAGs and CSMs depends upon how you set the symbolmethod INI option. If you set it to gif, Palview3 will replace each NAG and CSM with a GIF image of the actual chess symbol. If you set symbolmethod to text, then the program will convert the NAGs to its equivalent CSM. Using CSMs can reduce the size of your Html file(s), but if you are only using a few symbols you should set symbolmethod to gif.

One note of caution. You should only use the CSMs inside comments. While Palview3 does attempt to look for them even after chess moves, it is not recommended that you use them in that manner. Using CSMs outside of comments does not conform to the PGN Standard and may very well cause other software problems if they try to read such PGN files. All in all, it is best if you use your database software to enter chess symbols into you PGN games and then let Palview3 take it from their. The one exception to this rule is in regard to the symbols !, ?, !!, ??, !?, and ?!. These symbols can be used as is and they conform to the standard.

Palview3 also recognizes the new initiative by ChessBase to use a modified NAG format inside PGN comments so that chess symbols can be converted to and from a PGN file. Under this new scheme, by Mathias Feist, you can use two '$' characters for NAGs inside PGN comments. This allows the symbol's value, or meaning, to be retained so that it can be written to and read from PGN. Under this scheme, you can write:

1. e4 e5
{I always get at least $$15 from 1... c5! Kasparov}

In the above example, the symbol for NAG 15 is 'Black has a small advantage'. Using the new scheme, you can get ChessBase software to 'read' the $$15 in your PGN file and replace it with the proper symbol.


Continuations and Null Moves

When annotating a game it is sometimes useful to be able to play a series of variation moves by one player to show his plan or to demonstrate some tactical motif. Palview3 has introduced two new extensions to PGN that enable you to do just this. These extensions are called Continuations and Null Moves. But be forewarned! These extensions are not legal according to the PGN Standard so your chess software will not be able to understand any PGN file that you create that uses them. Furthermore, you should under no condition try to share such a PGN file with others, otherwise you'll only annoy them and receive their wrath. Because of this, we have made the decision to automatically disable the pgnlink INI option whenever the program detects either a Continuation or a Null move in the PGN file. This is to avoid spreading around PGN files that cannot be read by other software.

Plaview3 is, after all, a publishing tool, so it is perfectly acceptable to use these new extensions to publish your games to the web as a replayable Html-JavaScript file. But just how do you take advantage of these new extensions?

Your chess software will not be able to enter Continuations or Null moves into your PGN game, you will have to do this by editing the PGN file by hand. But this is not as difficult as you might imagine. You can use any simple text editor to do this, such as Windows Notepad program. We recommend that you use a proper chess database program, such as ChessBase 8.0, to enter as much of the game as possible. You can then export the game to a PGN file and use that file to begin your editing.

Continuations

A Continuation is simply a variation where the last move played before the variation is not taken back prior to the start of the variation moves. Consider the following example:

1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 g6
6. Be2 Bg7 7. Be3 Nc6 8. Nb3 Be6 9. f4 O-O
(*{So far the game has proceeded in conventional vein,
and now one would expect the equally routine} 10. O-O)
10. g4!?

As you can see from above, a Continuation is a special form of the variation that begins with (*. In other words, the character immediately following the '(' must be an asterisk, or '*'. In a normal PGN variation, the last move played before the variation is taken back. In this case, the move that would be taken back is black's 9... O-O. Therefore the first move expected in the variation would be another 9th black move, or 9... move. But in the Continuation, black's 9... O-O is not taken back at all, so the first move expected in the Continuation is white's 10th. In our Continuation example above that move is 10. O-O. Notice that once the Continuation ends, the very next move in the actual game is 10. g4.

The example also illustrates one reason why you might want to use a Continuation. The short note above is taken from Alexander Alekhine's annotations of his game against Mikhail Botvinnik in the 1936 Nottingham tournament book. In his game notes, Alekhine shows the routine and expected continuation after black's 9... O-O before actually showing what he played. This creates suspense and it is often the way that annotators think about their games. You will see this technique used quite often in chess books, but you cannot enter such a continuation directly into a PGN game. Using Palview3's new Continuation you can at least publish such games to the web.

The thing to remember about Continuations is that the move played before it is not taken back.

You can use your usual chess software to assist you in creating a Continuation. The way to do this is to replay the move that is taken back, and then edit this normal variation afterwards to make it a true Continuation. For example, if Alekhine were alive today, he could use his usual chess software to rewrite his above notes as follows:

1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 g6
6. Be2 Bg7 7. Be3 Nc6 8. Nb3 Be6 9. f4 O-O
( 9... O-O {So far the game has proceeded in conventional vein,
and now one would expect the equally routine} 10. O-O)
10. g4!?

Now Alekhine would only need to load the PGN file into Notepad and simply remove the replayed move and make the variation a Continuation. He would simply make this small change:

...
(*{So far the game ...
...

As you will see next, Continuations can be a powerful annotation tool when combined with Null Moves.

Null Moves

Null Moves allow you to play out a series of moves by one player without any moves played by the opponent. A Null Move acts as a placeholder for an expected move that is not played. This can be a useful device to show what a player is planning or to demonstrate some strategic or tactical motif. You will often see this technique used in chess books. For example, Informant uses the symbol to indicate what a player is threatening. But this indicates what will happen if the opponent takes no action to thwart the threat. In other words, if the opponent does not move.

The Null Move itself is represented by <> and can only appear inside a variation.

Below is an example of the use of Null moves to show what a player is threatening, or planning:

1. d4 d5 2. Nf3 Nf6 3. e3 c6 4. c4 e6
5. Nc3 Nbd7 6. Bd3 Bd6 7. O-O O-O
8. e4 dxe4 9. Nxe4 Nxe4 10. Bxe4 Nf6 11. Bc2
(* {With a view to} <> 12. Qd3 {and} <> 13. Bg5 {, threatening}
<> 14. Bxf6 {and} <> 16. Qxh7#)
11... h6
{Black meets the threat but weakens his \K-side.}

In the above example, you can see that a series of Null moves have been combined with a Continuation. Each of the <> represents a Null black move. Palview3 will turn this into the following:

First of all, notice that the program removes the Null move symbols, namely <>, from the actual game so that you only see:

With a view to 12. Qd3 and 13. Bg5 , threatening
14. Bxf6 and 16. Qxh7#

You will also see in the above example that we have clicked on the the move just before the Continuation begins with the Null moves. The position is shown on the board. If we now click on the Step button, , it will toggle into the Step mode, , and we can use the Forward button, , to Step through the Continuation moves. You will see the four white moves played one after the other until you arrive at the end of the Continuation. The screen would then look like the example below.

The only restrictions that apply to Null Moves are that you cannot have two consecutive Nulls, such as 1. e4 e5 2. <> <> 3. Nf3; you cannot begin a normal variation with a Null; and Null moves can only appear inside variations. (This last restriction only makes sense, after all what would be the point of playing a black move, then taking it back, then playing a white move instead?) Note that this last restriction does not apply to a Continuation. You can certainly begin a Continuation with a Null, in fact, our example above does begin with a Null move.