FMDATA.WRI Chess FileMate for Windows, 4.0 Copyright (c) 1994-1996 William H. Dyche Contents: 1: Introduction to formats for recorded chess games. 2: Text parsing 3: Rules for writing a PGN game 3.1: Header Section 3.2: The Movetext Section 3.2.1: Move numbers 3.2.2: Notation 3.2.3: Move continuation 3.2.4: Castling indications 3.2.5: Check, checkmate, and promotion indications 3.2.6: En-passant 3.2.7: Commentary 3.2.8: Variations 3.2.9: Partial Games 1: Introduction to formats for recorded chess games. In order for software to read information about a game, a convention on exactly what information is used and how it will be written must be established and adhered to by the creators of data and software. There have been several conventions (hereafter referred to as game "formats") in use. FileMate is designed to automatically recognize and read the formats referred to as PGN, NIC, and NTR. PGN, NTR, and NIC are all ASCII text formats, so they can be read by people as well as programs. They differ mainly in how the headers are written. PGN relies on keywords and a few special characters to clue a program in on what information is there and where it is located. The program can then extract the information and use it, e.g. to create a list of games. NIC also uses keywords. NTR is mostly a positional format; it is understood that certain information will be at certain locations in the header. Examples of all these formats are in DEMO1.TXT. The PGN format is easiest for a program to deal with because it is simply the repetition of a little motif: [keyword "value"]. PGN is well-defined, and its specifications are publicly available. It also allows commentary and embedded variations in the movetext section. Specific information about these formats, as well as a large number of games files, can be found in the libraries of the CompuServe Chess Forum. The format they prefer is PGN. 2: Text parsing (reading and extracting information from text) People are very good at extracting information from text because we have a vast amount of knowledge with which to analyze such data. But a program has only what little knowledge the programmer has been able to (tediously) build into the program to make sense out of a stream of characters. A program can quickly become confused by seemingly trivial typographical errors. On the other hand, the program can read and simply disregard text it doesn't understand. For example, FileMate can be used to read "The Week In Chess" files to view the games without having to edit the file or do copy and pasting. Just scroll the games list window down to where the games are. Things which can confuse a program: - Misuse of special characters. e.g. brackets and quotes in the PGN header tell the program where things begin and end. - Misuse of blank lines. Any two games in a file must be separated by one or more blank lines. Within the movetext section, blanks lines can be used freely to improve readability in PGN games, but not in NTR and NIC. - Each and every PGN game must end with a result string (also called the "game termination marker"). The program relies only upon this in determining where the text of a PGN game ends. Design of the program's routines for identifying the beginning and end of games is a compromise between cleverness and quickness. Don't expect perfection, e.g. sometimes non-game text may show as NTR in the File window's games list. As long as you use FileMate to create text, there should not be any data problems. The program will generate correct syntax so you won't have to worry about such technical stuff. However, some information on syntax is included here for those who are interested in it. 3: Rules for writing a PGN game You can probably write a PGN game by just looking at an example. Each unit in the header has the form: [keyword "value"]. The header should always look like the one you see below except that you supply the values enclosed in quotes. There are just a few rules you need to know. - The keywords must be spelled exactly as you see them in the example. ( "Event", "Site", etc. ) - The seven keywords shown below should always be present and in the same order. - The PGN date format is "yyyy.mm.dd". - Unknown values are indicated with question marks. - A single blank line must separate the header section from the movetext. - SAN (Standard Algebraic Notation) must be used. - End the movetext section with a result indication: 0-1, 1-0, 1/2-1/2, or * if unknown result. [Event "?"] [Site "USSR"] [Date "1903.??.??"] [Round "?"] [White "Salwe,G"] [Black "Chigorin,M"] [Result "0-1"] 1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5 4. d3 Nf6 5. Nc3 d6 6. O-O Bg4 7. Bb5 O-O 8. Be3 Nd4 9. Bxd4 Bxd4 10. h3 Bh5 11. g4 Bxc3 12. bxc3 Nxg4 13. hxg4 Bxg4 14. d4 f5 15. Be2 fxe4 16. Nd2 Bxe2 17. Qxe2 Qg5+ 18. Kh1 Rf4 0-1 3.1: Header Section PGN specs allow alot of optional information to be included in the header. For instance, an ECO opening code is often added, e.g. [ECO "B51"]. Many other officially sanctioned header keywords are documented in the PGN specifications document. All are accepted by the program. 3.2: The Movetext Section In PGN terminology, the text containing the moves is called the "movetext section". The following is some information about how FileMate expects the movetext section to be written. Move legality: The program will not play illegal moves. Historical games containing illegal moves will have to be described and explained in commentary. Standards for data portability: FileMate will read and display some things which are contrary to format specifications. e.g. descriptive or other non-algebraic notation, and comments in NTR and NIC. But it will only output syntactically correct PGN games (assuming it is designed correctly). You should avoid distributing data which does not conform to generally agreed upon format and notation rules. 3.2.1: Move numbers: Move numbers are optional but highly recommended in PGN. In FileMate, move numbers should always be used. A period appended to the move number is required also. The period may be followed by zero or more spaces. 3.2.2: Notation: The program does very little syntax checking, and no legality checking until the game is sent to the board. The program can only read English notation (piece letters: PRNBQK). 3.2.3: Move continuation: The program will recognize a move continuation like 10...Bh5. Notice there are exactly three periods and no spaces between the number and the play. PGN requires this form whenever a black play follows a comment. 3.2.4: Castling indications: The use of uppercase letter O's is strongly recomended, although the program will accept zeros instead of O's. 3.2.5: Check, checkmate, and promotion indications: The special characters + and # may be appended to plays to indicate check and checkmate. Pawn promotion may be indicated by a = followed by a piece letter appended to a play (example: b8=Q ) The use of all these indications is optional, and their validity is not checked by the program. PGN uses these indications and no others. They can be used with all the supported notations (except that NIC does not use the equal sign ' = '.) 3.2.6: En-passant: No explicit indication is used for en-passant captures. 3.2.7: Commentary PGN comments are enclosed in braces { and } or else begin with a semicolon ';'. A semicolon begins a rest-of-the-line comment. There are no rules regarding where ordinary comments should be placed in the text, except they need to be separated from moves and other elements by at least one space or newline. FileMate only allows comments in the movetext section. Any of the six suffix-annotations "! ? !! !? ?! ??" may be appended to a play. PGN annotations (which are termed "NAG"s - Numeric Annotation Glyphs) may be used. A NAG must be separated from a play by at least one space, e.g. 16. Nd2 Bxe2 $19. Result indications: The following are recommended: 1-0 (White wins) 0-1 (Black wins) 1/2-1/2 (Draw) * (The game is not finished, or the result is unknown) Some other result strings have been used, and are recognized by the program: 1/2 ½-½ +-+ (Draw) 3.2.8: Variations Quoting from the PGN specifications... >>8.2.5: Movetext RAV (Recursive Annotation Variation) An RAV (Recursive Annotation Variation) is a sequence of movetext containing one or more moves enclosed in parentheses. An RAV is used to represent an alternative variation. The alternate move sequence given by an RAV is one that may be legally played by first unplaying the move that appears immediately prior to the RAV. Because the RAV is a recursive construct, it may be nested.<< Example: 1. e4 e6 2. d4 d5 3. Nc3 Nf6 4. Bg5 dxe4 5. Nxe4 (5. Bxf6 gxf6 6. Nxe4 f5 7. Nc3 (7. Ng3 c5!) 7...Bg7 (7...c5 8. d5!) 8. Nf3 O-O 9. Qd2 c5 10. dxc5 Qa5 11. Nb5 Qxd2+ 12. Nxd2 Na6 13. c3 Nxc5 14. Nb3 Nxb3 15. axb3 a6) 5...Be7 6. Bxf6 There are no rules regarding line breaks and indentation. FileMate allows you to set breaks and indents for variations and comments. 3.2.9: Partial Games Recorded games which do not start at the initial position are called "partial games". FEN (Forsyth-Edwards Notation) is an extension of PGN which specifies how to write partial games. Partial games are useful for relatively efficient recording of chess problems. Since FEN is a text format, it can be read by both people and software. The game header must have two fields: SetUp and FEN. The starting position is described by a character string in the FEN value. Example: [Event "?"] [Site "Pick of the best Chess Problems, Paperfronts."] [Date "1994.??.??"] [Round "?"] [White "Chess Puzzle #192"] [Black "?"] [Result "1-0"] [SetUp "1"] [FEN "6b1/B1bR4/B1Q5/p7/2n1p3/2k5/1R6/K7 w - - 0 29"] 29. Qb5 $1 {Threatening 30.Qb3#} 29... Ne5 (29... Nb6 $5 30. Qxa5#) ( 29... Nd6 $5 30. Qe5#) (29... Nxb2 $5 30. Qxb2#) 30. Bd4# 1-0 The FEN string contains the following information... 1. piece placement 2. whose turn it is to move 3. whether or not castling will be possible 4. the en-passant target square, if any 5. halfmove clock - the number of plys since the last pawn move or capturing move. 6. the starting fullmove number The first 4 items are important. Filemate ignores the halfmove clock. It will use the fullmove number in the text display. A detailed description of FEN can be found in the PGN specifications document. However, you can enter all the FEN information by using FileMate's position setup dialog (except 5.). The program will automatically write and read FEN data, so you don't have to.