iBook Examples - ChessOK.com

iBook Examples 14 October 2009

Rybka Aquarium 3.2 has been released with several interesting enhancements. Some of them have been described in my recent ChessOK Cafe columns and, as usual, the Aquarium FAQ describes many of the new features.
In this column I will show a few examples that should help iBook authors better understand some of the commands available to them. I assume that the reader is familiar with my two previous iBook columns: “Interactive Chess Books in Rybka Aquarium” and “Writing Aquarium iBooks – Introduction”.

Let’s have a quick look at some of the things we have learned so far about iBooks:

In “Interactive Chess Books in Rybka Aquarium” we saw some examples of what iBooks can look like from the reader’s perspective. We saw iBook excerpts from a tournament report, game analysis, a middlegame book and an endgame magazine.
How potential errors in chess notation are automatically prevented in iBooks.
How a table of contents can be added where the author makes the final decision about the order in which the content of the book is presented.
How the creative writer has much more freedom in presenting his analysis than he is used to with traditional game analysis.
In “Writing Aquarium iBooks – Introduction” we learned how to create a new iBook and how to open iBooks.
The purpose of the various buttons, menus and options available to iBook writers.
How you can format text in iBooks: Headings, bold and italic text.
How you can easily convert moves in simple text format to live, clickable moves that display the corresponding position on the chessboard.
How you can automatically convert a fully annotated chess game into iBook format with the click of a button.
How authors can protect their commercial work from being modified, printed or exported.

Even though we have covered a lot of ground, there are many useful features that haven’t been mentioned yet. Some of them are covered in the following iBook examples.

I assume that you have already created a new iBook as was explained in “Writing Aquarium iBooks – Introduction.” After that click the “Edit Page” button on the ribbon and you are ready to follow the instructions below.

Exercises

There are many published collections of training positions, tactical and positional exercises, endgame studies, etc. You can use iBooks for such collections and present them in many different ways, depending on your requirements:

Attach the iBook to a database of your own games and collect important positions from them into the iBook. There could be chapters titled “Tactical Mistakes,” “Opening Mistakes,” “Strategic Mistakes,” or on a more positive note “Winning Combinations,” etc. Reviewing and updating the iBook once in a while makes sure that you learn from your own mistakes and don’t forget the techniques you have already mastered.
Endgame studies would show a diagram, immediately followed by the solution.
Training exercises might have pages with diagrams and links to another page with the solutions. This would be a typical setup for a printed book, but iBooks also allow you to add a link below the diagram that shows the solution there when it’s clicked.

I will take one very simple example to illustrate these different ways of presenting exercises, studies, etc. in an iBook.
As always, you have a choice of entering the moves into the book in text format or pick them up from a game in the iBook database. I will start be using the text format, but after that I’ll show that it’s even easier to get the moves from a database.
Our example position comes from a game that was played some years ago.
White can win material based on the weakness of f7, using discovered attack involving pin-breaking. Here is the game:
1.e4 e5 2.Nf3 d6 3.Bc4 Bg4 4.Nc3 c5. Here White played 5.Nxe5 Bxd1 (Black could have played on a pawn down after 5…dxe5 6.Qxg4) 6.Bxf7+ Ke7 7.Nd5#

White to move.

Method 1: Solution not hidden

For our first example, copy the game from the paragraph above and paste it into an empty page in your iBook, using the Ctrl+V keyboard shortcut. Then use the “1.e4” menu in the “Page text edit” window to convert the mainline and the variation into clickable moves as was explained in “Writing Aquarium iBooks – Introduction” (see the “Variations” section). After that you can preview the iBook by saving the text (click the button with the green check mark symbol). When you click the moves in the “Page text” window the corresponding position will be displayed on the chessboard.

At this point, the text in the edit window should look like this:

[line(1.e4 e5 2.Nf3 d6 3.Bc4 Bg4 4.Nc3 c5,0)]. Here White played [line(5.Nxe5 Bxd1,0)] (Black could have played on a pawn down after [line(5…dxe5 6.Qxg4,1)]) [line(6.Bxf7+ Ke7 7.Nd5#,0)] As you can see, only one command, “line,” is needed to create this example. It takes a sequence of moves and a second parameter which is either 0 (mainline) or 1 (variation) and converts them to links that display the corresponding position when they are clicked.
Next we want to add a diagram after the first move sequence, so add a double line break before “Here White played…”. Place the cursor in the empty line and select “Diagram for current position” from the “Other options” menu as shown in the following image.

Insert diagram.

Aquarium automatically figures out the correct position, based on where you place the diagram in the notation, so this is really easy. The resulting iBook page looks as shown below. When you click the moves, which are shown in blue color, the main board will display the corresponding position. Note that the diagram shown in the iBook itself is just like a diagram in a book and is not updated.
	Diagram with solution.

Method 2: Solution on a different page

We can use this same example to create an exercise, where the diagram is displayed without the solution. When the reader has tried to solve the exercise, he can click a link to see the solution. We will display the exercise on one page and the solution on another page, similar to printed books that have all the solutions collected at the end of the book.

Start by creating a new page for the exercise. When creating the page you can choose a page title. Call it “Exercise” if you like. The content of this page will be the first part from our previous page, plus a link that jumps to the page with the solution. Copy the following lines to your new page.

I have added some explanatory text after the “line” command and then a new command then you haven’t seen before: “open_page.” This command jumps to the page specified in the parenthesis, page number 1 in this case. Just like other iBook commands it is enclosed in square brackets; the command itself is in quotes, followed by a comma and the link text.

	When using the open_page command the first question is how do we know the number of the page we want to jump to? There are three different ways you can see the page number. As shown here, the number of the current page is always displayed in the title bar. You can also get a list of all pages in the book by clicking the “Page List” button. The page numbers are displayed in the ID column.
Page numbers.

A third method is available when you are editing a page. Then you can click the “Page options” button and the page number is displayed in the PageID field as shown in the next screenshot.
Note that it’s called PageID and not simply page number. The reason is that these numbers are different from traditional page numbers. An author who writes an iBook can write the pages (or chapters) in any order he likes. When he is ready to publish his work he can rearrange the pages any way he likes by using a classifier (which corresponds to a table of contents). There is no need to change anything in the book itself. This flexibility is invaluable for authors of bigger iBooks.

Page ID in page options.

You may have noticed that the open_page command is not available in the iBook menu system so you have to type it. The iBook menu system can be modified by the user and authors can use that flexibility to add commands, text snippets, etc. to the menu system. This can considerably speed up the writing of chess books, where certain structures are repeated throughout the book. Let’s see how we can add the open_page command to a menu.

Define new menu items.

Clicking “Edit Templates” opens a dialog box where you can add new items to this menu and define what they do.
Here I have clicked the “Add” button and given the template a name. This is the text that will be displayed on the menu. After entering the text and clicking OK, I can enter the definition of what this new item will do.

The “Jump to page” item is highlighted in the left pane and in the right pane I have entered this definition of the command:

[“open_page(:cursor:),”]
This is just the command itself, but the keyword “:cursor:” defines where the cursor will be placed after the text is added to the book. Here it will be placed where I must enter the page number, so immediately after selecting “Jump to page” from the menu I can enter the number of the page to jump to (1 in our example above). After that I place the cursor before the right bracket and enter the link text that will be displayed (“Show me the solution!” in the example).

Define the “Jump to page” command.

After adding the open_page command to our new page, it will display as shown here.
After the reader has studied the position and made up his mind about the best continuation he can click the solution link. The way we implemented this, he will be taken to the first page we created where the full solution is shown. He can play through the moves and study the solution. When he is done he can click the “Back” button to return to the page with the exercise(s). Another option is to let the solution page have a link to the page with the next exercise.

An exercise. Hidden solution.

Method 3: Solution gradually revealed

Sometimes it is more convenient to view the solution without jumping between pages. Our next example shows a simple way of doing that and at the same time gradually revealing the complete solution. The only thing that needs to be changed is how the solution link works. Start by creating a new iBook page and copying and pasting the following text into it. The first two lines are the same as in the previous example, and the two other lines contain the moves of the solution.

After pasting this text into the new iBook page, highlight the mainline (the third line in the text) with your mouse and select “set line: style 0” from the “1.e4” menu. This encloses the mainline in a set_line command, which only defines the mainline, but doesn’t display it. Next highlight the line with the 5…dxe5 variation with your mouse and this time select “set line: style 1” from the “1.e4” menu. Style “1” means that this will become a variation.

Finally, we need to add two commands to display the mainline and the variation. We use the “jump” command to do that. It jumps to the specified move number in the current line and displays the moves in the game window. An example is jump(5), which jumps to the position after White’s fifth move. A special case is jump($), which jumps to the end of the line. We need one jump command after the mainline and another one after the 5…dxe5 variation. The final version looks like this:

The image below shows how the exercise is presented to the user.
Here you can see the two links below the diagram. When the iBook is displayed, the game window is empty. After you study the position in the diagram you can click the first link to reveal the mainline. When you think you have found a better defense for Black you can click the second link. In this way you can gradually reveal the solution to an exercise instead of showing all variations at the same time.

Solution shown in game window.

Method 4: Using the database

This brings us to the most flexible way of dealing with exercises in iBooks. Instead of having all the variations and commentary as text in your iBook edit window, you can store them as an annotated game in the iBook database.

Open the database connected to your iBook. It has the same name as the iBook, but a DSN extension instead of AHB. Paste the following game into the database and save it.

1. e4 e5 2. Nf3 d6 3. Bc4 Bg4 4. Nc3 c5 5. Nxe5 Bxd1 (5… dxe5 6. Qxg4) 6. Bxf7+ Ke7 7. Nd5# 1-0

I assume that this is the first game that you add to the database. Switch back to the iBook and create a new page. We begin by selecting the game from the database. Open the “1.e4” menu and click main_game:

[main_game(1)]

You must type the number in the parenthesis, which refers to the game number in the database. In this case we want to work with the first game in the database, which should be the game shown above. Next we want to display the first four moves from the game and insert a diagram. Select “write_line” from the “1.e4” menu. You need to specify the first and the last move that are to be written. We want to start with White’s first move (1.) and end with Black’s fourth move (4…):

[write_line(1.,4…)]

Next insert a diagram in the same way as was explained before (Other options > Diagram for current position).

{d}

Finally add the following command to load the database game into the game window:

[“load_game(1),” Show me the solution!]

We’re done! This is all that is needed:

As you see it’s simpler than some of the solutions we looked at above. There is no jumping between pages and all the moves are picked up from the database game instead of being a part of the iBook itself.
One big advantage of this method is that it works equally well regardless of how complicated the game and the annotations are. If you change the game in the database, for instance, by adding verbal commentary, it will be reflected in the iBook.

Solution displayed from database.

Starting From a Non-Standard Position
In our examples above we used a complete game, starting from the normal initial position. In many cases we only have a position, such as an endgame position, but no record of how that position was reached. This situation is easily handled by iBooks. The main difference is that you must start by specifying the starting position with a FEN/EDP string. We’ll use this study by Reti as an example.
The EPD string for this position looks like this:

8/6p1/k1P2p1p/7K/8/8/8/8 w – –
Create a new iBook page for this study. The command to define the starting position is set_start_position:

Endgame study by Reti.

Here we have defined the position above and added a diagram showing the position. If we only want to show the solution itself, we could add:

[line(1.Kg6 Kb6 2.Kxg7 f5 3.Kf6{!} f4 4.Ke5 f3 5.Kd6 f2 6.c7 f1=Q 7.c8=Q Qf4+ 8.Kd5{=},0)]

We could also turn this into an exercise where reader must click a link to display the solution. It requires commands that are already familiar to us from previous examples:

It’s even easier if you have the study in your database. Create a new game in your iBook database, paste the following game into it and save it:

1. Kg6 Kb6 2. Kxg7 f5 3. Kf6 f4 4. Ke5 f3 5. Kd6 f2 6. c7 f1=Q 7. c8=Q Qf4+ 8. Kd5 {=} *

Since this is the second game we add to the database we can refer to it in our iBook as game number 2, but you can always see the id of an open game in the title bar of the Aquarium window. Now switch back to the iBook. Using the methods described earlier we add the following commands to the edit window:

When the reader clicks the link, the solution is displayed in the game window.

“Hidden” Moves
When writing an iBook, you may choose not to mention certain moves that are not central to an idea that you are explaining. Here is an example.
The author is explaining a threat that will materialize after 1.Nc6 depending on Black’s reply, but no such reply is displayed in the book. Instead the author gives a variation starting with 2.Qxh7. However, many readers might want to play through a typical variation from beginning to end. The author can allow that by using a set_line command, which contains the missing move. You can see the whole page in the iBook I link to at the end of this column, but here is the part that deals with the “hidden” move:

Where is Black’s first move?.

	Here we see that the hidden move is 1…Bxc6, so when you click, for instance, 3.Rh4# the following variation will be displayed in the game window. Here you see a full variation, which the user can play through to better understand the author’s explanation.
Black’s first move revealed.

Graphical Annotations

Besides plain diagrams, you can also add diagrams with graphical annotations to your iBooks. First add the diagram to your iBook page. This time select the “Diagram” option from the “Other options” menu in the edit window. This inserts the command “{d:}.” Add the FEN/EPD string for the position after the colon and follow it by a semicolon.

Open the game (either using the Sandbox or the database) and locate the position on the diagram. Select the “Comment” tab on the ribbon and click the “Color Marks” button to open the annotation palette. I will not go into the details of how to add graphical annotations to the position, but I think the annotation palette is fairly easy to use. When you are finished with annotating the position, select „Copy to Clipboard” from the „More options…” menu as shown in the image.

Copy graphical annotations.

Now you can switch back to the iBook and locate the diagram. Place the cursor before the right curly bracket (after the semicolon you added earlier) and then paste the graphics annotations using the Ctrl+V keyboard shortcut. The result should look something like this:

{d:5rk1/5ppp/8/5PQ1/8/8/8/8 w – -;X SNAg700}
As you can see the graphic annotation string is rather cryptic, but it does its job! You can see examples of what the results look like on the “Graphical markers” page in the iBook that you can download at the end of this column.
In the following example you can see diagrams with graphical annotations.
You can see that here the author has chosen to display only part of the board. You can do that by specifying the lower-left and upper-right corner squares of the rectangle that should be displayed. This can only be done if you specify the EPD string for the position in the diagram command:

{d:5rk1/5ppp/8/5PQ1/8/8/8/8 w – -;;e5-h8}
This example would display the part of the board that you can see in the example above.

Diagrams with graphics.

iBook Examples Download

You can download the iBook with the examples in this column here. Save the downloaded ZIP-file into the ABases subdirectory of your Aquarium directory and extract the files. After that you can open the iBook (iBookExamples.ahb) in Aquarium.

Dadi Jonsson.