Contents
MatPlus

Chess Problem Librarian ... and more!

Contents:

Notice

Overview

Screen Layouts and Menu Commands

Main Menu Commands

List Menu Commands

Mozaic Menu Commands

Solver System Box

Preview System Box

Index System Menu

Tutorial: How to...

Create a new book

Open an existing book

Create new problem

Fill the Author & Source field

Enter the position

Type the condition

Use the Keywords field

Use the Solver to fill the Solution field

Use and maintain the dictionaries

Store the problem

Use the Shelves

Maintain your library

Use exported images

Search tools: Simple find and Query

Find tool

Query

Query Writer Assistant

Query examples

Index tool

Solving tools:

MatPlus Solver

Popeye

Alybadix

Chloe

Gilgamesh

Problemiste

Technical information: Disk file format


Notice

The author of MatPlus Librarian does not approve the free use of the program. The experience shows that its usage is advantageous in many respects. The bottom line is that it can significantly improve composer's productivity and possibly the quality of his work. So unauthorized usage of this program would be at least unfair toward its author.

Author expects from user a symbolic compensation of 50 US$ or, by mutual agreement, an adequate exchange in e.g. literature, subscription to magazine or similar.

Also, author will be grateful for any bug-report or suggestion for improving the program.

Author: Milan Velimirovic

e-mail: mivel@sezampro.com

Web: http://www.matplus.org.yu


Overview

MatPlus Librarian (MPL) is result of a 8-year development of its predecessor MatPlus, a program written with not too ambitious initial purposes. However, as the time passed the program grew, and at this stage it has an impressive set of features, like:

- versatile methods of entering the chess positions (either in Forsyth or algebraic notation, typing directly onto the diagram, or mouse drag-and-drop method);

- easy and versatile tools for fast changing the position, thus saving the composers energy and time which would otherwise be wasted if the ordinary chess set is used: rotate, shift or flip position, insert or delete pieces by typing on the keyboard, or drag the pieces using the mouse; this is combined with a 64-step undo / redo feature;

- quick find tool;

- powerful query feature which provides quick extraction of problems satisfying defined criteria (e.g. theme, author name, first move, number of pieces, relative position between two or more pieces, etc.) from single book or from all books in the library;

- import problems from chess problem bases Problemiste (the Web page of which is notoriously growing); also import from another MatPlus book;

- export (selected or all) problems in Problemiste format; also export to another MatPlus book;

- export to Windows Bitmap or Paintbrush image format for later use with text processor, or to the Clipboard wherefrom it can be directly pasted at desired location in the text;

- export to HTML format for Web pages design;

- problem solving tools, either internal (MatPlus Solver), or possibility to export files for fast solving programs like Alybadix or Chloe;

- full support for Popeye solving program: user just has to issue the command and MPL will automatically call Popeye and, when job is done, present the result in separate window;

- it is also possible to export problems to Gilgamesh file format;

- maintaining chess problems archive in one or more books;

- assigning the keywords to entries (e.g. for themes);

- dynamic creation of indexes of themes, authors or sources;

- maintaining the dictionaries (of authors, sources, themes), helpful e.g for easier and faster data entry;

- viewing the single problem, the list of problem or the mozaic, with possibility to preview the solution and optionally diagram in separate window;

- print out in various formats with selectable layout and size of diagram and font;

and many other…

Program comes with two TrueType fonts: MatPlusTextRc which contains specific chess-oriented glyphs including chess pieces logos, and MatPlusDiagramRc, used for drawing the diagrams (program itself uses the latter only for printing, while screen diagrams are, for better visibility, drawn exclusively as bitmaps).

MPL runs on all Windows platforms starting from version 3.0. That means that it runs on any hardware Windows can run. However, for comfortable use it should be at least an over 100 MHz Pentium processor, and screen resolution 800x600 or higher.

MPL organizes its data in one or more plain text files ("books"). That means that they can be editted even in a Word processing program, though with disabled some "smart" options like automatic grammar and spelling errors correction. First open of the book is a little bit slower since MPL must build few additional files which will enable subsequent quick openning of the book and fast access to individual problems. These files are automatically re-generated whenever MPL senses an extrenal change of the book file. They can also be re-built on user request (either with disabled "quick open" option, or when compression of single book or reorganization of entire library is done).


Screen Layouts and Menu Commands

In any moment user can choose one of three possible screen layouts: normal (default) view, list mode and mozaic mode. Each of these has a specific set of commands which can be executed from respective menu bar, most of them by keyboard accelerator, and those which are assumed to be most frequently needed also from a toolbar icons. Optionally, user can at any time open (and close) three additional windows: solver, preview and index. They also have their set of commands accessible from a window System box (located on the left hand side of the caption). Regardless of the current mode, each of three independent windows -- Solver, Preview and Index -- can be opened and closed at any time., each with its own set of commands accessible through the respective System Menu (or System Box).

Menu commands and eventual keyboard accelerators are briefly described in following sections:

Main Menu Commands

List Menu Commands

Mozaic Menu Commands

Solver System Box

Preview System Box

Index System Menu

Any window, either fields in main window or additional windows, can be activated (or given input focus) by click on left mouse button.  However, user can switch from one window to another with Ctrl+TAB key, which passes the focus to the next window in chain: main window - solver window (if visible) - preview window (if visible) - index window (if visible). Within the main window the order of windows is: author & source field - diagram - condition field - keywords field - solution field. If the solution field has input focus, Ctrl+TAB will pass it to the first visible additional window, or, if all of these are hidden, to author & source field.

Additional window can also be activated and/or closed by a keyboard command: Ctrl+P for preview, Ctrl+I/J/K for index or #9 (numeric key 9) for solver window. If respective window is inactive it is activated, otherwise, except in the case of index window, it is closed.


Screen layout - normal view


Screen layout - list of problems


Screen layout - mozaic


Main Menu
Main Menu commands

See: Screen layout - normal view

File | Open Book (Ctrl+O) - Select this to open an existing or create a new book.

File | Compress Book - Performs the compression of current book, discarding the space occupied by deleted, renamed or changed problems.

File | Book Title - Allows user to assign or edit the title of current book. This title is displayed in the program's main window caption.

File | Manage Shelves - Allows grouping the  books for easier orientation through the Library.

File | Autosave - Alternatively enables or disables the "autosave" feature. If enabled, changes to current problem will be done automatically before user selects another problem or book.

File | Browse - Alternatively turns the Browse mode on or off. If this mode is in effect all changes to current problem will be discarded when user selects another problem or book.

File | Import or Convert from >> Old MatPlus PBA file - Earlier version of program kept each problem in separate file, and they were grouped in subdirectories. This procedure converts all PBA files from selected directory (folder) to a single MatPlus Book.

File | Import or Convert from >> Problemiste File - Converts the Matthieu Leschemelle's chess problem base to MatPlus Book format.

File | Import or Convert from >> Extract from VP text - Obsolete.

File | Export >> Old MatPlus PBA file - Used for backward compatibility with old version of MatPlus.

File | Export >> Problemiste File - Exports the entire book to Matthieu Leschemelle's chess problem base. Useful e.g for contribution to Matthieu's Web page, if you want to share it with others...

File | Export >> Diagram to Bitmap File (Ctrl+B) - Exports the diagram image to Windows Bitmap (BMP) disk file.

File | Export >> Diagram to PCX File - Exports the diagram image to Paintbrush (PCX) disk file.

File | Export >> Diagram to Clipboard (Ctrl+Shift+Insert) - Exports the diagram image to Windows Clipboard, wherefrom it can be inserted directly e.g to opened Word document.

File | Export >> Dictionary to Text - Generates 8-bit ASCII text file in application directory for each of three dictionaries: of authors (DICT_A.TXT), sources (DICT_S.TXT) and themes (DICT_T.TXT).

File | Make Index - Enables (re-)generation of authors, sources or theme index.

File | Page Setup - Opens the Page Setup dialog .

File | Print - Prints current problem.

File | Multiple instances >> Launch another MatPlus (Alt+F1) - Starts another instance of program.

File | Multiple instances >> Switch to MatPlus (Ctrl+F1) - Activates another instance of program.

File | Multiple instances >> Previous instance (Ctrl+1) - Activates previously started instance.

File | Multiple instances >> Next instance (Ctrl+2) - Activates subsequently started instance.

File | House cleaning - Allows change of name or deletion of MatPlus Book file (and all respective components)

File | Reorganize Library - Performs the compression of all libraries, update of all links and generating of indexes. Also removes all temporary files.

File | Quit (Alt+F4) - Ends the current program (instance).

Problem | New (Ctrl+N) - Opens the blank unnamed problem. When entry is completed, it must be given a unique name under which it will be stored to current book.

Problem | Store (Ctrl+S) - Stores the problem back to book. For new problem user will be prompted for entry name.

Problem | Store As (Ctrl+A) - Stores the problem to book under another name. Old version of problem remains unchanged.

Problem | Prior (Alt+PgUp, Gray - ) - Selects the problem the name which alphabetically precedes the current problem name.

Problem | Next (Alt+PgDn, Gray +) - Selects the problem the name which alphabetically follows the current problem name.

Problem | Top (Alt+Home) - Selects the first problem according the alphabetical order of names.

Problem | Bottom (Alt+End) - Selects the last problem according the alphabetical order of names.

Problem | Locate item # (F5) - Opens directly problem from given position in alphabetical order. If Keywords field has input focus and caret is inside the "See also" ("finger", "link") entry, the referred problem is opened. If reference is to problem from another book, the another instance of MatPlus is started and referred problem is opened.

Problem | Next index item (F7) - Enabled only when one of index windows is visible. Opens the next problem from current index entry.

Problem | Find (F3) - Allows user to specify one to four search criteria. Next problem in order which fulfills at list one of these criteria (logical "OR") is opened. In current version only the data from problem list rows and optionally from the Solution field can be scanned.

Problem | Find next (F4) - Next problem in order which fulfills at list one of current search criteria (logical "OR") is opened.

View | List (Ctrl+L) - Displays the list of problems. If Preview window is visible, the diagram and solution of current problem are shown there.

View | Mozaic (Ctrl+M) - Selects the mozaic view. If Preview window is visible, the solution of current problem are is there.

View | Preview Solution (Ctrl+P) - Displays the preview and, if the list view is in effect, the diagram of current problem solution.

View | Character table (F9) - Alternatively shows or hides the character table with glyphs which are not easily accessible on keyboard. Click on the button will insert the respective character to caret position in currently active edit window (author, condition, keywords or solution field) or piece to the board if diagram window has the input focus. The piece can also picked from the character table, dragged over the diagram and dropped to pointed square.

View | Index of >> Authors (Ctrl+I) - Shows the index of authors in index window. If index file does not exist, it will be created.

View | Index of >> Sources (Ctrl+J) - Shows the index of sources in index window. If index file does not exist, it will be created.

View | Index of >> Themes (Ctrl+I) - Shows the index of themes in index window. If index file does not exist, it will be created.

View | Font Size >> n - Selects the height of font used in author, condition, keywords and solution field.

View | Font Size >> Increase (Ctrl+Gray +) - Increases the height of font used in author, condition, keywords and solution field.

View | Font Size >> Decrease (Ctrl+Gray -) - Reduces the height of font used in author, condition, keywords and solution field.

View | Diagram Size >> NxN - Selects the size of diagram.

View | Hatched black squares - If enabled black squares are painted as slanted parallel lines. Otherwise they are filled with gray brush.

View | File / rank borders - If enabled files (lines) and ranks (rows) are separated by black hairline.

View | Toolbar - Alternatively shows or hides the toolbar icons.

View | Yellow messages - Alternatively enables or disables short messages when mouse pointer is over the respective toolbar icon.

View | Hide solution! - Hides the solution field, in case that user wishes to solve the problem by himself.

View | Arrange desktop - Arranges all windows opened in current instance in non-overlapping layout: main window in top-left, solver's window in top-right, preview window in bottom-left and index window in bottom-right part of the screen.

Board | Undo - Undoes in reverse order the changes made on diagram (up to 64 steps).

Board | Undo - Redoes undone diagram changes (up to 64 steps).

Board | Rotate >> 90 degrees (Ctrl+9) - Rotates the board 90 degrees counterclockwise.

Board | Rotate >> 180 degrees (Ctrl+8) - Rotates the board 180 degrees counterclockwise.

Board | Rotate >> 270 degrees (Ctrl+7) - Rotates the board 270 degrees counterclockwise.

Board | Flip >> Vertical (Ctrl+V) - Flips the position around the vertical axis between 4th and 5th row.

Board | Flip >> Horizontal (Ctrl+H) - Flips the position around the horizontal axis between d- and e- file.

Board | Scroll >> Up (Alt+Up arrow) - Shifts the position one row up.

Board | Scroll >> Down (Alt+Down arrow) - Shifts the position one row down.

Board | Scroll >> Left (Alt+Left arrow) - Shifts the position one line to the left.

Board | Scroll >> Right (Alt+Right arrow) - Shifts the position one line to the right.

Board | Clear (Ctrl+Delete) - Removes all pieces from the board.

Edit | Cut (Shift+Delete) - Deletes selected text and copies it to the Clipboard.

Edit | Copy (Ctrl+Insert) - Copies selected text  to the Clipboard.

Edit | Paste (Shift+Insert) - Inserts the Clipboard text (if any) to the caret position.

Edit | Uppercase (Alt+4) - Converts all alphabetic characters in selected text to capital letters.

Edit | Lowercase (Alt+5) - Converts all alphabetic characters in selected text to lowercase letters.

Edit | Capitalize (Alt+5) - Capitalizes (first character uppercase, all other lowercase) all words in selected text.

Edit | Forsyth entry (F2) - Opens the dialog for entry in Forsyth notation.

Edit | Algebraic entry (Alt+F2) - Opens the dialog for entry in algebraic notation.

Edit | Notation - Opens the dialog for choice of current notation.

Edit | Convert to MatPlus (F10) - Converts the letter symbols to logos in portion of text between double left ([[) and double right (]]) bracket.

Edit | Convert from MatPlus (Alt+F10) - Converts the logos to letter symbols in portion of text between double left ([[) and double right (]]) bracket.

Edit | Convert from Chloe - Converts the double-bracketed solution copied & pasted from Chloe window to shortened notation.

Edit | YUSCII to MatPlus (Ctrl+Shift+Y) - Obsolete.

Insert | From Dictionary (F8) - Replaces the current (part of the) word with selected dictionary entry.

Insert | To Dictionary (Alt+F8) - Adds data from current problem (author name, source and keywords) to respective dictionary.

Insert | White piece >> <piece> (Esc .. <symbol>) - Inserts the white piece logo to current caret position. Keyboard command consists of two separate hits: first on Escape key and then on respective piece symbol (depending on currently selected notation).

Insert | Black piece >> <piece> (Esc .. Esc .. <symbol>) - Inserts the white piece logo to current caret position. Keyboard command consists of three separate hits: first two are the Escape key and then on respective piece symbol (depending on currently selected notation).

Insert | Character >> <char> (Esc .. [Esc ..] <symbol>)

Insert | Accent >> <char> (Esc .. [Esc ..] <symbol>) - Inserts the character or accent to current caret position. Keyboard command consists of two or three separate hits: first on Escape key, then another Escape if uppercase is needed, and then on respective key as shown in the table.

Insert | Position >> Algebraic (Ctrl+Shift+F) - Inserts the position in algebraic notation at caret position.

Insert | Position >> Forsyth (Ctrl+Shift+F) - Inserts the position in Forsyth notation at caret position.

Insert | VP Attribute - Obsolete.

Solving | MatPlus (#5) - Invokes the MatPlus Solver for key move only.

Solving | MatPlus Analyzer (#6) - Invokes the MatPlus Solver for complete solution.

Solving | Copy Solution (#4) - Copies the lines from MatPlus Solver window to caret position. See section MatPlus Solver .

Solving | Options >> xxx - Sets part of solving options. See Solver Menu

Solving | Popeye | Solve (Ctrl+Z) - Calls the Popeye program to solve current problem.

Solving | Popeye | Executable file - CAllows user to determine the location of Popeye executable file. By default, MPL expects it in its (MPL) directory named PY.EXE.

Solving | Popeye | Generate Popeye Record - Generates provisional Popeye script based on diagram position and condition of current problem.

Solving | Popeye | Paste Popeye Diagram - This function is not likely to be needed, but anyway it allows you to mark and copy the diagram from Popeye output file to the Clipboard, and then to paste it to the current ptoblem diagram.

Solving | Alybadix (Alt+F6) - Generates file in format which can be read and solved by Alybadix.

Solving | Chloe (Shift+F6) - Generates file in format which can be read and solved by Chloe.

Solving | Gilgamesh (Ctrl+F6) - Generates file in format which can be read and solved by Gilgamesh.

Help | Contents (F1) - Displays this document.

Help | User registration - Allows user to enter or change his registration key.

Help | About - Information about the program.


List Menu
List Menu commands

See: Screen layout - list of problems

File | Open Book (Ctrl+O) - Select this to open an existing or create a new book.

File | Compress Book - Performs the compression of current book, discarding the space occupied by deleted, renamed or changed problems.

File | Book Title - Allows user to assign or edit the title of current book. This title is displayed in the program's main window caption.

File | Manage Shelves - Allows grouping the  books for easier orientation through the Library.

File | Make Index - Enables (re-)generation of authors, sources or theme index.

File | Renumber All - Renumbers selected or all problems in the book after user specifies the starting number and increment.

File | Page Setup - Opens the Page Setup dialog.

File | Print - Prints current problem.

File | Multiple instances >> Launch another MatPlus (Alt+F1) - Starts another instance of program.

File | Multiple instances >> Switch to MatPlus (Ctrl+F1) - Activates another instance of program.

File | Multiple instances >> Previous instance (Ctrl+1) - Activates previously started instance.

File | Multiple instances >> Next instance (Ctrl+2) - Activates subsequently started instance.

File | House cleaning - Allows change of name or deletion of MatPlus Book file (and all respective components)

File | Reorganize Library - Performs the compression of all libraries, update of all links and generating of indexes. Also removes all temporary files.

File | Back (Escape) - Hides the list window and shows the normal layout.

File | Quit (Alt+F4) - Ends the current program (instance).

Problem | Find (F3) - Allows user to specify one to four search criteria. Next row in the list which fulfills at list one of these criteria (logical "OR") will be selected. In current version only the data from problem list rows and optionally from the Solution field can be scanned.

Problem | Find next (F4) - Positions to next row in list which fulfills at list one of current search criteria (logical "OR").

Problem | Find next (Ctrl+F3) - Positions to the last row in list which fulfills at list one of current search criteria (logical "OR").

Problem | Goto item # (F5) - Positions to specified row in the list.

Problem | Next index item (F7) - Enabled only when one of index windows is visible. Positions to the next row which corresponds to current index entry.

Problem | Rename (Ctrl+R) - Renames current problem.

Problem | Delete (Delete) - Deletes current problem.

Problem | All to MatPlus - Converts all solutions to MatPlus style (e.g logos instead of letter symbols for pieces)

View | Default (Ctrl+D) - Selects the normal (default) view.

View | Mozaic (Ctrl+M) - Selects the mozaic view. If Preview window is visible, the solution of current problem is shown there.

View | Diagram & Solution (Ctrl+P) - Displays the solution and the diagram of current problem.

View | Index of >> Authors (Ctrl+I) - Shows the index of authors in index window. If index file does not exist, it will be created.

View | Index of >> Sources (Ctrl+J) - Shows the index of sources in index window. If index file does not exist, it will be created.

View | Index of >> Themes (Ctrl+I) - Shows the index of themes in index window. If index file does not exist, it will be created.

View | Font Size >> n - Selects the height of font used in list of problems.

View | Font Size >> Increase (Ctrl+Gray +) - Increases the height of font used in list of problems.

View | Font Size >> Decrease (Ctrl+Gray -) - Reduces the height of font used in list of problems.

View | Diagram Size >> NxN - Selects the size of diagram for preview window..

View | Toolbar - Alternatively shows or hides the toolbar icons.

View | Yellow messages - Alternatively enables or disables short messages when mouse pointer is over the respective toolbar icon.

View | Arrange desktop - Arranges all windows opened in current instance in non-overlapping layout: main window in top-left, solver's window in top-right, preview window in bottom-left and index window in bottom-right part of the screen.

Select | Select All (Ctrl+E) - Selects all rows in the list.

Select | Unselect All (Ctrl+U) - De-selects all rows in the list.

Select | Reverse All (Ctrl+X) - Inverts the selection state of all rows in the list.

Select | Compare with book - Selects all problems with matching (or mirrored) position contained in another book.

Select | Miniatures - Selects all miniature problems (max 7 pieces) in the list.

Select | Merediths - Selects all Meredith problems (max 12 pieces) in the list.

Select | List Type - Defines the list style.

Select | List Type | Extended selection - Multiple rows can be selected in usual Windows Control or Shift click operations. The arrow keys deselect all rows and select the caret position row.

Select | List Type | Multiple selection - Each row is individually (de)selected by mouse click or press on the SPACE key. The selection remains unchanged if caret position is changed by arrow keys.

Export | MatPlus book - Exports selected problems another MatPlus book.

Export | Problemiste File - Exports all or selected problems to Matthieu Leschemelle's chess problem base. Useful e.g for contribution to Matthieu's Web page, if you want to share it with others...

Export | Plain Text - Generates plain 8-bit ASCII text file.

Export | Ventura TXT - Obsolete.

Export | HTML - Generates HTML text. Useful for Web designers. A set of GIF images is necessary for browsing with e.g Internet Explorer or Netscape Navigator.

Export | Image >> Bitmap (Ctrl+B) - Generates image files for selected or all problems in Windows Bitmap format (BMP). Files are stored in subdirectory <book_name>.img.

Export | Image >> Paintbrush - Generates image files for selected or all problems in Paintbrush format (PCX). Files are stored in subdirectory <book_name>.img.

Export | Alybadix - Generates files which can be read and solved by Alybadix solving program.

Export | Chloe - Generates files which can be read and solved by Chloe solving program.

Export | Gilgamesh - Generates files which can be read by Gilgamesh.

Export | Old MatPlus PBA files - Obsolete.

Export | Hardcopy List - Obsolete. Generates a plain text file with list of problems suitable for use by Ventura Publisher.

Export | 8-bit Hardcopy - Generates a plain 8-bit ASCII text file with list of problems.

Export | To Dictionaries - Updates all dictionaries (of authors, sources and themes) with data from current book.

Solve | MatPlus (#5) - Invokes the MatPlus Solver for key move only of current problem.

Solve| MatPlus Analyzer (#6) - Invokes the MatPlus Solver for complete solution of current problem.

Solve | Options >> xxx - Sets part of solving options. See Solver Menu

Solving | Popeye | Solve (Ctrl+Z) - Calls the Popeye program to solve current problem.

Solving | Popeye | Executable file - CAllows user to determine the location of Popeye executable file. By default, MPL expects it in its (MPL) directory named PY.EXE.

Help | Contents (F1) - Displays this document.

Help | User registration - Allows user to enter or change his registration key.

Help | About - Information about the program.


Mozaic Menu
Mozaic Menu commands

See: Screen layout - mozaic

File | Open Book (Ctrl+O) - Select this to open an existing or create a new book.

File | Compress Book - Performs the compression of current book, discarding the space occupied by deleted, renamed or changed problems.

File | Book Title - Allows user to assign or edit the title of current book. This title is displayed in the program's main window caption.

File | Manage Shelves - Allows grouping the  books for easier orientation through the Library.

File | Multiple instances >> Launch another MatPlus (Alt+F1) - Starts another instance of program.

File | Multiple instances >> Switch to MatPlus (Ctrl+F1) - Activates another instance of program.

File | Multiple instances >> Previous instance (Ctrl+1) - Activates previously started instance.

File | Multiple instances >> Next instance (Ctrl+2) - Activates subsequently started instance.

File | House cleaning - Allows change of name or deletion of MatPlus Book file (and all respective components)

File | Reorganize Library - Performs the compression of all libraries, update of all links and generating of indexes. Also removes all temporary files.

File | Back (Escape) - Hides the list window and shows the normal layout.

File | Quit (Alt+F4) - Ends the current program (instance).

View | Default (Ctrl+D) - Selects the normal (default) view.

View | List (Ctrl+L) - Shows the list of problems.

View | Solution (Ctrl+P) - Displays the solution of current problem.

View | Index of >> Authors (Ctrl+I) - Shows the index of authors in index window. If index file does not exist, it will be created.

View | Index of >> Sources (Ctrl+J) - Shows the index of sources in index window. If index file does not exist, it will be created.

View | Index of >> Themes (Ctrl+I) - Shows the index of themes in index window. If index file does not exist, it will be created.

View | Font Size >> n - Selects the height of font used in mozaic.

View | Font Size >> Increase (Ctrl+Gray +) - Increases the height of font used in mozaic.

View | Font Size >> Decrease (Ctrl+Gray -) - Reduces the height of font used in mozaic.

View | Diagram Size >> NxN - Selects the size of diagrams in mozaic.

View | Toolbar - Alternatively shows or hides the toolbar icons.

View | Yellow messages - Alternatively enables or disables short messages when mouse pointer is over the respective toolbar icon.

View | Arrange desktop - Arranges all windows opened in current instance in non-overlapping layout: main window in top-left, solver's window in top-right, preview window in bottom-left and index window in bottom-right part of the screen.

Solving | MatPlus (#5) - Invokes the MatPlus Solver for key move only of current problem.

Solving | MatPlus Analyzer (#6) - Invokes the MatPlus Solver for complete solution of current problem.

Solving | Options >> xxx - Sets part of solving options. See Solver Menu

Solving | Popeye | Solve (Ctrl+Z) - Calls the Popeye program to solve current problem.

Solving | Popeye | Executable file - CAllows user to determine the location of Popeye executable file. By default, MPL expects it in its (MPL) directory named PY.EXE.

Help | Contents (F1) - Displays this document.

Help | User registration - Allows user to enter or change his registration key.

Help | About - Information about the program.


Solver Menu

This menu i pulled down by hitting the System Box in upper left corner of Solver window.

Copy (#4) - Copies all lines which do not start with minus sign to the solution field.

Join (#8) - Joins selected lines.

Assume Mutate (#0) - For twomovers only: compares set and actual variations and generates the MatPlus mutate classification code.

Set play (#1) - If checked, tests the set play in twomovers or helpmates.

Tries (#2) - If checked, looks also for tries.

Smart test - If checked, test the set play and tries if mentioned in condition field.

Non-defences - If checked, shows all black moves, not only defences against the threat.

Black King moves - If checked, shows all moves of BK, even if they are not defences.

Checks to White Kink - If checked, all checks to WK are shown, even if they are not defences.

Ugly refutations - If checked, all kinds of tries are shown, including those with bad refutations (e.g checks or capture of white piece which took the first move)

Checking tries - If checked, white checking tries are shown.

Refutations-defences (#7) - When checked, first refutation is shown for all white moves (unless it is a key move or cook)

Sound - If checked, a "beep" is played when solving is done.

Font (Ctrl + #7) - Allows selection of the font used in solver's window.

Abort! (#9) - Terminates current solving process.


Preview Menu

This menu i pulled down by hitting the System Box in upper left corner of Preview window.

Reduce font - Reduces the size of font used in preview window. Alternate command is a double click on LEFT mouse button.

Enlarge font - Enlarges the size of font used in preview window. Alternate command is a double click on RIGHT mouse button.

Formatted - If checked, semicolon forces the new line, and comma forces the indented new line.

Keywords - If checked, the content of keywords field is shown here.

NxN diagram - Selects corresponding diagram size for preview window.


Index Menu

This menu i pulled down by hitting the System Box in upper left corner of Index window.

n points - Selects respective font size.

Reduce font - Reduces the size of font. Alternate command is a double click on LEFT mouse button.

Enlarge font - Enlarges the size of font. Alternate command is a double click on RIGHT mouse button.


Escape sequences


GIF images for HTML


Tutorial: How to...

Create a new book

Open an existing book

Create new problem

Fill the Author & Source field

Enter the position

Type the condition

Use the Keywords field

Use the Solver to fill the Solution field

Use and maintain the dictionaries

Store the problem

Maintain your library


Creating a new book

To create an empty book:

1) 	Select from menu File | Open or Create Book, or press the Ctrl+O keyboard combination.

2)	In Open Book dialog fill the Filename field with a new file name (use only the valid MS-DOS filename characters!) and press OK.

3)	Confirm the creation of new book.

4)	Select from menu File | Book Title to enter the title of the book. This is not necessary to do immediately -- the title can be given or changed at any time.

A new book can also be crated on import from other sources (e.g Problemiste base, old MatPlus files, etc.) or when exporting problems from an existing MatPlus book to another book.


Opening an existing book

To open an existing book:

1) 	Select from menu File | Open or Create Book, or press the Ctrl+O keyboard combination.

2)	In Open Book dialog select the desired book from the list and press OK. Alternatively, you can fill the book filename from keyboard.

MatPlus Librarian will always try a quick open, using the special index file created on previous reading of the book. However, you can force the re-creation of this special file by removing the check mark from a Quick open checkbox. Keep in mind that on slower machines this re-creation for "thick" books may take a considerable time.


Creating a new problem

1)	Select from menu Problem | New or press the Ctrl+N keyboard combination.

2)	You can now either fill one or more fields with respective data, or leave empty for the moment. However, you what you must do is

3)	Store the problem selecting from menu Problem | Store or press the Ctrl+S keyboard combination (in this moment same as Problem | Store As / Ctrl+A).

4)	The problem must be given a name (1 to 8 alphanumerics). When prompted for a name of new problem, type it in respective field and press OK. The name must be unique in the scope of current book. If problem with same name already exists, you will be warned and asked to give another name.

You can recall the problem at any time either to browse it or to make changes to it.

Alternatively, a new problem entry can be created from an opened existing problem, with menu command Problem | Store As / Ctrl+A/


Filling the Author & Source field

It is recommended to enter the author's name in first, and the source in second line of this field, followed by eventual additional rows (e.g dedication, "after", FIDE Album notification etc.). In case of joint problems, do not start new line for each author, but rather insert an ampersand between the names. If you don't follow these recommendations then the indexes of authors and sources will not be quite correct

Another reason for this is the fact that this field is associated with two dictionaries. Index of authors is filled with data from first, and index of sources with data from second line. Also, during the entry, which of two dictionaries is open for typing assistance depends on the row in which the caret is.

The MatPlus Librarian entry is designed to be as user friendly as possible and for that reason this field will accept various data in a single stream which is for user much more easier than filling a dialog box with separate fields for e.g author(s), source, tourney reward, date of publication, eventual dedication, etc. However, some tools which must parse the stream expects user to follow few guidelines.

- Enter the author's name in first logical line of the field. Logical line is terminated by user press on Return key, and may wrap to more screen lines. In case of joint problems insert the ampersand ("&") between each author's name.

- Enter the source, date of publication and eventual tourney distinction in the second logical line in following order: distinction - source - date. For tourney rewards use following shortcuts:
Prize: Pr / pr / n
Honorable mention: HM / hm / pp
Commendaiton: Com / com / cm / p
Place: Pl / pl
Special: Spec / sp

- Enter the eventual additional data from third logical line (dedication, In memoriam, after, etc.)


Entering the position

There are several ways to enter or alter the diagram position thus offering the user opportunity to choose the most suitable one for given circumstances.

Notation

The fastest way to enter the complete position (e.g from book or magazine) is either Forsyth or algebraic notation. Select menu command Edit | Forsyth entry (or F2 accelerator) for former, and Edit | Algebraic entry (or Alt+F2) for latter.

For each there are some shortenings compared to standard notation used in the literature. For example, consider the following position:

The Forsyth notation, if English notation is used, normally looks like:

3b4.8.3p2K1.3pP1RS.4kB2.1r4R1.6b1.3Q4

However, MatPlus offers few methods to simplify the entry, one of which is to avoid use of shift key -- the symbol in lowercase preceded by space represents white piece. The same position may be entered as:

3b..3p2 k.3p p1 r s.4k b.1r4 r.6b.3 q

Note that here are omitted digits before the row delimiter (which is here a dot, but may as well be used a dash "-" or comma ",").

During the entry the diagram is updated after each key-press, and next square to be filled is marked by a blue rectangle around it. You can use a semicolon ";" to move to the square below the last piece entered (or two semicolons if to move two rows down, etc.). When you get experienced, you can type position without any row separator, for instance:

3b;;p2K4pP1RS4kB3r4R;b4Q

In some cases it is easier to calculate the empty squares between two pieces, even if they are more than one row distant. In our position, bPd6 is exactly 2 rows below the bBd8, and we know without counting that there are exactly 15 empty squares between them, so:

3b15p2K4pP1RS4kB3r4R7b4Q

is also possible.

If you prefer to use the algebraic notation, then white and black pieces are entered in separate fields:

Kg6 Qd1 Rg3 g5 Bf4 Sh5 Pe5

Ke4 Rb3 Bd8 g2 Pd5 d6

Use the TAB key to move between two fields in Algebraic entry dialog box.

It is not necessary to use capital letters for pieces, nor to insert space separators. Further, if two or more pieces of the same kind and color are placed on the same file, e.g Pa3, Pa4 and Pa7, then file-letter can be typed only once: pa347. In our position there are two black pawns on d-file and two white rooks on g-file, so the position can be entered in this way:

kg6qd1rg35bf4sh5pe5

ke4rb3bd8g2pd56

Typing from keyboard to diagram

When diagram window has the input focus, there is always a current square the contents of which can be altered by hitting the keyboard key. It is marked with blue rectangle around it. The rectangle is hidden after few seconds of inactivity. To show it press Return key. Use the keyboard arrows to change the current square. Type the symbol for the piece (in current notation) to put it on current square - capital letter for white and lowercase for black piece. Press Space bar to invert the color of the piece. Press Delete key to empty the square.

The entire position can be shifted, rotated or flipped with following keyboard commands:

Ctrl+Shift+Arrow shifts the position by one square in respective direction

Ctrl+9 rotates the position 90 degrees counterclockwise

Ctrl+8 rotates the position 180 degrees counterclockwise

Ctrl+7 rotates the position 270 degrees counterclockwise

Ctrl+V flips the position around vertical axis

Ctrl+H flips the position around horizontal axis

You can go through changes backward (undo) or forward (redo) up to 64 steps.

Diagram entry/edit using the mouse

To add a piece on the board you can drag it from character table (press F9 key or click on toolbar icon to show or hide it) and drop to desired diagram square. The piece can be moved from one square to another also by similar drag-and-drop method: point to the piece, press the left mouse button, move the pointer to destination square and release the button. To remove the piece just move the pointer outside the board and release the button.

While a current square box is visible you can:

- point to another square and click the right mouse button to insert the piece of the same type as the piece inside the box.

- point to another square and press Shift or Control key and click the left mouse button to move the piece inside the box to new location.

- point to another square and press Shift or Control key and click the right mouse button to exchange the pieces on current and pointed squares. If one of the squares is empty then only the piece from other square is moved.

To shift, rotate or flip the position, undo and/or redo changes click on respective toolbar icon.


Filling the Condition field

It is recommended to use the mate symbol "#" rather than word "mate in", and respective one-letter prefixes for helpmate, selfmate, reflexmate etc. In case of twins, insert the TAB character after the condition for first, and RETURN and TAB before each further twin.

It is not necessary to type the sum of pieces since it is automatically calculated and shown in the status line.

The MatPlus Solver and export modules (for Chloe, Alybadix, Gilgamesh) assumes that above rules are met.

Twins description

MatPlus Solver expects following syntax rules to be obeyed:

- twins should be enumerated with lowercase letters followed by right parenthesis, in ascending alphabetical order, starting with "b)" (except in case of zeroposition);

- for successive twins add a plus sign in front of the letter, e.g "+c) ...";

- for zeroposition, write at least first four letters ("zero") after the condition, and then start with position "a)";

- twins with two or more changes in the position are not accepted by Solver;

- use the pieces logos rather than ordinary notation to indicate the piece;

Following twinning methods are recognized for time being:

Move a piece from one square to another. For instance, removal of black pawn from d5 to e5:  (typing sequence: Esc Esc p d 5 esc m e 5), but not: , since solver will notice the difference in color). The piece symbol can be omitted:  and solver will accept it without checking, but this is not recommended.

Exchange the location two pieces. For instance, if WQd2 and WSe2 are swapping places:  (typing sequence: Esc q d 2  Esc x Esc s e 2), or shorter [image].

Replace one piece with another or addition of new piece. Simply indicate the new piece and it will be placed on the board on given square regardless it was empty or occupied by another piece. For your convenience and for practical reasons, you can insert a plus sign in front of the piece logo if the piece is added to the board. Anyway, either you write [image] or [image] the result will be the same.

Remove the piece from the board. Insert a minus ("-") or en-dash ("--") character in front of the piece:  (typing sequence: - Esc p d7) or [image] (typing sequence: Esc - Esc p d7). Optionally, you can omit the piece logo: .

Shift the position in any direction. Take one square in diagram (or current) position and indicate which square it will become in twin position. For example, "b) b1=a1" shifts the position left by one square (what was b1 now is a1!), or "b) a1=a3" shifts the position up by two squares. The position can also be shifted diagonally, e.g "b) d6=c3" for three ranks down and one file left.

Rotate the position. Just write the amount in degrees of a counterclockwise rotation: "b) 90", "b) 180" or "b) 270", but do not expect the solver to figure out that e.g "b) 450" is the same as "b) 90"!


Use the Keywords
Use the Keywords field

This field has two purposes. One is to contain the list of themes shown in given problem, and another to contain the links to related problems in current or some other book. It can contain one or more entries (separated by semicolon), and each entry can have one or more sub-entries (separated by comma). The entry starting with finger pointer (which is in MatPlus font a different glyph for circumflex "^", ASCII 94, hex. 5E) is a link. Others are considered as theme descriptors

Theme descriptors

The syntax for this entry is:

  main-entry [, sub-entry-level-1 [, sub-entry-level-2 [ ... ] ] ] ;

In index of themes every sublevel is given in new (more) indented line, and will be associated in problem number (according to ascending sort order of problem names) in the book. The user can choose whether he wants the problem number associated with each, only main and last, or only with the last level of given entry.

For instance, consider the keyword fields from a book containing 5 problems:

Problem 1: grimshaw, black; miniature

Problem 2: grimshaw, black; mutate

Problem 3: mutate; miniature

Problem 4: grimshaw, black, double

Problem 5: grimshaw, white

Problem 6: grimshaw, white, double

Depending on user requirement, index should be in one of following forms:


Use the Solver to fill the Solution field

The current version of solving module is just a stage in the development of the algorithm which would be a sufficiently powerful to deal with e.g longer problems, helpmates and fairy conditions. However, at this stage it can be quite useful, especially for composers and collectors of direct twomovers.

This chapter describes only one of the solving module features: the assistance in writing the solution.

What will be listed in the Solver window depends on the options set in the Solver Menu

There are to types of lines in the list: those starting with and those starting without a minus sign. Only the latter (and all of them) will copied to the Solution field when such command is issued, and then if necessary edited in usual way. To copy the content of the Solver window select "Copy" from Solver's system menu, or just press "4" on numeric keypad (provided that NumLock is turned on)

However, you can do some rearranging easier directly in the Solver window: delete one or more lines or phase, move the line or phase or join two adjacent lines (which is useful only for twomovers).

To delete the line(s) just select it(them) and press Delete key.

Example:

To delete the phase select the heading line (e.g "- Try:) and press Backspace. All lines until the next one which starts with minus sign will be deleted.

Example:

To move a single line point to it, press right mouse button, drag it to the desired destination and release the button. Line will be moved in front of the destination line. To move the line to the end of the list drag it below the last line and release the button.

Example:

To move a phase point to the heading line (e.g "- Try:) and press the right mouse button. You will see that all lines until the next phase are highlighted. Now move the pointer to the destination heading line and release the button. All highlighted lines will be moved in front of the destination heading line.

Example:

To join two or more adjacent lines select them and select "Join" from Solver's system menu, or just press "8" on numeric keypad (provided that NumLock is turned on). Note: This procedure works correctly only with two-movers!!

Example:


Use the dictionaries
Use and maintain the dictionaries

MatPlus Librarian provides three different dictionaries which can make the data entry easier: of authors, of sources and of themes. First two are associated with the Author & Source field, the third one with the Keywords field. When F8 key is pressed (Insert | From Dictionary menu command) respective dictionary is opened and the positioned to the entry which is the closest match to the current word. If Author & Source is current field, then the caret position determines which dictionary is opened: if caret is in the first field it is the dictionary of authors, otherwise the dictionary of sources.

The entries can be added to or removed from the dictionary at any time. The menu command Insert | To Dictionary (Alt+F8) adds all relevant current problem data to respective dictionaries.

When entering the new problems, user can for instance start typing in the Author & Source field "abdu", then press the F8 key and then the Return key, and the string "Fadil Abdurahmanovic" will replace the four typed letters (provided than there is such entry in the dictionary). If there are more than one entries starting with "abdu", user should use up or down arrow to position to desired one and then press the Return key.


Storing the problem

Once the position (or any other field - author, condition, keywords or solution) is entered or altered, it should be stored to the file (book). Each new problem must be given a unique name before it is stored. The name consists of up to 8 alpha-numeric characters. Some special characters can also be used (those which are valid for old, short MS-DOS filenames). Changes to old problems are automatically stored back if "Autosave" option is enabled. Old problem can also be stored under new name (from menu: "Problem | Store As...", Ctrl+A), renamed or deleted.

Keep in mind that each change is appended to the end of current book, preserving all previous versions of the problem (which are invisible for user). Deleted problems are only marked as such, but not yet removed from the book (they are also invisible for user). This allows the restoration of changes made by mistake. However, the size of book is growing with every change, and from time to time it is recommended to compress it, discarding all previous versions or deleted problems (from menu: "File | Compress book).


Using the Book-shelves

The number of book can eventually grow so much that the user can face the difficulties in orientation through the entire library. For that reason MPL offers the possibility of grouping the books of similar kind - to place them in adequate "book-shelf".

It is possible to create up to 256 shelves. One book can be placed in one or more shelves (or may be left out of any shelf), but total number of "titles" in all shelves cannot exceed 4000.

To manage the shelves first select from the menu File | Manage Book-shelf. Then:

- To create a new shelf click the New button. Enter the name of the shelf (up to 28 letters) and press OK.

- To add the book(s) to the shelf select desired lines in the list of all library books and click the Add to Shelf button.

- To remove the book(s) from the shelf select them in the list of the shelf and click the Remove from Shelf button.


Library maintaince
Maintaining the library

Each re-write of the problem causes the growth of the book it belongs to, as well as of few for user transparent files (e.g, the file which keeps track of renamed problem in order to keep the links update). User should periodically perform the reorganization of the library which will compress all books and do the necessary operations before discarding the "technical" files. To do this chose from menu File | Reorganize library.

Occasionally, you could export something temporarily to a new book. When you do not need it any more it may not be sufficient just to delete it from the application folder. You should rather select from menu File | House cleaning and (carefully) select from the list what you do not need any more. The same dialog allows you to rename the book, as well as to discard index files if they are not needed (when needed again, it will be automatically created anyway when you try to open the index).


Using exported images

MPL can export diagram position to two types of image files which can be subsequently imported e.g in text processing program: Windows bitmap file (BMP) and Paintbrush file (PCX). You can export bitmaps individually for each problem from MPL default view, or select group of problems from the list and export them with single command. In addition, diagram can be copied to the Clipboard, wherefrom it can be immediately pasted to word processor.

To generate one-at-time diagram image use one of following Main menu commands:

File | Export >> Diagram to Bitmap File (Ctrl+B) - Exports the diagram image to Windows Bitmap (BMP) disk file.

File | Export >> Diagram to PCX File - Exports the diagram image to Paintbrush (PCX) disk file.

File | Export >> Diagram to Clipboard (Ctrl+Shift+Insert) - Exports the diagram image to Windows Clipboard, wherefrom it can be inserted directly e.g to opened Word document.

To generate a group of images use following List menu commands:

Export | Image >> Bitmap (Ctrl+B) - Generates image files for selected or all problems in Windows Bitmap format (BMP). Files are stored in subdirectory <book_name>.img.

Export | Image >> Paintbrush - Generates image files for selected or all problems in Paintbrush format (PCX). Files are stored in subdirectory <book_name>.img.

Images are stored in sub-directory under the application directory named <BOOK_NAME>.IMG. For instance, images from book MP_ORIG.PBZ will be stored in sub-directory <app_dir>\MP_ORIG.IMG.


Search tools

MatPlus Librarian provides few ways for finding the problems satisfying specific criteria: one simple (Find) and one advanced (Query). They differ in the scope of search, as well as in the variety of criteria which can be specified.

Find tool is limited to current book only and has restricted set of criteria. On the other hand, the scope of Query is can be either limited to single (currently open) book, or extended to all books in the library. It also offers a much wider set of criteria which can be combined with logical operators, e.g, each of two or more criteria must be satisfied, or one of few criteria is sufficient, or some criteria are mutually exclusive.

Another useful feature is the Index tool which allows systematic review of authors names, sources and themes within the book.


Find tool

Simple find mostly related to the data contained in the list of problems (see: Screen layout - list of problems). The simplest "approximate" find tool is to press a single key when list is displayed -- this will select the first row after the current one which begins with that letter (more accurate: to the first problem with the name starting with that letter).

A more advanced tool is triggered by main or list menu command Problem | Find (keyboard accelerator: F3), which opens a Find Dialog box where user can specify search criteria, and Problem | Find next (keyboard accelerator: F4), which searches for next problem satisfying specified criteria.

User can specify up to four search criteria. The first problem in the book after the current one which satisfies at least one criteria will be opened. It should be kept in mind that this function in fact searches the list of problems, so only the data contained in the list rows are scanned, except when user explicitly specifies that he wants to extend the scope to the solution field, or to limit the scope only to the solution field. Thus, what can be searched for is e.g author's name, position of the kings, number of black or white pieces (see the example below) or content of keywords field.

Examples:

"d3/e5" will move to the next problem with white king on d3 and black king on e5. Consequently,

"d3/" will move to the next problem with white king on d3, while

"/e5" will move to the next problem with black king on e5.

";2+" will move to the next white minimal (note that if leading semicolon is omitted the 12 white pieces would also be a match).

"+2" will move to the next black minimal.

"herlin" will probably move to the next problem in book composed by Herlin, or the next problem showing the pericritical maneuver (provided that theme is correctly notified in keywords field).


Queries
Query

Overview

Query is a powerful feature which provides you with a quick search tool in a scope either of current book, or selected books, or even entire library. The search subject can be simply a text in one of the fields (e.g author's name in Author & Source field, or theme in Keywords field), or can be more sophisticated when problem position characteristics are concerned. A query can contain one or more commands of both types. The entries satisfying the query will be extracted and collected in special book named "~QUERY.PBZ", which will be immediately opened by another MatPlus Librarian instance. User can decide if he wants either the overwrite old query results, or add new problems to existing file.

For all extracted problems a full (qualified) "link-back" to original location is inserted at the beginning of the Keywords field. Qualified link is a string starting with "finger", followed by book name, dot and problem name. If there are two or more problems with the same name extracted from original books, all but one will be given a new name, and program will try to make it as similar as possible to the original name.

For textual search it is possible to limit the search to specific field(s), or to search in all fields. E.g if one looks for a problems with a key move, say, 1.Ke4!, it is practical to scan the Solution field only. On the other hand, if one wants only duplex problems, he will limit the search to Condition field.

The query is written in simple symbolic format consisting of one or several strings of commands separated by white spaces (blank or new line). Optionally, logical operators "and", "or" or "xor" may be inserted between the condition, and parenthesis may be used to override the precedence of operations. For some users it would be more convenient to use the Query Writer Assistant

The query string has following format:

cmd_1 [oper] cmd_2 [oper] cmd_3

cmd_4  [oper] ...  [oper] cmd_n

where

cmd_#	is one of commands explained below

oper is one of following logical operators (given in order of precedence):

&	AND operator

^	XOR operator

|	OR operator (default)

If operator is omitted then an AND is assumed.

AND is true only if both left-hand side and right-hand side command are true.

XOR is true if only one of left-hand side and right-hand side command is true.

OR is true if at least one of left-hand side and right-hand side command is true.

Following "truth table" lists the results of logical operations for all possible left-hand and right-hand side condition results:

Query operators are resolved in precedence order: AND (the highest priority), XOR, OR from left to right, unless the parenthesis are used to force the expression within them to be resolved first. The parenthesized expression may also contain a further nested parenthesized expression, which will, again, be resolved before the outer one.

A condition consists of command prefix followed by a statement terminated by white space. Only literal strings between quotes may contain the spaces which will not terminate the condition.

A set of pre-defined templates is available for user, most of which contain question marks in place of arguments. If a question mark is present in submitted command, it will be "eaten" before parsing.

Text search

Command syntax is:

@ [ F ] "<string>"

where:

@ is text search command prefix

F is optional specification of fields which are to be scanned and can be one or any combination of following (upper- or lowercase):

A for Author & Source field

C for Condition field

K for Keywords field, or

S for Solution field

<string> is a text which is to be looked for.

The comparison is case insensitive. For alpha characters only English alphabet letters should be used. Letters specific to other languages are substituted by the "best match" English letters.

Examples:

@A"Mansfield"

will extract all problems with name Mansfield appearing anywhere in Author & Source field

@C"h#2"

will extract all problems with helpmate in two condition, provided that the recommendations in chapter Filling the Condition field have been followed.

@k"cycl" & !@k"chang"

will extract all problems which in the Keywords field contain first, but do not contain the second string (for completely and correctly entered problems probably all single-phase and perhaps few multi-phase cycles will be extracted).

Problem position characteristics

There are three groups of criteria which can be specified in current version of program: sum of (white, black or all) pieces, presence of certain pieces, and location of or relation between pieces on the board.

Sum of pieces

Command syntax is:

<prefix> [ w / b ] #

where:

<prefix> specifies one of three possible conditions:

<	means less then or equal to

>	means more than or equal to

=	means equal to

w or b specifies that only sum of white or black pieces respectively matters, and

# is then number of pieces.

Examples:

<7

extracts all miniatures (7 or less pieces),

<w2

extracts all white minimal problems,

>18

extracts all heavy-weight positions,

=b16

extracts all problems with complete black force.

=w16 & =b1

extracts all "Maximin" problems with full white power against sole black king (provided that the black king is not missing on the board -- more accurate condition is "=w16 & =b1 & +k", the latter command will be explained shortly).

Presence of pieces

Command syntax is:

<prefix> [ # ] X [ [ # ] X ... ]

where:

<prefix> specifies one of three possible conditions:

+ means that presence is required

- means that absence is required

# is optional parameter meaning "exactly", and

X stands for piece symbol in English notation

Command can optionally be extended to more conditions, all of which must be satisfied for extraction of the problem (AND operator is applied between condition). For example

+2R0S

is same as:

+2R & +0S

or:

+2R & !+S

or:

+2R & -S

The presence or absence of pieces not mentioned in the command is irrelevant for search.

Examples:

+R

extracts all problems in which at list one white rook is on the board

+2R

extracts all problems in which two white rooks are on the board

+Q2R

extracts all problems in with white queen and two white rooks on the board, but to extract problems with "Fascineerend material" (ONLY white king, queen and two rooks) the command must be more accurate:

=w4 & +K & +Q & +2R

where first condition limits the number of white pieces to four, and exactly this number of pieces is required by conditions which follow.

Location and relation of pieces

Command syntax is a little more complex than those discussed so far:

[:]X[<loc>][~]<dir>[<ofs>][~]X2[,[<ofs2>]X3 ... ]

where

: (colon) is an optional 'dynamic' relation command prefix; if it is omitted, a 'static' relation is assumed; dynamic search is extended to positions which may appear after the white first move.

X is a placeholder for starting piece symbol in English notation, uppercase for white and lowercase for black;

<loc> is optional location of starting piece, which can be given either in algebraic notation or in one-based coordinates;

~ (tilde) is optional prefix for line search which allows masked lines to be accepted; the same symbol can be used later in the same command, but with different meaning;

<dir> is search direction, which may be one of following:

/ (slash) means diagonal direction

+ (plus sign) means orthogonal direction

* (asterisk) means line direction (diagonal and/or orthogonal)

: (colon) means any offset, not necessarily along the same line.

A double direction symbol extends search to lines passing by the first mentioned piece (good e.g for indirect batteries).

<ofs> is a distance from starting piece (e.g distance between 3rd and 4th row is 1, and between "c" and "g" files is 4)

~ (tilde) is now a prefix which means that next piece can also be a queen (useful e.g in case of rear battery piece);

X2 is either a second piece symbol in English notation (uppercase for white and lowercase for black, or "X" / "x" for any white / black piece.

, (comma) is sequence operator which means that description of relative position of another piece follows.

The position can be analyzed statically, and to some extent dynamically, which means extension to all possible position after white first move. Dynamic search is slightly slower and has a side effect which user must be aware of: no logical test is performed on new positions, thus some absurd moves (e.g exposing white king to check or creating a direct 'battery' with-like moving front and rear piece) may be accepted.

Examples:

q

extracts all problems with black queen on the board.

qd7

extracts all problems with black queen on d7 (but not on e.g e7 or other corresponding rotate/flip squares).

q47

extracts all problems with black queen location 4+7 squares from two perpendicular edges of the board (namely: d7, e7, b4, b5, d2, e2, g4 and g5).

Ke1 & (Rh1 | Ra1)

or	Ke1 (Rh1 | Ra1)

will extract all problems with white king and one of rook on initial position (squares between them may be either empty or occupied by other pieces); however,

Ke1 & Rh1 | Ra1

will extract few position more with white rook on a1 and without white king on e1, since the ORed commands are not parenthesized, and with rook on a1 and either king not on e1 or rook not on h1 the resolving order will be 1) :Ke1 & Re1 = FALSE, 2) FALSE | :Ra1 = TRUE. In previous case the resolving order was: 1) :Rh1 | :Ra1 = TRUE, 2) :Ke1 & TRUE = FALSE.

k/X,~B

will extract all diagonal batteries, and

k~+X,~R

will extract orthogonal batteries, either direct or masked by one or more black and/or white pieces.

However, with both diagonal and orthogonal direction, the last piece in similar cases should be a white queen (with enabled corresponding rook or bishop alternative). Thus:

k*x,x,~Q

will extract all black (non-masked) halfpins. It would be inaccurate to write e.g:

k*x,x,~B

since this would extract all diagonal halfpins and only those orthogonal with white queen on the black king's line.

To find all possible positions with any kind of battery (either direct, masked or indirect) aiming to or beside the black king, issue a command:

:k~*X,~Q

However, for indirect batteries only there is not way to get correct result in a single-query. The first query should be issued with above command, then to rename a book with results (since query cannot be done on result file) do following query:

!k~*X,~Q

As mentioned earlier, a single-pass request:

:k~**X,~Q & !k~+X,~Q

will probably result with none or very few extracted problems, because second command will also be a dynamic one and it is very rare case that in position with indirect batteries there is no possibility to create a direct one in one move.


Query Writer Assistant

MatPlus Librarian offers a more user-friendly tool for defining the Query. It is a Query Writer Assistant (QWA) which is opened by pressing the "Assist" button in Query dialog.

Creation of the query consists if successive selection from lists of possible options, and occasional entry of the values (numbers, coordinates or texts). In case of error press Left arrow or Backspace, or click on Right mouse button.

Selection from list of options

There are three possible ways to choose from list:

1) Use Up or Down arrow to position to desired item (highlight it), then press Right arrow or Return.

2) Type the first few letters of desired list item. As soon as the unique item matches the typed string it is inserted into the text.

3) Point with cursor to desired item and click left button.

Entering the value

Numeric: type the value (one or few digits) and press either Space or Right arrow; eventually, you can press the semicolon key which will complete the entry of the value and insert end of command symbol after it.

Coordinate: Enter the coordinate in algebraic notation and press either Space or Right arrow; eventually, you can press the semicolon key which will complete the entry of the value and insert end of command symbol after it.

Distance: Just type a numeric key.

Two distances: Type two a numeric keys for perpendicular directions. A plus sign will be automatically inserted in between just for the better readability. It is irrelevant whether the horizontal or vertical direction is entered first -- the search will be done in four directions (including negative).

Text: Enter a string and finish it with quote or Right arrow. If you type a semicolon, it will be considered a part of the string. A quote cannot be in the string. Backspace or Left arrow deletes last character in the string. However, once the string is completed, Backspace or Left arrow will delete entire string.

QWA "language":

1. Prolog section
for

  (1)	  current book / current shelf / entire library

  (2)	  CREATE result book / APPEND TO result book

of problems	==> 3

(1) determines the scope of the query, and (2) the disposition of output file (result book). QWA continues from step 3: Command prefix.

2. Logical operator

  (3)	AND

  (4)	OR

  (5)	XOR

  (6)	END

(3), (4) and (5) are logical operators between two commands. (6) completes the query script.

3. Command prefix

  (7)	NOT

  (8)	(

(7) is optional unary negation which inverts the condition of command which follows. (8) is optional nesting "start of group" operator in case that two or more commands are grouped as one expression.

4. Command

sum of

presence of

location of

relation

dynamic relation

text in

Each starts respective command: Sum of pieces, Presence of pieces, Location of pieces, (Dynamic) Relation of pieces, or Text search. From here the command syntax diverges:

5. Sum of pieces command syntax

 	all pieces

white pieces

black pieces

defines which pieces should be summed, and then

equal to

less then or equal to

greater than or equal to

which sum will satisfy the condition.

<number>

Determines the comparison number of pieces and

;	==> 2

is end of command operator, and QWA continues from step 2: Logical operator.

6. Presence of pieces command syntax

at least one	==> 6.1

exactly

define the number of pieces and the condition (e.g only exact number of pieces on board is satisfactory)

<number>

is necessary if exact number of pieces is looked for.

6.1.	White

Black

defines the color, and then

King

Queen

Rook

Bishop

Knight

Pawn

the type of the piece.

(9)	OR	==> 6

(10)	;	==> 2

(9) continues the same command (it allows the specification of more pieces), while (10) ends the command and QWA continues from step 2: Logical operator.

7. Location of pieces command

White

Black

defines the color, and then

King

Queen

Rook

Bishop

Knight

Pawn

the type of the piece.

<coordinate>

is the location where the piece should be to satisfy the request.

(11)	AND	==> 7

(12)	;	==> 2

(11) continues the same command (it allows the specification of more pieces), while (12) ends the command and QWA continues from step 2: Logical operator.

8. Relation or dynamic relation between pieces

from

  White

  Black

defines the color, and then

  King

  Queen

  Rook

  Bishop

  Knight

  Pawn

the type of the starting piece.

<coordinate>

is optional location of that piece on algebraic or 2-digit form (if omitted, any location of any piece of that color and type is good). If entered in algebraic notation, then only exact position of the piece is searched for. Otherwise, if entered in two digits, then all corresponding squares (rotated and mirrored) will match.

8.0.	diagonally	==> 8.1

orthogonally	==> 8.1

along any line	==> 8.1

(13)	at distance of	==> 8.2

first three specify to which direction to search for and QWA continues from step 81., while (13) tells that fixed relation is searched for.

8.1. 	>>

which may be masked

allows inclusion of masked lines, and then

>>

or adjacent

inclusion of also parallel adjacent lines (e.g useful if indirect batteries are looked for), and finally

>>

at distance of

specification of fixed distance between first and second piece on given line and/or diagonal.

White

Black

defines the color, and then

(14)	Piece

(15)	Line-Mover

King

Queen

Rook

Bishop

Knight

Pawn

the type of the second piece. (14) means that any piece is good, while (15) defines the piece which moves along given line or diagonal Q and R and/or B.

(16)	FURTHER	==> 8.0

(17)	;	==> 2

(16) continues the same command from step 8.0 if there another piece in required relation i, while (17) ends the command and QWA continues from step 2: Logical operator.

Fourth option from step 8.0 continues from here:

8.2.	  <2 digits>

squares

specify the distance from the starting piece (either in horizontal + vertical, or in vertical + horizontal direction).

White

Black

defines the color, and then

(18)	Piece

King

Queen

Rook

Bishop

Knight

Pawn

the type of the second piece. (18) means that any piece is good.

(19)	FURTHER at distance of	==> 8.2

(20)	;	==> 2

(19) continues the same command from step 8.2 if there another piece in required relation i, while (20) ends the command and QWA continues from step 2: Logical operator.

8. Text search command syntax

one of fields "

author & source field "

condition field "

keywords field "

solution field "

defines which field to scan for text and

<text>

is the string which is searched for.

;	==>2

ends the command and QWA continues from step 2: Logical operator.


Query Writer Assistant
Query examples

Here are some examples from section Queries, together with corresponding QWA text (without prolog);

q

"presence of at least one Black Queen ;"

extracts all problems with black queen on the board.

qd7

"location of Black Queen d7 ;"

extracts all problems with black queen on d7 (but not on e.g e7 or other corresponding rotate/flip suares).

Ke1 & (Rh1 | Ra1)

"location of White King a1 ;

 AND (

    location of White Rook h1 ;

 OR location of White Rook a1 ;

  )

END "

will extract all problems with white king and one of rook on initial position (squares between them may be either empty or occupied by other pieces);

k/X,~B

"relation from Black King diagonally White Piece

FURTHER White Line-mover ;"

will extract all diagonal batteries, and

k~+X,~R

"relation from Black King ortohogonally

which may be masked White Piece

FURTHER White Line-mover ;"

will extract orthogonal batteries, either direct or masked by one or more black and/or white pieces.

However, with both diagonal and orthogonal direction, the last piece in similar cases should be a white queen (with enabled corresponding rook or bishop alternative). Thus:

k*x,x,~Q

"relation from Black King along any line Black Piece

FURTHER Black Piece

FURTHER White Line-mover ;"

will extract all black (non-masked) halfpins.


Index tool

This tool provides alphabetical list either of authors names, or sources, or themes within the current book with references to all problem numbers where the respective term appears. Moreover, it provides fast "walk" (forth and back) through the listed problems by simple mouse clicks or single key presses.

Index of authors extracts and sorts the terms from the first line of the Author & Source field. In case of joint compositions, the names are expected to be separated by ampersand(s).

Index of sources extracts and sorts the terms from second and all remaining  lines of the Author & Source field. For guidelines how to enter data in this field see the section: Filling the Author & Source field

Index if themes extracts and sorts the terms from the Keywords field. This is a multilevel index, provided that instructions given in the section How to use the Keywords field were followed.

Creating the index

To create the index select from the menu File | Make Index. It opens the dialog which allows you to specify which index you want to create, and also some options which are here briefly described.

Last name, First name - Related only to index of authors. If checked, the entries will be sorted by authors' last names.

Main entry always - Relates only to index of themes. If checked, then numbers will be inserted alongside the main entry and alongside the bottom-level entry for given term. Normally, numbers are shown for bottom-level entries only.

Sublevel entries - Relates only to index of themes. If checked, then numbers will be inserted alongside the main entry and alongside all sub-level entries for given term.

Prefix and Suffix - Obsolete. Allow specification of string which will be placed before or after the problem numbers.

Start # - Obsolete. Overrides the default starting number (which is always 1).

Indexes are stored to disk files with the same name as the book file, and with extension .pxa for index of authors, .pxs for index of sources and .pxt for index of themes. Three or more successive numbers are shown as range: first number, en-dash and last number, with note that en-dash code in MatPlusTextRc font is at location 0x96 (150 decimal).

"Walking" through the Index list

Index is shown as standard Windows List-box. You can go through the listed problem by positioning to the desired term (row) and press one of following keys or key combinations:

Ctrl+Shift+F7 - go to first problem

F7 - go to next problem

Ctrl+F7 - go to prior problem

At any time you can use menu command Problem | Goto item # (F5) and explicitly type the number of the problem you want to open.


Forsyth notation

The Forsyth notation consists of enumerating empty and occupied squares starting from the upper left corner of the board. Digits are used to represent the empty squares, uppercase letters for white and lowercase letters for black pieces. Rows are separated by either dash, slash or dot.


Notation

Notation dialog offers the possibility to select between several languages, or to define a custom symbol for pieces.


Page Setup dialog

Font sizes - enables user to specify independently the height of font used for text, and of font used for drawing the diagrams.

Diagram options - Hatch selects the diagonal lines to fill the black fields, while Shade selects the gray brush. Each of remaining four radio buttons selects the diagram drawn as bitmap from the same resources used for screen diagrams, though obligatory with hatched black squares. The percent field allows the stretching or shrinking the bitmap.

Diag/page - selects between one, two or four diagrams to be drawn on a single page. The last optimum will print maximal number of diagrams per sheet of paper, and then solutions on separate sheet(s).

 Margins - defines the margins from the edges of the paper, as well as the margin (gutter) between diagrams if more than one diagram is drawn on the page.

Diagram border - Line width specifies the thickness of the line in device pixels, while horizontal and vertical shift allow the tuning of the diagram rectangle position.

Print Keywords - if checked then the content of Keywords field will be printed in the bottom of the problem's print area.


Technical information
Technical information: Disk file format

This is the information for those who want to include import and export modules for MatPlus Librarian books in their applications.

MatPlus Book is stored to disk as a plain text file with extension ".PBZ". Lines are separated by <CR-LF> (13-10 decimal, 0d-0a hexadecimal) pairs. The text is logically divided into records (problems), each of which consists of several fields (e.g author & source field, diagram, solution, condition, keywords). The "@" (at sign) at start of the line followed by one letter (N, n, R, X, A, D, C, K or S) designates the start of the record (N, n, R or X) or field (A, D, C, K or S). The plain text format is chosen because the 25 years of author's experience have shown that it offers the simplest recovery possibility if file is damaged (e.g bad disk sector). This format has its disadvantages in slower access, or in cumulating of chunks of overhead data, but they can be easily overcome by a dynamic pointers file (which is automatically re-created whenever the text file is changed) and by the compression routine which discards all inactive (updated, renamed and deleted) records.

One should keep in mind that current file format is inherited from initial primitive method of keeping each problem in separate file, so the "problem name" line corresponds to the old problem file name and should be unique in a scope of one book.

Start of record (problem) line(s):

@N<problem_name> line starts the record (problem). <problem_name> is string of up to 8 DOS-file-name valid characters. If shorter than 8 bytes, it is recommended to pad it with dots until eight, which will reserve enough space for rename with simple re-writing the original line (otherwise, the whole problem record is appended to the file and the original problem data becomes inactive).

@R<problem_name> starts the inactive problem (renamed record).

@X<problem_name> starts the inactive problem (deleted record). Deletion of the problem consists of simple re-writing the "X" byte at position of original "N".

@n<problem_name> line (with lowercase "n") has the same meaning as the "@N" (uppercase "N") line. However, it usually means that the record is appended without test for duplicate name and MPL will assign the new, unique name to this record if necessary.

Start of field lines:

@A<string> line starts the Author & Source field.

@D<Forsyth_string> is the Diagram field line. Position is given in Forsyth notation preceded by parenthesized enumeration of piece symbols (see examples below.

@C<string> is the starting line of Condition field;

@K<string> is the starting line of Keywords field;

@S<string> is the starting line of Solution field.

The capacity of all fields is limited to 1024 bytes each, except the Solution field which can hold about 28600 bytes. Thus, the length of the problem record should never exceed 32K bytes.

How to scan the book file

Keep in mind that there can be more than one start-of-problem lines with the same problem name. Only the last one is relevant, since each modification appends the record to the book.

1. Read the file one line at time until the start-of-problem line.

2. Remember the file position of current line.

3. Continue reading lines until another start-of-record line (or end of file) encountered.

4. Subtract the remembered line file position from this line position and you will have the length of previous record.

5. For next record(s) continue from step 2 until the end of the file.

You could allocate an array of structures in which you will keep problem names, file positions and lengths -- a kind of directory -- which will later serve for direct access to individual problems (records) and isolating its fields.

Alternatively, you can use the MatPlus pointers file which is automatically created when book file is opened either for the first time, or with disabled "quick open" option, or after the book has been compressed. The pointers file has the same name as corresponding book file and extension ".PBX". Pointers file has three blocks of data:

- File header (see QHDR structure below) (160 bytes)

- Array of PBX records (16 bytes each)

- List of problems used internally by MatPlus Librarian

Here is a C code declaration of QHDR and PBX structures (DWORD is unsigned long integer, and BYTE is unsigned char type):

typedef struct tagQHDR {

  char  szKey[16];      // "MatPlus Library"

  DWORD dwPbzDate;      // modification date

                        //    of book file

  long  lProblems;      // problems in PBX structure

  long  lCurProblem;    // current problem

  long  lMax;           // internal use

  char  szTitle[64];    // asciiz book title

  char  szNote[64];     // asciiz note

  DWORD dwPbzSize;      // size of book file

  long  lValidProblems; // internal use

  long  lTopItem;       // internal use

  BYTE  bSpare[4];      // unused

} QHDR;

typedef struct tagPBX {

  char  szName[9];       // asciiz problem name

  DWORD dwPos;           // file position of

                         //   the problem name line

  int   cb;              // length of this record

  BYTE  fOldVersion : 1; // newer version exists

                         // in later in the book

  BYTE  fNewVersion : 1; // has earlier version

                         //   in this book

  BYTE  fShortName : 1;  // problem name is not

                         // padded to 8 bytes

  BYTE  fDeleted : 1;    // problem is deleted

  BYTE  fNew : 1;        // new entry

  BYTE  fHasLink : 1;    // keywords field

                         //   contains the link(s)

  BYTE  fRenamed : 1;    // problem is renamed

  BYTE  fVisible : 1;    // internal use

} PBX;

For your information, the format of the last block is following:

struct {

  int length;   // length of the row including

                //   the terminating NULL byte

  char szRow[]; // row data (length bytes) with

                //   TABs (0x9) between columns

} ROW;

Example (part of the A2345.PBZ book):

.....

@N2a_00024

@AW. A. SHINKMAN

Elmira Telegram 1883

@D(KDTLSP)25p4L9p1kP4p1L2K2S2D

@C#2

@S*1... Kb2/b4 2. Lf6#; 1. Dh5! (~), 1... Kb2/b4 2. Dh8#, 1... Kb4 2. Ld2#, 1... Kd4 2. Lf6#

@Kkey,ambush

@N2a_00025

@AS. LOYD

Detroit Free Press 1884

@D(KDTLSP)12S15p1P3K4p3L1k1pT6P2D

@C#2

@S1. Lc2! (~), 1... Ke2/Kf2/Kg2 2. Le4#, 1... Kg4 2. Ld1#, 1... e4 2. Ld1#

@Kkey,flight-giving,3

.....

describes following two problems:


Solving tools

One of main roles MatPlus Librarian is supposed to have in composer's life is the assistance in composing chess problems. Apart the various tools for changing the diagram, very often composer needs a more subtle assistance in testing the soundness of the position.

MatPlus Solver (vers. 1.0) is a built-in tool still in the early phase of its development. Anyway, although based on a primitive algorithm, it can be very helpful in composing the direct twomovers, and up to certain extent for threemovers and helpmate twomovers. Meanwhile, until a better built-in solving module is offered, MPL provides export facility for few much more advanced solving programs: Alybadix and Chloe are real solving "smashers". There is also a very interesting program Gilgamesh, and fascinating Problemiste chess problems base.

It should be mentioned that file formats for both Alybadix and Chloe are not documented by authors and they are "deducted" from the hexadecimal dumps of disk files they produced. That's why MPL generated files are without eventual twinning information in any of exported files.


MatPlus Sover
MatPlus Solver

MatPlus Solver is called by menu command Solving | MatPlus (or #5 key on numeric keypad) for a key move only,  and by command Solving | MatPlus Analyzer (or #6 key on numeric keypad) for complete solution. User can select between several options what he wants Solver to analyze - See Solver Menu.


Alybadix

Alybadix is excellent and extremely fast solving program written by Ilka Blom. For those ho want obtain the program here is Ilka's e-mail address: iblom@walli.uwasa.fi

To export current problem from MPL default view select menu command Solving | Alybadix (or press Alt+F6). This will generate the file with the same name as current problem and extension .POS in MPL application directory.

To open it in Alybadix select Disk Menu (press key "D") in Alybadix Main menu, and then change the current drive/directory to MPL application directory. For instance, if it is C:\MatPlus, press "C" in disk menu, then press "8", delete the displayed path (unless it is not "MATPLUS"), type "MATPLUS" and press Return key. Then select "Load Problem" (LP) and find the exported filename in list of problems. For your convenience, MPL places its application path to the clipboard, which can be pasted to Alybadix window, which will save you from some typing.


Chloe

Chloe is excellent and extremely fast solving program written by Christian Poisson. For those ho want obtain the program here is Christian's e-mail address: christian.poisson@free.fr

To export current problem from MPL default view select menu command Solving | Chloe (or press Shift+F6). This will generate the file with the same name as current problem and extension .CHL in MPL application directory.

To open it in Chloe select "O - Directory" in Chloe menu. Chloe will first ask for the drive - type the drive letter of MPL path. Then Chloe asks for the directory - type the path for MPL application. For your convenience, MPL places its application path to the clipboard, which can be pasted in this moment, which will save you from some typing. Then open the problem as usually you do ("F - NEW PROBLEM", etc.).

Christian Poisson also maintains the Web site Problemesis which is worth visiting -  http://www.multimania.com/cpoisson/problemesis


Gilgamesh

Gilgamesh is an interesting Windows program by Marc Ph. Lavaud and Jaques Rotenberg, dedicated mostly to direct twomovers, either orthodox or with various fairy pieces or conditions. The only supported version is 1.0 (1993), although the voice came that authors continued the development of the program and realized some new versions.

Contact Jacques Rotenberg at one of following e-mail addresses: Rotenberg@hotmail.com, or Jacques.Rotenberg@wanadoo.fr


Problemiste

A fascinating chess problems base designed by Matthiew Leschemelle runs on Windows platform. MPL can generate files in Problemiste format, although currently eventual twinning information is added in a text field instead of special twins field. Meanwhile, Matthiew has provided the specification for that field and it will be implemented shortly.

The greatest importance of Problemiste is that this is actually the first chess problems exchange format. Program files and many bases provided by problemists from all over the world can be downloaded from Web site http://perso.easynet.fr/~mleschen


Popeye

Popeye is a freeware program initially written in Pascal by Philippe Schnoebelen and subsequently handed over to Elmar Bartel & friends... The program, as well as the complete source code is available at http://archiv.leo.org/pub/rec/games/popeye/

MatPlus can use Popeye directly as a kind of the "Solving Machine", though the communication is done on file-to-file basis. That means that, on request, MatPlus generates the command file, passes it as the parametar on Popeye call, and then waits for Popeye to finish its job. When it happens (i.e, the Popeye MS-DOS session ends), MatPlus reads the Popeye output file, and presents it slightly reformatted in respective window.

Since Popeye covers a number of fairy pieces, types and conditions which are not supported by MatPlus, a method for overriding the default comunication is provided. User can supply either the complete Popeye command script, or the addition to a script (or partial script) passed by MatPlus. They should be entered in the MPL Solution field.

If there is a string "BeginProblem" in the Solution field, MPL will export the portion between this line and the "EndProblem" line (or to the end of the Solution field if the latter line is missing) to the Popeye command file.  Note that this portion MUST contain the complete script including the position, stipulation, etc... Nothing else will be generated by MPL, so all possible errors should be fixed within the user-provided script. MPL offers the assistance in generating the script by providing the default one based on current problem.

The partial script is a portion between the line "PopeyeBegin" and "PopeyeEnd" (or end of the Solution field if latter is omitted). Any available Popeye command may be entered here. Since at the moment MPL has not the intellegence to generate the twin conditions, the partial script is so far the only way to do it.

See also: The Popeye Documentation File.


Popeye DOC File

(This chapter is given 'as is' - as downloaded from Popeye home location http://archiv.leo.org/pub/rec/games/popeye/)

     D E S C R I P T I O N   O F   P O P E Y E    3 . 7

Some remarks on the distribution of popeye:

Popeye is free software. It means that everybody may get the source of

popeye.  We believe that this software should be public und constitutes not our

own personal property - even we have invested a lot of work. This work cannot

be waged by money, and also we devote our time to popeye not to earn money.

Therefore we distribute popeye for refunding our costs of material and shipping.

It means, if someone gets a floppy from us, he should return a floppy.

Its also possible to send us stamped return envelope with a floppy, we return

the floppy with popeye on it. We do not mind if someone redistributes popeye.

The only thing we want to obeye is, that he distributes it as he gets it -

meaning all the files listed below.

py-engl.doc:    The file you are reading now

py-deut.doc:    German version of this file

py-fran.doc:    French version of this file

history:        The developpers describe here which bugs have been

fixed and what's new in POPEYE.

readme:         Short hints for those, who want to recompile popeye

pydos32.exe:    Executable file for MS-DOS (32 Bit, 80386)

pywin32.exe:    Executable file for MS-Windows95/-98/-NT

py-*.str:       These files contain the language dependant text

for popeye. They must reside in the same directory

as the executable.

List of source files:

makefile.unx:   Makefile for UNIX-systems and friends

py.h:           Header-file for all C-files.

pydata.h:       All global data are define here.

pydata.c:       For the generation of pydata.o.

py1.c, py2.c, py3.c py4.c (+py4.h) py5.c py6.c:

C-Source of popeye.

pyhash.c:       dynamic hashing functions.

dht:            package supporting "dynamic hashing".

pyint.c:        Procedures for intelligent mode calculation.

pyio.c:         Everything concerning I/O is coded here.

pymsg.c:        All procedures for output of messages.

pylang.c        Language dependent procedures.

pyproof.c:      Procedures for shortest proofgame calculation.

pysignal.c:     All procedures for UNIX signal handling.

pytime.c:       All procedures for meassuring time.

pymac.h:        Segmentspecification of Macintosh's MPW

pymsg.h:        Defines for the messages of popeye.

pyproc.h:       Definitions of the procedures.

todef.awk:      awk-script to convert enumerations in py.h to defines.

toenum.awk:     awk-script to convert defines in py.h to enumerations.

py-*.msg:       The language dependent files for Popeye-messages.

pie*.dat:       The files for LaTeX output of the pieces which Popeye knows.

genpystr.c:     Source of the program which generates the py-*.str

from py-*.msg.

BEISPIEL:       Directory which contains example-files in

german language and their results.

DHT:            Directory containing C-files for the dynamic

hashing package.

LATEX:          Directory containing LaTeX files.

Starting popeye:

Change the name of your preferred executable to py.exe

To operate it from the terminal:                py

To solve problems recorded in file XX:          py XX

   or:          py < XX

Commandline parameters:

-maxmem

You can provide for Popeye for example 4096 kilobyte (or 4 megabye)

of memory with

py -maxmem 4096 XX    or   py -maxmem 4M XX

to make calculation of problems faster.

Stopping Popeye:

        press  CTRL + C  key combination

Description of the input language of popeye:

The input to popeye is not case sensitive. Every input to popeye starts with

the reserved word `BeginProblem'. After entering this command to popeye,

following commands may be used:

remark, author, origin, title, protocol,

        condition, option, stipulation, forsyth, pieces, twin

The order of these commands is free, and can also occur more times.

The last of the commands in the second line is relevant. All of these

commands expect further parameters. Lets start with the simpler commands:

 - remark: this keyword introduces a comment. Everything up to the end of the

line will be ignored and has no further effects.

 - author: The parameter to this command is the author of the problem. All

Text up to end of line will be put above the diagram in the output.

This input is completely optional and has no effect to the other

capabilities of the program. All the input of multiple author

commands will be placed on the output.

 - origin: All the same as the author command.

 - title:  All the same as the author command.

 - protocol: The parameter to his command is interpreted as filename, and all

further output of popeye on the screen is also placed in the given

file. If the file exists already, the output of popeye is appended to

the file. The file will not be deleted.

 - condition: All the conditions neccessary for the problem, seperated by

blanks or newline, should be given to this command.

        Through combination of single conditions you can get other

        already existing conditions:

        for example: Circe  and  Immunchess  results in  StrictCirce

        The following conditions are implemented:

RexInclusiv

Circe

MirrorCirce

Madrasi

Volage

Hypervolage

BichromChess

MonochromChess

GridChess

KoeKo

BlackEdgemover

WhiteEdgemover

Leofamily

ChineseChess

Patrouille

PWC

NoCapture

ImmunChess

MirrorImmunChess

ContactGridChess

Imitator

CavalierMajeur

HaanerChess

CouscousCirce

ChameleonCirce

EquipollentsCirce

FileCirce

Sentinelles

BlackMaximummer

WhiteMaximummer

BlackMinimummer

WhiteMinimummer

MagicSquares

DiagramCirce

Tibet

DoubleTibet

Hole                    (= a field where you cannot move to)

BlackMustCapture

WhiteMustCapture

TransmutedKings

BlackFollowMyLeader

WhiteFollowMyLeader

DuellistChess

ParrainCirce

SymmetryCirce

NoIProm                 No Promotion to Imitator allowed

VogtlaenderChess

EinsteinChess

Bicolores

NewKoeko

CirceClone

AntiCirce

MirrorFileCirce

AntipodenCirce

MirrorCirceClone

MirrorAntiCirce

DiagramAntiCirce

FileAntiCirce

SymmetryAntiCirce

MirrorAntiCirce

AntipodenAntiCirce

EquipollentsAntiCirce

FileImmunChess

DiagramImmunChess

MirrorFileImmunChess

SymmetryImmunChess

AntipodenImmunChess

EquipollentsImmunChess

ReversalEinsteinChess

SuperCirce

RelegationChess

NorskSjakk

TraitorChess

AndernachChess

BlackForcedSquare

WhiteForcedSquare

BlackConsequentForcedSquare

WhiteConsequentForcedSquare

ReflectiveKings

ChameleonChess

FunctionaryChess

GlasgowChess

AntiAndernachChess

FrischaufCirce

VerticalMirrorCirce

Isardam

ChecklessChess

DiametralCirce

PromOnly

ExclusiveChess

Marscirce

MarsMirrorCirce

PhantomChess

WhiteTransmutingKing

BlackTransmutingKing

WhiteReflectiveKing

BlackReflectiveKing

AntiEinsteinChess

MirrorCouscousCirce

BlackRoyalSquare

WhiteRoyalSquare

CirceAssassin

PlusChess

BrunnerChess

CentralChess

ExtinctionChess

RepublicanChess

        ActuatedRevolvingBoard

        MessignyChess

        Woozles

        BiWoozles

        Heffalumps

        BiHeffalumps

WhitePromSquares

BlackPromSquares

NoWhitePromotion

NoBlackPromotion

EiffelChess

ActuatedRevolvingCentre

Maximummer

UltraSchachZwang

WhiteUltraSchachZwang

BlackUltraSchachZwang

ShieldedKings

StingChess

NoWhiteCapture

NoBlackCapture

AprilChess

AlphabeticChess

LineChameleonChess

CirceTurncoats

CirceDoubleAgents

AMU

After the conditions Imitator, MagicField, Hole, FrischaufCirce,

WhitePromSquares, BlackPromSquares

or one of the ForcedSquares, list the fields on which the imitators

are to be placed, where the special fields are located, where

promoted pieces (FrischaufCirce) are located, or where the

white or black promotionsquares are located.

The condition  PromOnly   must be followed by a list of pieces, separated

through blanks. Promotion is only allowed for those pieces.

The list should be given in the same way as with the command pieces.

The condition ChameleonCirce can be followed by a list of pieces,

separated by blanks. The list determines how the pieces change before

rebirth. (Examples: "ChameleonCirce S B R Q S" is ordinary Chameleon-

Circe and equivalent to "ChameleonCirce", "ChameleonCirce S Q R B S"

gives reverse ChameleonCirce.)

After some of the Circe, Immun, Madrasi or Phantomchess conditions

        you can enter RexInclusive.

After all Anticirce conditions "Cheylan" or "Calvet" can be entered -

according to the type desired.

After the Isardam condition "TypeB" can be entered.

After the Sentinelles condition "PionAdvers", "PionNeutre", "ParaSentinelles",

              or Berolina can be entered, and also WhiteMaximum, BlackMaximum

              or TotalMaximum followed by a number.

After MessignyChess, (Bi)Woozles and (Bi)Heffalumps you can enter

        RexExclusive.

 - option: Everything which should be in effect should be given here as

blank seperated list. The following is recognized:

Try             calculate if a move is a try.

Defence         this option is followed by a number indicating the number

of defences which should be taken into consideration.

For instance  Defence 1  all real tries are calculated.

SetPlay         calculate setplay.

Threat          for moremovers: This option must be followed

by an integer. The opposit party has defended

when there is no threat in less or equal this

number of moves.

WhiteToPlay     white starts moving in helpplay.

Variation       show threats and variations.

MoveNumbers     Movenumber, already calculated move and cumulated

solving time on output.

StartMoveNumber This option is followed by the Movenumber

popeye was interrupted at.

NoWk            without white king

NoBk            without black king

Duplex          calculate stipulation for both sides

NoThreat        calculate variations without calculating threats

MaxSolutions    This option must be followed by an integer. Popeye

stops calculating if this number of solutions

are reached.

MaxFlightsquares  for moremovers: This option must be followed

by an integer. The opposit party has defended

when the number of flightsquares for it's king

are more or equal this number.

EnPassant       Must be followed by at most two fields. A possible

enpassant-key to this field(s) is calculated.

NoBoard         The chessboard is not printed to screen or into file.

NoShortVariations  Short variations are suppressed on output.

HalfDuplex      calculate stipulation only for the opponent side.

PostKeyPlay     The position entered is considered to be the position

after the key. Just the solution play is analysed.

NonTrivial m n  A special option to solve/cook/test long self and

(semi)reflex problems. The second argument n deter-

mines which black moves are considered to be trivial -

a move that can be met by a s#n (or r=n resp.). In

long problems (more than n moves) black has at every

stage at least one nontrivial move. I. e. a move that

doesnot lead to a s#n. The first argument m determines

how many additional nontrivial moves can be granted to

black by white during the whole solving procedure.

Example: nontr 0 1. This is the most restrictive option.

White forced to play moves that leave black with only

one move not met by a s#1.

Intelligent     intelligent (quick) solving of helpmate-moremovers.

After the intelligent option, the maximum number of

solutions per mating position can be given.

MaxTime         This option must be followed by an integer. Popeye

stops calculating if this number of seconds

solving time are reached.

NoCastling	This option must be followed by the fields of those

pieces, that cannot castle anymore in the diagram position.

Quodlibet       In s# or r# also direct mates are a solution.

StopOnShortSolutions  Calculation is terminated after detecting of

      short solutions.

 - stipulation: popeye knows the following stipulations:

any useful combination of

{  #= }

{  != }

{  00 }

{  %  }

{  ~  }

{  ep }

{  #  }

{ SER-  }   {  H  }     {  =  }

 { m-> } + { EXACT-} +  { SEMI- } + {  S  }  +  {  == }   +   n

{ RECI- }   {  R  }     {  +  }

{ Zxy }

{  x  }

{  ## }

{ ##! }

{  ct }

{  <> }

{ ctr }

{ <>r }

{ dia }   +  n{.5}

{ SER- }             +  { dia }   +  n

{ SER-}              +  { a=>b }  +  n

(m, n are the number of moves)

for example:

#3              mate in three moves

HZg74           help-targetfield-g7 in 4 moves

S+2             self-check in 2 moves

R==3            reflex-doublestalemate in 3 moves

HS#3            helpselfmate in 3 moves         (= help forced selfmate)

SER-+7          series-check in 7 movesn

SEMI-R+4        semi-reflex-check in 4 moves

x3              Capture in 3 moves

RECI-H#2        reciprocal helpmate in 2        (= Grazer helpmate)

SER-%4          series-Win_a_Piece in 4 moves

H##!4           help-"gegenmatt" in 4 moves

SER-H##3        series-help-"beidmatt" in 3 moves

2->ser-h#4      white makes 2 moves, then ser-h#4

h003            help-castling in 3 moves

dia6.5          Shortest Proofgame in 13 halfmoves

(after the seventh move of white)

ser-dia9        Series-Proofgame in 9 moves

reci-h(=)#4     helpalternative(stale)mate in 4 moves

ser-!=7         Series-AutoStalemate in 7 moves

ser-ct10        Series-direct circuit (switchback) in 10 moves

(of W piece)

h<>3            help exchange place in 3 moves

(Bl helps W swap 2 pieces from diagram)

ser-sctr2       series self circuit by rebirth in 2 moves

(W forces Bl to complete switchback of a W piece)

ser-h<>r5       series help exchange place by rebirth in 5 moves

(Bl helps W complete by rebirth the exchange

 of two Bl pieces)

#=2             mate or stalemate in 2 moves

h~1             any helpmove

SEMI is valid only in combination with direct reflex-play.

   All these stipulations must be followed by a number giving the

   count of moves.

 - forsyth: With this command you can enter the position in forsyth notation.

All these commands up to now are very easy to use. A little bit more

elaborate is the command

 - pieces: This command specifies all the pieces belonging to the problem.

After this keyword, the color of the following pieces must be given:

This is one of:

White

Black

Neutral

After the color specification

Chameleon

Jigger

Kamikaze

Paralysing

Royal

Volage

Functionary

HalfNeutral

HurdleColourChanging          (only for hoppers !)

may be given. All the pieces given after this will have these attributes.

After this specification follows the list of pieces: First the name

of the piece followed by the list of fields the piece should be

placed on. By giving a new color specifiation pieces of another color

may be entered without repeating the pieces command. Popeye knows the

following pieces:

15      1,5-leaper

16      1,6-leaper

24      2,4-leaper

25      2,5-leaper

35      3,5-leaper

36      3,6-leaper

37      3,7-leaper

ag      Andernach grasshopper

al      alfil

am      amazon

an      antelope

ao      maorider

ar      archbishop

b       bishop

be      bishop eagle

bh      bishop hopper

bi      bison                           1,3+2,3 leaper

bk      bouncy knight

bl      bishop-lion

bm      bishop moose

bp      berolina pawn

br      bishop/rook hunter

bs      berolina superpawn

bt      boyscout

bu      root-25-leaper (bucephale)

bw      bishop sparrow

c       cardinal

ca      camel

cg      contra grashopper

ch      camelrider hopper

cr      camelrider

ct      CAT (cavalier trojan)

cy      charybdis

da      dabbabba

dg      doublegrashopper

dr      dragon

ds      ("Diagonalspiralspringer")

du      dummy

ea      eagle

eh      edgehog

ek      erlking

em      empress

eq      equihopper

et      elephant	0,1+1,1+1,2 rider

f       friend

fe      fers

fr      fersrider                      like bishop, but different rebirthsquare

g       grashopper

g2      grashopper-2

g3      grashopper-3

gh      gnurider hopper

gi      giraffe

gl      gral                           alfil + rookhopper

gn      gnu

gr      gnurider

gt      girlscout

ha      hamster

k       king

ka      kangaroo

kh      kinghopper

l       locust

lb      bishop locust

le      leo

li      lion

ln      nightrider locust

lr      rook locust

m       moose

ma      mao

mg      marguerite                      g+sw+ea+m+ha

ml      maorider lion

mm      moarider lion

mo      moa

n       nightrider

na      nao	chinese nightrider

nd      nereide

ne      nonstop equihopper

nh      nightrider hopper

nl      nightrider lion

o       orphan

oa      moarider

ok      okapi                           knight + zebra

or      Orix                            English equihopper on queen lines

p       pawn

pa      pao

pr      princess

q       queen

r       rook

ra      rao                             chinese rose

rb      reflecting bishop

re      rook eagle

rf      root-50-leaper

rh      rook hopper

rl      rook-lion

rm      rook moose

rn      rose-lion

rp      rose-hopper

ro      rose

rr      rook/bishop hunter

rw      rook sparrow

s       knight

si      sirene

sk      skylla

so      scorpion

sp      superpawn

sq      squirrel

ss      ("Spiralspringer")

sw      sparrow

tr      triton

uu      ubiubi

va      vao

wa      waran

we      wazir

wr      wazirrider                     like rook, but different rebirthsquare

z       zebra

zh      zebrarider hopper

zr      zebrarider

 - Twin: Solving/testing of positions obtained by small changes of the

initial position. The following specifications are supported:

    Stipulation ...: The stipulation is changed. See the repective basic

command.

    Condition ...: Cange of fairy conditions. The old conditions are

subsituted by those put in.

    Move <square1> <square2>: Move the piece from square1 to square2. A

piece accidentally standing on square2 will be removed. Example:

twin move a3 b4.

    Exchange <square1> <square2>: The pieces on <square1> and <square2>

exchange places. Example: twin exchange a3 b4.

    Remove <square>: The piece located on the square specified is removed.

Example: twin remove e5.

    Substitute <piece1> <piece2>: All pieces of type 1 are replaced by

pieces of type 2. Colour and further piece specification (like

paralysing etc.) are not effected. Example: twin substitute R B.

All rooks are replaced by bishops.

    Add <colour> <piecespecs> <type><fieldlist>: Adding pieces. Example:

twin add black para NHa6 - a black paralysing NightriderHopper is

added on a6. See the basic command "pieces".

    Rotate n: Turns the board by n degrees to the left (n=90, 180, 270).

Example: twin rotate 180.

    Mirror a1<-->h1: Mirrors the position on the vertical middle line.

    Mirror a1<-->a8: Mirrors the position on the horizontal middle line.

    Mirror a1<-->h8: Mirrors the position on the diagonal a8-h1.

    Mirror h1<-->a8: Mirrors the position on the diagonal a1-h8.

So, not the mirror line is given, but square into which a1 (or h1)

is turned into.

    Shift <square1> <square2>: Shift the whole position into the direction

determined by the two squares entered. Example: twin shift a1 a2 -

all pieces are moved one square up.

    PolishType: All pieces change colour.

More than one change may be specified, for example twin rem e7

add white qe8. As you can see the twinning commands can abreviated.

By default the changes refer to the position initially set.

Alternatively the changes can be applied to the position solved most

recently. Just enter "continued" (or "cont") immediately after

"twin". Example twin cont rem a1.

 - ZeroPosition: This command can be used alternatively to the command

"twin". It indicates that the initial position is not for solving.

The command must be followed by the changes for the first position

to be solved. Example: zero move b4 d5

       twin move c5 b5.

When all data have been entered to describe completely the problem, the solving

may be started by giving the keyword `endproblem' to popeye.

Immediately after reading this, provided no input errors were discovered,

popeye starts to solve the problem.

Here comes a sample:

BeginProblem

Author          Unknown

Origin          Also Unkown

Stipulation     #2

Pieces          White   Ka3 Ra8

Black   Kb1

Option          MoveNumbers Try Set Variation

EndProblem

This input seems long and cumbersome. But Popeye recognizes the keywords

as long as the shortage is unique. The above input may also be written

like this:

Begi

Auth    Unknown

Orig    Also Unkown

Stie    #2

Piec    Whit Ka3 Ra8

Blac Kb1

Opti    Move Try Set Vari

Endp

In the future the minimum length of unique shortages changes, when popeyes

capabilities are increased. But we try to keep all keywords uniq within the

first four characters. If they are now uniq with less than four, its not

guaranteed for the future.

If there are more problems to be solved in one run, you can replace the

`EndProblem' directive with `NextProblem'. After this, popeye expects

an new problem specification, after he has solved the previous one.

The last problem specification should be finished with `EndProblem'.

Special things depending on your operating system:

UNIX, SINIX, XENIX, ULTRIX, MUNIX, SUNOS, SOLARIS, AIX, HPUX, IRIX, LINUX:

1) Maximum depth of calculation:        999 half-moves.

2) Solving can be interrupted anytime with the CTRL-C key.

Windows-95/-98, Windows-NT/-2000:

MS-DOS (32 Bit), DR-DOS (32 Bit):

1) Maximum depth of calculation:        699 half-moves.

2) Solving can be interrupted anytime with the CTRL-C key.

VMS, MVS, ATARI, macintosh:

will EVENTUALLY be supported by:

VMS:       Torsten Linss

MVS:       Harald Denker

ATARI:     Harald Denker

macintosh: Stefan Brunzen

MS-DOS (16 Bit), DR-DOS (16 Bit):

No support any more ...

BS2000:

No support any more ...

OS/2:

No support any more ...

Elmar Bartel, Norbert Geissler, Torsten Linss, Stephen Emmerson    may 2001

If you have any suggestions, any errors you know of, etc., you are

welcome to contact us.

You will find our address in the files  history  or readme  .