What's it For?
In the C:\Users\Public\OoChess folder you'll find a text file called: OoChess.txt. This is a special configuration file that the OoChess helper program reads each time it is called upon to insert a PGN, a Quiz or Game or Opening Index. It's main use is to provide the user with a method of controlling the formatting of the information about each game. It also allows users of languages other than English to better adapt the output to suite their own linguistic needs.
The Two Sections of a PGN Game
The helper program will format all the games you choose to insert from a PGN file. Each game in the PGN file is formatted into two sections. The first section contains all the information of the game, such as the names of the players, the event and site of the game, etc. This information is taken from the start of each game in the PGN file. An example of this, from a PGN file, would look like this:
[Event "74th Tata Steel GMA"]
[Site "Wijk aan Zee NED"]
[Date "2012.01.14"]
[Round "1"]
[White "Navara,D"]
[Black "Topalov,V"]
[Result "1/2-1/2"]
[WhiteTitle "GM"]
[BlackTitle "GM"]
[WhiteElo "2712"]
[BlackElo "2770"]
[ECO "A20"]
[Opening "English Opening"]
[EventDate "2012.01.14"]It would be a very tiresome and tedious process if this information was simply inserted 'as is' into the document and the user had to edit it all into some presentable form. The helper program formats all this information into a presentable form for you. Here is an example:
The second style for the game information uses a simple text-based display:
Game 1
Navara D GM (2712) - Topalov V GM (2770)
74th Tata Steel R1
Wijk aan Zee, NED, 14/01/2012
The second part of a game in a PNG file is referred to as the movetext section. This is the section that contains the score, or the moves of the game, along with any commentary. In a PGN file, the movetext of a game looks something like this:
1. c4 e5 2. g3 Nf6 3. Bg2 d5 4. cxd5 Nxd5 5. Nc3 Nb6 6. Nf3 Nc6 7. O-O Be7 8. a3
O-O 9. b4 Be6 10. Rb1 f6 11. d3 Nd4 12. Nxd4 exd4 13. Ne4 Bd5 14. Bb2 f5 15. Nd2
Bxg2 16. Kxg2 Kh8 17. Nf3 Bf6 18. Qc2 Qd7 19. Rfc1 c6 20. a4 f4 21. b5 cxb5 22.
axb5 Nd5 23. Nxd4 Rae8 24. Nf3 Bxb2 25. Qxb2 Qe6 26. Qd4 fxg3 27. hxg3 Qxe2 28.
Qxd5 Re3 29. Re1 Qxf3+ 30. Qxf3 Rexf3 31. Rb2 Rxd3 1/2-1/2
This section can contain commentary, enclosed in { and } brackets, chess symbols, designated by a dollar sign, $, followed by a number from 1 to 255, and, often, something called a 'diagram marker,' which is a request to print a diagram of the current position in the game. The helper program of OoChess nicely formats this section for you, using a number of options that you can choose from.
The Configuration File Itself
The OoChess configuration file is a simple text file that contains formatting options to be used by the OoChess helper program when processing a PGN file for insertion. Here is an example:
; Here we do some format options 'o'+
ow = ""
ob = ""
oc = ""This file, which resides in the C:\OoChess folder, can be edited with any simple text editor, like Notepad. Empty lines, or lines that begin with a semicolon, are skipped during the reading of the file by OoChess, so you can use the semicolon to add comments to your configuration file as a reminder of what each option is and what you have selected.
The options themselves begin with a group letter, almost always 'o', followed by an option command letter, then the '=' sign, and the actual option setting itself. Option settings can be numbers or "strings" depending upon the option.
Formatting Options for the Game Information
Almost all of the options deal with the game information section of the PGN game and how the information will be formatted. This is especially useful for languages other than English.
Output format White ow = "string"("string" = Language-specific 'White', default = "")
This is used to set the name of the color 'White' to precede the name of the White player in the
InfoBox. Use this only if you wish to have the color of the White player written before his or her name. For example, in Spanish you might want to set the option to:
ow = "Blanco"If you don't want any color name to be written before the name of the White player, you can set this option to an empty string:
ow = ""
Output format Black ob = "string"("string" = Language-specific 'Black', default = "")
This is used to set the name of the color 'Black' to precede the name of the Black player in the
InfoBox. Use this only if you wish to have the color of the Black player written before his or her name. For example, in Spanish you might want to set the option to:
ob = "Negro"If you don't want any color name to be written before the name of the Black player, you can set this option to an empty string:
ob = ""Using Spanish as an example, the two player's names in our game would appear in the InfoBox as:
Blanco: Navara D GM (2712)
Negro: Topalov V GM (2770)
Output Format Strings in General
The OoChess helper program uses a system of place-markers within formatting strings to indicate the position of some data at which it is to be printed. Each place-marker begins with a '%' character, followed by the letter that represents the data. This sounds complicated, but it really isn't. Let's start with a very simple example, the game number output format.
The game number output format string uses the place-marker, %g, to indicate the placement of the actual game number. (The game number is incremented by one after each game in the PGN file is formatted. Thus the first game is game 1, the second is game 2, etc.) The simplest game number format string would be:
"%g"
In this case, only the number of the game would be printed, nothing more. But that might not be very useful, so you can add any other text that you like inside the format string, and it will be printed along with the game number. Here is an example:
"Game %g"
That is much more useful. Now the game number will be printed as: Game 1 … Game 2 … etc. You can already see how much more useful this method is for working with other languages.
There are three special characters that can be used inside a format string to indicate the use of
Bold,
Italic and
Underlined text. These are the * character for
Bold, ~ for
Italics and _ for
Underlined. You can use these characters to surround any text within the format string. Putting it all together, we could then write a game format string like this:
"~Game~ *%g*"
This would give us a result something like:
Game 1 ...
Game 2 … etc.
This is pretty much all you need to know about format strings in general. Now on to specific cases.
Output format Game number og = "string"(Uses %g for game number, default = "~Game~ %g")
This is used to write the game number at the top of each game. For example:
og = "~Game~ %g"Setting the og string to an empty string indicates that you don't want any game number printed at all.
Output format ECO opening code oo = "string"(Uses %o for ECO code, default = "ECO %o")
This is used to write the ECO code in the
infoBox of each game. For example:
oo = "ECO %o"Setting the oo string to an empty string indicates that you don't want the ECO code printed at all.
Output format Elo oe = "string"(Uses %e for Elo, default = "(%e)")
This is used to write each player's Elo rating in the
infoBox of each game. For example:
oe = "(%e)"The Elo format string is printed immediately following the player's name. Setting the oe string to an empty string indicates that you don't want the Elo printed at all.
Output format Event ov = "string"(Uses %v for Event, default = "%v")
This is used to write the Event of the game in the
infoBox. For example:
or = "*%v*"Setting the ov string to an empty string indicates that you don't want the Event printed at all.
Output format Site os = "string"(Uses %s for Site, default = "%s")
This is used to write the Site of the game in the
infoBox. For example:
os = "*%s*"Setting the or string to an empty string indicates that you don't want the Site printed at all.
Output format Round or = "string"(Uses %r for Round number, default = "*R%r*")
This is used to write the Round of the game in the
infoBox. For example:
or = "*R%r*"The Round format string is printed immediately following the Event name, on the same line. Setting the or string to an empty string indicates that you don't want the Round printed at all.
Output format Date oy = "string"(Uses %Y for Year, %M for Month, %D for Day, %N, %n for Month Name, default = "%D/%M/%Y")
This is used to write the Date of the game in the
infoBox. For example:
oy = "%D/%M/%Y"In the PGN game, the Date Tag looks like this:
[Date "2012.01.14"] or, showing the placement of our place-markers: [Date "YYY.MM.DD"]
You will often run across games that have a Date Tag that looks like this:
[Date "2012.??.??"]
This simply means that the month and day of the game are unknown. In such a case, only the year will be printed.
You can use the place-markers to arrange the date in any way that you like. You can also use the %N as a place-marker for the name of the month, rather than just its number. A lowercase %n shortens the name of the month to just the first 3 letters.
The Date format string is printed immediately following the Site name, on the same line. Setting the oy string to an empty string indicates that you don't want the Date printed at all.
NOTE: The use of %N and %n only provides the English names of the months! Support for other language month names is yet to be supported.
Output format Player Name op = "string"("string" uses %L,%l for Last Name, %F,%f for Fist Name, %I,%i for Initial, %T,%t for Title, default = "*%l, %i* ~%T~")
A player's name appears in the PGN White, Black or Annotator Tag as:
[White "Navara,David"]
[Black "Topalov,Veselin"]
Each of these player's can also have an associated Title Tag:
[WhiteTitle "GM"]
[BlackTitle "GM"]The place-markers can be used to construct any format you wish to display a player's name. The %T place-marker is for the player's Title, if one is available in the corresponding WhiteTitle or BlackTitle PGN Tag. This too can be added to the player's name. The use of uppercase place-markers tells the program to convert that portion of the name to uppercase, whereas the use of lowercase markers tells the program to preserve the case of the name.
The op format command is applied to
both the White and Black player names. There is a special format command just for the Annotator. Here are a few examples using the above player's names:
op = "*%l, %i* ~%T~" Navara, D GM
op = "*%L* %T" NAVARA GM
op = "%T %f *%l*" GM David Navara
Output format Annotator Name oa = "string"("string" uses %L,%l for Last Name, %F,%f for Fist Name, %I,%i for Initial, %T,%t for Title, default = "*[%l, %i* ~%T~*]*")
The Annotator's name appears in the PGN Annotator Tag as:
[Annotator "Navara,David"]The Annotator can also have an associated AnnotatorTitle Tag:
[AnnotatorTitle "GM"]The rules that apply to formatting the White and Black player's names also apply to formatting the Annotator's name. But there are two differences to note. The first is that while the OoChess helper program understands the AnnotatorTitle Tag, it is not a recognized tag in PGN, so you are unlikely to come across other software that writes this tag. So you can either edit the PGN file to add this tag yourself, or you can just ignore it altogether. (If no AnnotatorTitle Tag is present, the OoChess program will simply ignore the %T in the format string. You can always add the Annotator's title yourself directly in the document, once the game has been inserted.) The second difference is in the placement of the Annotator's name. It is written at the very end of the game itself, as in the Informant style. For that reason, the default format string encloses the Annotator's name in square brackets. You are free to change this to suite yourself.
Output format game Termination ot = "string"(Uses %w for White result, %b for Black result default = "*%w:%b*")
This is used to write the game termination, or game result. This is written immediately at the end of the game itself, just before the Annotator's name. The values of %w and %b are taken from the PGN Result Tag:
[Result "1/2-1/2"] or, with of our place-markers: [Result "w-b"]This format option allows you to specify just how you would like the game result to be displayed.
ot = "*%w:%b*"
Output format 1/2 Character o2 = "string"(default = "½")
This format options simply allows you to set the "string" to be used for the Result Tag's "1/2" used to indicate a draw. The default is to use the single character, ½, in place of the "1/2" string used by PGN. This o2 string is used when formatting the game Termination above. You could choose to go with PGN's "1/2" or you could use the "=" sign, another common method.
Formatting Options for the Game Itself
Now we come to the formatting of the game itself. There are a number of options here, most of which control the creation and formatting of automated diagrams. But first we'll look at the options that affect the appearance of the game itself.
Output format Diagram Number od= "string"(Uses %d for diagram number, default = "No. %d")
This is used to format the diagram number at the top of each diagram. For example:
od = "No. %d"Another example might be:
od = "~Diagram~ *%d*"Setting the od string to an empty string indicates that you don't want any diagram number printed at all.
Output format Diagram Caption oc= "string"(Uses %m for last move, default = "Position after %m")
The OoChess helper program can write a caption under each diagram it creates as you can see in this example:
Position
after 3... b6
The Diagram Caption format option allows you to set your own formatting. The last move played, the move that sets up the position in the diagram, uses the place-marker %m in this formatting option. The default for this option is shown in the above diagram. It would be written as:
oc = "Position after %m"You might prefer to have nothing but the last move played as the caption. In that case you could set this option as:
oc = "%m"If you wish to have no captions to your diagrams at all, you can do this easily be setting the Diagram Caption format string to an empty string:
oc = ""
Output format FEN Caption of = "string" (The FENCap)(Uses %w %b %e %s %r %y %m %c, default = "")
For PGN game fragments, you can have the OoChess helper program ignore the usual game information formatting that is used for a complete game and have the information formatted under a diagram of the initial position.
When we encounter a FEN game to be inserted, we will first check to see if the user has declared an of string. (The FENCap string.) If so, we then ignore writing the game info at the top of the game altogether, only writing the game number along with the game info, and then leave the rest to be written under the diagram in the FENCap. A example of a FENCap command is:
For this diagram, the following was used:
of = "*%w – %b*/~%s %y~ %c"For all other normal games, that begin at the initial position, the selected info type will be used.
Note that the options available for this command are:
of = "FENCap String"You can use any of these PGN tags as part of the FENCap string:
%w – White player (Last name only)
%b – Black player (Last name only)
%e – Eventually
%s – Site
%r – Round
%y – Year
%m – Move Number (As in 13... ?)
%c – Color to Move (Shown as a box)
Output format Quiz Caption oq = "string"(Uses %d %m %c %v, default = "*%d*|%m")
The caption for a Quiz diagram is controlled by the Output Format Quiz Caption command. This is placed inside the OoChess configuration file. There area four place-markers available:
%d The current diagram number.
%m The move number (as in 13... ?)
%c Color to move (shown as either a white or black box)
%v Evaluation of the position (shown as i or o depending upon game result)You are free to use the special formatting characters, * ~ and _ for Bold, Italics and Underlined. Note especially the use of the vertical bar character |. This is a special character that tells the helper program that you want the caption to be divided into two separate parts, one displayed at the left edge of the diagram, and the other on the right edge of the diagram. This can be clearly seen in the example below. If the vertical bar is not used in the oq command, then it is understood that the user wants the text of the caption to be centered over the diagram. In this case, it is more likely that all you would want is the diagram number.
Five Miscellaneous Formatting Options
Diagram Marker am = "string"(default = "Diagram #")
If your chess editing software does not have a mechanism for inserting Diagram Markers into a game, you can simply create your own Diagram Marker string, and then type it at the start of a comment after the move that gives rise to the position you want a diagram for. Once you have decided upon a Diagram Marker string, all you have to so is let the OoChess helper program know what it is. You do this using the Diagram Marker option.
am = "Diagram #"The helper program will look at the start of every comment to see if it beings with the Diagram Marker string. If it does, it creates a diagram of the current board position and writes it to the file that will be inserted into your document. It's as easy as that.
The Diagram Marker option can also be used to set the Diagram Marker string to whatever string is used by your chess software to indicate a diagram is to be printed.
Move Column Placement ac = "string"(default = "25,30,70")
This setting is used only if you have chosen the
Classical Game Style. It is the only style that uses columned game moves. You can use this option to refine the placement of the three columns. The first is the move number column, followed by the White move column and the Black move column. Here is an example:
ac = "25,30,70"In this example, the helper program will place the move number column at 25% width of the text column. The White moves will be written at 30% of the text column width, and the Black moves will be written at 70% of the width.
One thing to note about this option: The move number is a special right-justified tab stop, so its percentage value is set at the end of the numeric string, whereas the moves themselves are left-justified, so their percentage values are set at the start of the move:
23. Nxd4 cxd4
_______|____|__________|___
25 30 70
Info background Color ic = "rgb(R,G,B)"("rgb(R,G,B)"= ?, Default = ?)
This option sets the background color to use for the
InfoBox. It is only used when
Info Style is set to 1, the InfoBox. To set the background color, you must use an rgb color string as in the following example:
ic = "rgb(255, 255, 240)"The above line will set the background color to the light yellow color used in the above examples. The rgb letters refer to the primary colors, Red Green and Blue. The numbers for each color must be between 0 and 255, with 0 meaning no color at all, and 255 meaning full color. So rgb(0,0,0) is the color black, whereas rgb(255,255,255) is white. A nice light-gray is obtained using rgb(230, 230, 230).
The next group of options deal with the formatting and display of individual items from the game information section. These options make it much easier to use the helper program in languages other than English, and to tailor the program's output to meet the needs of the writer.
Game Index Title ox = "string"(default = "*Game Index*")
This setting allows you to set the name to be used for the Game Index. Alternatively, you can just as easily edit the default Game Index title once it has been inserted into your document. That is probably the easiest option. You may wish to do this in order to make the game index title a heading, such a
Heading 1, so that it will automatically be included in the TOC.
Opening Index Title oz = "string"(default = "*Opening Index*")
This setting allows you to set the name to be used for the Opening Index. Alternatively, you can just as easily edit the default Opening Index title once it has been inserted into your document. That is probably the easiest option. You may wish to do this in order to make the opening index title a heading, such a
Heading 1, so that it will automatically be included in the TOC.
