Dadi Jonsson «Introduction to Writing Aquarium iBooks»

Dadi Jonsson «Introduction to Writing Aquarium iBooks» 11 August 2009

In February 2009 I described a new feature of Rybka 3 Aquarium, Interactive Chess Books or iBooks.
At that time the tools for creating iBooks were rather primitive, but a new version of Aquarium is expected soon and improved iBook writing tools are among the enhancements.
In this column I will show you the basics of creating iBooks – enough to get you started writing your own.
Just keep in mind that there are a many features that I only mention briefly, or skip completely, including some that are quite useful for larger writing tasks.

Based on the experience so far, we can see that iBooks are suitable for both small and large projects. You may prefer to use iBooks for your own personal annotations, for presenting tactical exercises and other training material, for web publishing, for preparing forum posts, etc. It has also been used successfully for jobs such as converting a 200 page chess book to iBook format.

Creating an iBook
When starting an iBook, you may already have a database with the games that you want to use for the book. Otherwise you must start by creating a database. Switch to the database page or the Sandbox and select the Database tab in the ribbon.
Click the ‘New’ button (highlighted in the screenshot below) and the “Data source properties” dialog box will be displayed.
Here I have given the database the name “My-iBook” and when I click OK, a new window will be shown where I can define the game header fields. I accepted the defaults and clicked OK again. The database has now been created. This database will hold the games that I will use in the iBook. Note that we have created a native Aquarium database; this is the only type of database that can be used for iBooks.

Next we must tell Aquarium that we want to use the database for creating an iBook. The Database tab should still be active in the ribbon. Click the tool button in the lower right-corner of the Database group.
Make sure that the new database you created is highlighted in the sidebar and then select “This database has i-Book attached to it” as shown in the image above.
Finally click OK and an iBook will be created with the same name as the database.
You only need to go through the above steps once for each new iBook and if you are basing it on an existing database, only the second step is required.

An iBook created for the current database.

From now on you can use the games in the database as input for your iBook. Since Aquarium keeps a live connection from the database to the iBook, you can be sure that the moves and variations in the iBook are an exact copy of the moves in the database. This eliminates many types of errors that are common in chess books.
	A live connection from database to iBook.

You can open and update the iBook database like any other database, even after you start writing. After all it is just a normal Aquarium database. Of course you have to be careful when you change games that are already being used in the iBook. The changes will be reflected in the iBook, which can be very convenient, e.g., if you find an improvement to a variation. In such cases it is often sufficient just to update the variation in the database and the iBook will be automatically updated.

Let’s say that you are going to write an iBook, but you don’t have the games, game fragments, and such in database format. This could, for instance, be the case if you are converting a printed book to iBook format. Then you would have all the moves in the text itself, but you need a way to convert them into something that the computer can understand and display on the chessboard. This is also supported in Aquarium and even here you get additional quality control, as illegal moves will be rejected.

Each author can decide how he writes the book. Some may prefer the database approach, where all the moves and variations in the book come from the database, while others like to do all their work within the book itself. Of course you can also mix the two methods within the same book, if you like.

	Opening an iBook After creating (or downloading) an iBook, you can open it just like a normal database. After clicking the Open button on the Database tab, the standard Windows file open dialog box will be shown. Here you should set the file type to *.ahb, which is the file type for iBooks, and then locate and select the book you want to open.
The iBook file type is .ahb*.

When you open a newly created iBook for the first time, you will see a chessboard, a “Game” window below the board and a “Page text” window on the right. The book itself will be displayed in the page text window. It can automatically load the correct game into the game window. The game window also shows moves that you play through in the book, solutions to tactical exercises, etc.
	The iBook working area.

	The iBook Ribbon Tab The iBook ribbon tab is split into three groups: “Browse”, “Edit” and “Options”. Back/Forward: These buttons have similar function as in web browsers where you can go backward and forward through recently viewed pages.
The “Browse” group.

Refresh: This button updates all windows in the working area.
Move to Sandbox: Moves the contents of the game window to the Sandbox. This function can be useful if you run into an interesting position or game in an iBook and want to analyze it further.
Search: Searches for text in the current iBook.
Page List: Displays a list of all pages in the iBook and allows you to jump directly to the selected page. A page in an iBook is usually a section or a chapter.

These three buttons are the most interesting for iBook authors.

New Page adds a new page to the book. It also lets you choose options for the page, such as if the board and game window should be displayed and actions that are performed when the page is displayed. You can change all these options at a later time and we’ll have a closer look at them when we change the options for the pages in our new iBook.
Book Options opens a dialog box where you can set global options for the book.

The “Edit” and “Options” groups.

If you select “Show tree panel” then the tree will be shown by default. You can override this option for individual pages.
A classifier is the table of contents for the iBook and “Show classifier” determines if it is displayed or not.
The author decides which pages go into the table of contents and how it is structured.
This means that he can write the book in any order and then reorganize the chapters and sections as he wishes before publishing the book.
The size of chess diagrams in the book is determined by “Diagram size (pixels)”. You can change the size at any time and all the diagrams will be resized automatically.

Global iBook options and access rights.

Sometimes you may want a specific page displayed when readers open your book. They may, for instance, prefer to go to the first page of the text instead of seeing the front cover every time they open the book. You can change the initial page by pressing the “Change” button following the “Initial page ID” field. It allows you to choose any of the pages in the book as the initial page when users open the book.

The “Edit Styles…” button allows you to define the formatting of the book’s text (headings, hyperlinks, etc.). You may want to do that if you have special formatting requirements or if you simply don’t like the default text formatting.

The “Access rights” panel allows authors to protect the contents of the book. This is relevant for commercial iBooks. Authors can decide if they “Allow printing and exporting” the book and if they “Allow editing,” i.e., if users can modify it. If you want to protect the book you must also set a password by clicking “Change password…” and select a password.

If the access rights allow, you can export the whole iBook to HTML by clicking the “Export to HTML” button. After selecting a destination directory and exporting the book, you can upload it to a website and allow visitors to view it in their browsers.

Editing an iBook Let’s add some content to our new iBook. When you click the “Edit Page” button on the ribbon, Aquarium opens the “Page text edit” window where you enter your text. There are several buttons and menus across the top of the window.
	The iBook editing window.

The most important one is the checkmark button (the leftmost button), which saves the page text, so use it often! As an additional incentive for saving often, this button also updates the book itself, so you can see it formatted in the “Page text” window.
Let’s start with something simple and see some of the text formatting options that are available. iBooks use simple Wiki-type formatting which is widely used on the web. Those who are familiar with Wikis may choose to enter formatting commands manually, but others will probably prefer to use the iBook formatting menus. If you want to format your text, first highlight it with the mouse and then select the formatting option from the B/U menu as shown here.

Formatting selected text.

When you click the save button, the formatted text is displayed in the “Page text” window. As you can see from the menu, you can choose three levels of headings (Heading, Subheading and Sub-subheading), besides bold and italic text. The image below shows the markup for the different types of formatting and what it looks like in the book itself.
	Editing window and final formatting.

If you want to change the default styles you can do so in the book options. Using the formatting commands, you can write a whole book, but we still need some chess content. The following text comes from Jeroen Noomen’s introduction to his Rybka Aquarium Opening Book:

Here we have some chess moves, but if we copy this text as it stands into our new iBook, it will just be normal text and you won’t be able to view the positions that Jeroen is discussing on the chessboard. Additionally, there is a missing diagram, which should be displayed after Black’s ninth move. We never want to show chess moves without being able to view them on the board as the “i” in “iBook” stands for “interactive” and there isn’t much interactivity involved in staring at the text of a normal book. We could of course add these moves manually to our iBook database and then pick them up from there, but let’s use some iBook magic instead.

We start by pasting the above text into the iBook. Then highlight the first nine moves with your mouse. Next select “line: style 0” from the “1.e4” menu. Save your book and voila, the moves come to life!
Now you can click any of the moves in the game and the corresponding position will be displayed on the board. You can even do this with moves in descriptive format and they will be automatically converted to algebraic notation.
The reason why we chose “line: style 0” here is that “style 0” corresponds to the mainline. “line: style 1” on the other hand is used for variations.

Normal text turned into playable moves.

We still don’t have the diagram that was in Jeroen’s introduction, following Black’s ninth move.
Normally, you would need the FEN string for a position in order to create a diagram, but again there is an easier way.
Place the cursor below the move sequence and select “Diagram for current position” from the rightmost menu button (“Other options”).
When you save the text, the diagram will be displayed, showing the correct position after the ninth move.

The diagram will show the current position.

	Let’s take a look at another timesaving feature. If you are converting normal text to iBook as we are doing here, it may take some time to search for and find the chess moves in the text. For quickly finding and highlighting moves, click the magnifying glass as shown in the image above. After that you can use the method we saw earlier to convert the text to clickable chess moves.
Find and highlight chess moves in the text.

With just a few mouse clicks we have converted normal text with chess moves into an iBook where you can click each move and see the position on the chessboard in Aquarium.
Here is a screenshot that shows what happens when we click the last move, 11.Kb2.
The whole variation from the iBook is displayed in the game window, ending with the move we clicked.
This means that you can now switch to the game window and quickly move backward and forward in the variation and even click the “Move to Sandbox” button if you want to analyze it with Rybka.

iBook moves displayed in game window.

	When you start writing iBooks, you may notice an extra button that appears on the right-hand side of the page editing toolbar.
A repeat button.

This button allows you to repeat the previous command, so it changes depending on what you were doing. You will find that this can come in quite handy; for instance, when you are converting existing chess text to iBook format.
Variations
We have now seen how to convert text with chess moves to iBook format. Next we’ll see how you can show variations in addition to the mainline, but let’s create a new page in the book for that. Click the “New Page” button on the ribbon and a dialog box for defining the page will be displayed.
I’m only changing one field here, the page title at the top. I call the page “Variations”. There are also fields that let you decide if the board and game window are displayed when the page is opened. I left them unchanged, so both windows will be displayed.
Note the drop-down list that shows “<No template>”. You can define page templates by selecting “<Edit templates>” from this drop-down list. A template contains boilerplate text, such as a top heading and links to next and previous pages at the bottom.

Creating a new iBook page.

The OnLoad instructions are frequently used by authors, especially if they are basing their books on games in the iBook database. In that case you could, for instance, automatically load game number five from the database into the game window when the page is opened. You would do that by entering the command load_game(5) into this field.

After changing the page title, click OK to create the new page. We’ll use the same mainline as before, but add a variation on the second move:

1.e4 e5 2.Nf3 Nf6 (2…Nc6 3.Bb5 a6 4.Bxc6 Ruy Lopez Exchange Variation) 3.Nxe5 d6 4.Nf3

After pasting this text into the newly created page, do the following:

Select the first two moves and convert them just like we did in the first example.
Select the moves in the variation and convert them, only this time you select “line: style 1” from the menu, indicating that it is a variation and not the mainline.
Select the rest of the moves, starting with 3.Nxe5 and convert them to mainline moves.

When you save the page, the results should look as follows:

The markup for the output shown in the image looks like this:
[line(1.e4 e5 2.Nf3 Nf6,0)] ([line(2…Nc6 3.Bb5 a6 4.Bxc6,1)] Ruy Lopez Exchange Variation) [line(3.Nxe5 d6 4.Nf3 Nxe4 5.Nc3 Nxc3 6.dxc3 Be7 7.Bf4 Nc6 8.Qd2 Be6 9.O-O-O Bxa2,0)]

You must be careful if you change anything within the line command (or any other iBook command for that matter). It can only handle chess moves, so no additional text is allowed.

Another option is to use the push_line and pop_line commands for nested variations. I will not describe these commands in this introduction, but they are necessary for deeply nested variations.

Automatic Conversion of Annotated Games
If you have a fully annotated game, you may want to convert it directly to iBook without any further editing. First you must add the game to the database. In our example the database is My-iBook.dsn. You can open the database and add the game in the same way as for any other database. After that it’s available for use in the iBook.
As before we’ll create a new page in the iBook for this example.

Load game #1 when the page is displayed.

This time we take advantage of the “OnLoad instructions” and load the game we just added to the database when the page is displayed with the load_game(1) command.
When you click OK the page will be created and the game will be displayed in the game window. Finally, right-click in the game window and select Convert to iBook -> Game as shown in the screenshot below.
That’s all! The game with all variations and annotations will be converted to iBook format.

Game with annotations converted to iBook.

Additional Features

Admittedly, this introduction to writing iBooks barely touches the surface of the tools that auhtors have at their disposal. The examples I presented are simple, but below I give a quick overview of other features that are helpful for writers:

Links. Authors can insert links in the text that take the reader to a different page in the book. External links (e.g., to web pages) can also be inserted.
Diagrams with graphic markers are supported.
Diagrams for a specific move or user defined position. Writers are not limited to diagrams for the “current” position. They can specify a move number or even a FEN string allowing user defined positions.
Images. Images can be displayed in the text.
Jump to a specific position when a page is loaded. We saw in the examples above how a game can be loaded when a page is opened. If you are going to start your discussion from a certain position in the game, you can jump automatically to that position.
Automatic loading of multiple games. You can load a game automatically when a page is displayed, but what if you want to discuss several games on the same page? Ideally, the correct game should be loaded and displayed whenever you encounter a new game on the page. That’s what Sections are for. Simply enclose each game in a section that loads the game. Whenever the user clicks a move within the section, that game will be loaded and displayed.
More flexibility in presenting game commentary. You can slice and dice the game any way you like and present it in the way that you think is most effective instead of being restricted to the traditional format for game commentary.
iBook export: desktop publishing, printing, blogs and self-contained HTML pages. You can export a whole book or the current page.

Selecting Moves and Variations
There are many issues that surface when writing interactive chess books. We have already seen that it’s easy to convert a whole game to iBook format and there are also simple methods available for converting the current move, the current variation or a whole variation complex.
The real challenge comes when you want a finer control over the display of moves and commentary, especially for games with many variations. When you are basing your writing on games in the iBook database, there are three ways to select a move sequence from a game. These methods even work for deeply nested variations.
The image below shows a game fraction and we are interested in commenting on one of its variations (highlighted in yellow), which actually contains moves from the mainline a first level variation and a second level variation.

Three methods of selecting a variation.

Here are the methods you can use to select such move sequences from the game:

You can add special annotations to moves in the game, which you can refer to in the iBook. These are called anchors. An anchor is a name enclosed in double slashes: “//”. In this example we use //Anchor// and the arrow points to the iBook command that would select the move sequence we are interested in.
You can point to a position in the game by giving the FEN string for the position as shown in the second example in the image. Both this method and using anchors give you access to all the moves leading up to this point in the game, starting from move one.
The third method is currently my favorite. Here you specify the first move of each variation leading to the variation of interest. The variation starting with 30…Qe8 is a second level variation. It is a sub-variation of the first level variation starting with 29…Qe1+. Therefore the path to our move sequence is “29…Qe1 30…Qe8” as shown in the third example. The difference from the two other methods is that this method returns all the moves to the end of the last variation (the variation starting with 30…Qe8 in this case).

After you have specified a move sequence using one of these methods, it becomes the current line in the iBook. This means that you can display selected moves from the variation simply using their move number. After commenting on the selected moves, you can display the next set of moves, etc.

Further information

I have briefly described some of the tools available for iBook writers. For detailed information you should refer to the “iBook Command Reference,” which will be released at the same time as the new Aquarium version. Sample iBooks showing how these tools are used in practice will also be available for download.

Dadi Jonsson.