Documentation BbnOrganiser 1.10

Introduction

BbnOrganiser is a program for processing a bridge bidding system. Its main features are:


Bridge Bidding Notation

An edited bidding system is saved in a file with default extension bbn. The letters bbn are the abbreviation of : Bridge Bidding Notation. The layout of this notation is based on XML. The precise definition of BBN is defined in an XML Schema called bbn.xsd .


A bidding system consists of the following types of Objects: Configuration, Macro, Chapter, Header, Text, Footer, Call, Description, Meaning, Condition. The 3 top level structures of a BBN file, reflecting a bidding system, are:


The Configuration contains general settings for the whole bidding system.

The Macros structure is optional and contains one or more Macros. Each Macro consists of a name and one or more Meanings. A Meaning specifies (part of) the meaning of a Call.

The Chapters structure is optional and contains one or more Chapters. A Chapter is a complex structure. It contains either sub-Chapters, also named child Chapters, or it contains Calls. So, only at the lowest level a Chapter can have Calls. Each Call has a Description and one or more Meanings.

A Meaning consists of one or more Conditions. There are many Conditions defined, such as High Card Points, Distribution, Controls, etc. Some (combinations of) Conditions may become complex or difficult to read. Macros are then handsome to replace such Conditions.

A Call can be followed by one or more Calls of the next bidder. Such subsequent Calls are named child Calls.


User Interface

The user interface consists of the screen, the menu bar, popup menus, and dialog windows.


Screen

The screen consists of 3 horizontal sections, related to the above mentioned top level structures of a BBN file.

The information about these structures is shown in rectangles, named cells. You can select a cell by pointing to it with the mouse and clicking the left mouse button. A selected cell will get a grey background. Selecting a cell is important since many operations happen with reference to the Object corresponding with the selected cell. In general, a dialog window pops up when you double click a cell. The contents of the dialog window depends on the Object of the selected cell.

Pressing the shift key or the ctrl key when selecting a cell changes the scope of the selection. If you press the ctrl key, then the selected Object is expanded to a higher level as follows:


Object

Expanded selection, ctrl key pressed

Call

Call + Description + Meanings

Footer

Chapter

Text

Chapter

Description

Call + Description + Meanings

Condition

Meaning


If you press the shift key, then all the child Objects are included in the selection as follows:


Object

Expanded selection, shift key pressed

Macro

Macro + Meanings

Chapter

Chapter + expanded Calls + child Chapters

Call

Call + Description + Meanings + child Calls


Configuration

This section consists of a single row at the top of the screen. It shows the filename of the file where the bidding system is stored. If the bidding system has not been stored yet then the text <<no name>> is shown. A marker (*) behind the filename indicates a change in the bidding system, e.g. due to edit operations.


Macros

The section of the Macros is optional. The section is invisible when no Macros have been defined. Otherwise, the section is subdivided in 2 vertical sections. The left section contains the names of Macros; the right section contains one or more Meanings for each Macro. The name of a Macro is used for identification, that can be used by the invoke Condition. When applying this Condition with the Macro’s name, it means that at that place the Macro’s Meaning(s) must be substituted.


Chapters

The section of the Chapters is optional, although it will be present most times. The section is invisible when no Chapters have been defined. The hierarchy of Chapters results in an equivalent hierarchy of sections.

Each Chapter contains the following optional elements:

Each of the above elements results in a sub-section of the Chapter section.

The top row of a Chapter section shows an automatically allocated Chapter number followed by the text of the Header. Before the Chapter number, a ‘+’ indicates that the Chapter will be fully shown. A ‘-‘ indicator results in showing only the top row of the Chapter section.

If a Text element is available, then the first line of the Text is shown in the next row. Only a single line is shown to save screen.

If a Footer element is available, then the text of the Footer is shown in a row after all the child Chapters or Calls.

The sub-section containing Calls is subdivided in 3 vertical sections. The left section contains the actual Calls; the middle section gives a Description of a Call; and the right section specifies the Meanings of a Call.


Calls

The Calls are shown in a grid of columns and rows. The possible Calls of a bidder are shown below each other in the same column. A Call can be followed by one or more Calls of the next bidder. Such subsequent Calls are named ‘child’ Calls. The first child Call is shown in the next column, and in the next row below its parent Call.

Sequences of Calls can become very large so that many columns are needed. For improving readability, a summary of Calls can be given. Summarised Calls consume only 2 columns for an uncontested auction, and 4 columns for a contested auction.


Description

The Description of a Call is shown in the same row as that Call. It indicates whether a Call is conventional, forcing, etc.


Meaning

A Call can have several Meanings. The first Meaning is shown in the same row as the Call; each next Meaning is shown in the next row. A Meaning consists of one or more Conditions. There are many Conditions defined, such as High Card Points, Distribution, Control, etc. Some (combinations of) Conditions may become very complex. Macro definitions are then handsome to replace such Conditions.

If there are at least 2 Meanings for a Call, then these Meanings have a logical OR relationship. So, the Call is such that Meaning-1 is true OR Meaning-2 is true. (In exceptional cases, even both might be true.)


Condition

The following Conditions have been defined.


Condition type

Description

vulnerable

Vulnerability

hcp

High Card Points

distribution

Card distribution

set

Number and suit of cards

tricks

Number of tricks

losers

Number of losers

covercards

Number of covercards

aces

Number of aces

kings

Number of kings

keycards

Number of keycards

controlcounts

Number of controlcounts

stopper

Stopper in a suit

control

Control in a suit

trump

Trump fixation

invoke

Substitute a Macro definition

general

Textual description of a Condition


All above Conditions, except for general, can be interpreted programmatically. The Condition general has been added to enable a human understandable condition. Optionally, it can just be used for a remark.


The Conditions can be entered in any order. However, when storing the bidding system to a BBN file, the types of the Conditions will be sorted in the order given by the above table.


Two artificial Conditions have been defined to ease the use of the bidding system:


brackets

Changes the AND/OR logic of the Conditions inside the brackets

goto

Goto a Chapter for further child Calls


The following rule holds for the interpretation of Conditions :

Conditions within a Meaning have a logical AND relationship.


So, a Meaning is true if all Conditions are true. Conditions with an OR relationship can be realised at the expense of additional Meanings. The brackets Condition has been introduced to prevent copying a whole Meaning except for a certain Condition. The brackets can be applied recursively.


menu bar

The menu items of the menu bar have the following meaning:


File

Main operations.

New

Begin with a new bidding system.

Open

Load a bidding system from a BBN file.

Save

Save the bidding system to the current BBN file

SaveAs

Save the bidding system to another BBN file.

Recent

Open one of the most recent BBN files.

Import

Include a BBN file in the bidding system. The Chapters are added just after the current Chapter. The Macros are appended to the current Macros.

Export

Generate a text file from the bidding system.

Print

Print the screen representation of the bidding system.

Exit

Stop the program.


Edit

Edit operations.

Undo

Undo the last edit operation. The latest 10 operations can be undone.

Redo

Redo an undone edit operation.

Cut

Put the current Object to the clipboard, and remove that Object.

Copy

Put the current Object to the clipboard.

Replace

Replace the current Object with the Object in the clipboard. This operation is only possible when the 2 involved Objects are compatible.

Paste Before

Paste the Object in the clipboard before the current Object.

Paste After

Paste the Object in the clipboard after the current Object.

Paste Child

Paste the Object in the clipboard as a child of the current Object. This operation is only possible wen the involved Objects are Chapters or Calls.

Show

Show the current Chapter.

Hide

Hide the current Chapter.

Find

Find a text in the document.

FindNext

Find a next instance of the text.


Insert

Insert an Object, that is placed relative to the current Object, or relative inside its section.

Macro

Insert a new Macro.

Chapter

Insert a new Chapter.

Call

Insert a new Call.

Meaning

Insert a new Meaning.

Condition

Insert a new Condition of the selected type.


Tools

Tools menu.

Probability

Compute probabilities of hand distributions.


Extra

Miscellaneous operations.

About

Program information.

Settings

Edit program settings.

Register

Enter Registration information.

UserInfo

Show information about a registered user.


popup menus

Popup menus appear when pressing the right mouse button, for the following selected Objects: Macro, Chapter, Call, Meaning, Condition. The possible actions in a popup menu depend on the type of the current Object. The actions are similar to the actions in the menu bar.


Menu windows

The following windows activated from the menu need further explanation.


Find

This window popups when selecting the Edit / Find menu item.



Probability

The following tools window popups when selecting the Tools / Probability menu item.


At each side you can specify the minimum and maximum number of cards for each suit. It is important to indicate which (ranges of) cards are known and which cards are unknown. Mark the checkbox(es) below the “?” for indicating the unknown cards. The probability of the distribution of these unknown cards is computed relative to the known cards. (In fact, the conditional probability of the unknown cards is computed given the known cards.) To speed up computations, leave the Min/Max of irrelevant cards to 0 and 13. In the example above, North has 4 spades and 6 hearts; the probability of a fit in spades is only approximately one third. The upper text field shows this probability in percentages. The lower text field can be used as an additional memory location.

For unregistered users, the West hand and East hand can not be edited.


Field

Description

Compute

Compute the probability.

Reset

Reset the Min/Max fields, and clear the computed probability.

Clear

Clear the memory probability.

+

Add the computed probability to the memory probability.

-

Subtract the computed probability from the memory probability

Exit

Close the window (or use Escape key).


Settings

The following settings window popups when selecting the Extra / Settings menu item.




Field

Description

Properties file

Select the properties file according to your language.

Export Html

Select the maximum number of characters per line of Text areas at File / Export / Html action. The default value is 80. Wrapping is word based. No wrapping happens if the checkbox is unchecked.

Export Text

Select the maximum number of characters per line of Text areas at File / Export / Text action. The default value is 80. Wrapping is word based. No wrapping happens if the checkbox is unchecked.


Dialog windows

Dialog windows popup when a cell has been double clicked. The type of window depends on the cell’s Object. The dialog windows have several features in common:


Configuration

This window popups when double clicking the Configuration cell.


Field

Description

Nr columns uncontested

Number of columns before wrapping of summary Calls happens to the first column, for uncontested auction. The default value is 2.

Nr columns contested

Number of columns before wrapping of summary Calls happens to the first column, for contested auction. The default value is 4.


Chapter

This window popups when double clicking the Chapter cell.


Field

Description

Header

Short description of the Chapter. This text is shown on the screen.

Text

Extensive description of the Chapter. Only the first line of this text is shown on the screen. The complete text is shown in an exported file.

Footer

Concluding description of the Chapter.

Chapter attributes


Id

Identification of the Chapter. The Identification text is used for referring to this Chapter in Condition “Goto”. If the Chapter has no Header value, then this text is shown as the Chapter’s header.

Contested

Select contested (‘yes’) or uncontested (‘no’) auction. The number of columns before wrapping, as determined in the Configuration, is based on this choice. The default value is ‘no’.

Nr columns

The number of columns before wrapping. This value overrules the value determined by the Contested field.

Open

Select if the Chapter is shown (‘yes’) or hidden (‘no’). The default value is ‘yes’.


Text

This window popups when double clicking the Text cell.


Field

Description

Text area

Extensive description of the Chapter.


Call

This window popups when double clicking the Call cell. The Call dialog has 3 main tabs, that will each be described below.


Field

Description

Call attributes


Id

Identification of the Call. The Identification text is used for referring to this Call in Condition “Goto”.

Who

Select who made the Call, either ‘us’ or ‘them’. The default value is ‘us’.
Calls of ‘them’ will be shown between rectangular brackets (or user chosen delimiters).

Summary

Select that the Call is a summary of a bidding sequence. The default value is ‘no’.
Summary Calls will be shown in the same row, or at the next row after exceeding the selected number of columns.

Bid attributes


Bid-Id

Identification of the Bid. The Identification text is used for referring to this Bid in Conditions “Set”, “Stopper”, “Control”, “Trump”.

Show

Select the acronym to be shown on the screen instead of the selected bids. The acronym consists of a number and a letter. This attribute is recommended when many bids have been selected, since in that case the fixed size cell would be exceeded.

Tab CallValue


Select a bid. More than 1 bid can be selected.

pass

Select Pass.

dbl

Select Doublet.

rdb

Select Redoublet.

any

This satisfies any Call.

void

Enables an empty row, meant for layout purpose.

Tab BidLevelDenom

See below

Tab BidComparison

See below



Field

Description

Tab BidLevelDenom


Level


1 - 7

The level of the call.

lowest

The lowest level based on the current situation.

jump1

Jump of 1 level.

jump2

Jump of 2 levels.

jump3

Jump of 3 levels.

Denom attributes


Id

Identification of the Denomination. The Identification text is used for referring to this Denomination in Conditions “Set”, “Stopper”, “Control”, “Trump”.

Show

Select the name to be shown on the screen instead of the selected denominations.

Tab DenomValue


Select spades. Multiple denominations can be chosen.

Select hearts.

Select diamonds.

Select clubs.

Select no-trumps.

List of Ids

Select from the list an Id of a bid, or a denomination.

Tab Comparison

See below



Field

Description

Tab Comparison


>=

Add a list entry: the intended denomination is greater than or equal to the denomination to be selected. The popup dialog ‘Select denomination’ has the same description as above, see Tab DenomValue. The only difference is that now only a single denomination can be chosen.

<=

Add a list entry : the intended denomination is less than or equal to the denomination to be selected.

>

Add a list entry : the intended denomination is greater than the denomination to be selected.

<

Add a list entry : the intended denomination is less than the denomination to be selected.

!=

Add a list entry : the intended denomination is unequal to the denomination to be selected

==

Add a list entry : the intended denomination is equal to the denomination to be selected.

Edit

Edit a list entry.

Delete

Delete a list entry.

List of entries

Select a list entry for editing or deleting



Field

Description

Tab BidComparison

See above ‘Tab Comparison’. The only difference is that the comparisons refer now to Bids instead of denominations. The popup dialog ‘Select bid’ appears when clicking one of the 6 comparison operators, see below.



Field

Description

Tab BidValue


Select a bid. Only 1 bid can be selected.



Field

Description

Tab LevelDenom

See above ‘Tab BidLevelDenom’. The only difference is that only a single denomination can be selected.


Description

This window popups when double clicking the Description cell.


Field

Description

Text

Textual description.

Forcing

Select the type of forcing. The default value is ‘not’.

Category

Select a predefined category. The default value is ‘natural’.


Vulnerable

This window popups when double clicking a cell with a Vulnerable Condition.


Field

Description

Us

Select vulnerability of us. The default value is ‘no’.

Them

Select vulnerability of them. The default value is ‘no’.


Hcp

This window popups when double clicking a cell with a Hcp Condition.


Field

Description

Number of hcp


Num

Enter exact number of hcp.

Min

Enter minimum number of hcp.

Max

Enter maximum number of hcp.

Ownership


Owner

Select the owner of the Hcp.The default value is ‘me’.

Owns

Select the type of ownership. The default value is ‘owns’.


N.B. The number of hcp is allowed to be a decimal value.


Distribution

This window popups when double clicking a cell with a Distribution Condition.


Field

Description

Ownership

See Hcp

Tab SHDC


Enter number of spades.

Enter number of hearts.

Enter number of diamonds.

Enter number of clubs.

Tab 1234


<<<<>>>>

Enter number of cards of longest suit.

<<>>>

Enter number of cards of one but longest suit.

<<>>

Enter number of cards of one but shortest suit.

<>

Enter number of cards of shortest suit.


The number of cards denoted by ‘x’ means an arbitrary number of cards.


Set

This window popups when double clicking a cell with a Set Condition. The dialog window has 2 main tabs.

The tab CardsSelect is meant to specify the number of cards of a certain suit. Optionally, restrictions can be added concerning the hcps of these cards or the ranks of these cards.

The tab CardsNumber is meant to select specific cards. Optionally, the number of the selected cards can be specified.



Field

Description

Ownership

See Hcp

Number of cards


Num

Enter exact number of cards.

Min

Enter minimum number of cards.

Max

Enter maximum number of cards.

Tab CardsNumber


Suit attributes


Id

Identification of the Suit. The Identification text is used for referring to this Suit in Conditions “Set”, “Stopper”, “Control”, “Trump”.

Show

Select the name to be shown on the screen instead of the selected suits.

Tab SuitValue


Select spades. Multiple suits can be chosen.

Select hearts.

Select diamonds.

Select clubs.

List of Ids

Select from the list an Id of a bid, a denomination, or a suit.

Tab Comparison

See below

Hcp


Num

Enter exact number of hcp within selected cards.

Min

Enter minimum number of hcp within selected cards.

Max

Enter maximum number of hcp within selected cards.

Subset


Num

Enter exact number of ranks within selected ranks.

Min

Enter minimum number of ranks within selected ranks.

Max

Enter maximum number of ranks within selected ranks.

A - 2

Select one or more ranks.

Tab CardsSelect

See below



Field

Description

Tab Comparison


>=

Add a list entry: the intended suit is greater than or equal to the suit to be selected. The popup dialog ‘Select suit’ has the same description as above, see Tab SuitValue. The only difference is that now only a single suit can be chosen.

<=

Add a list entry : the intended suit is less than or equal to the suit to be selected.

>

Add a list entry : the intended suit is greater than the suit to be selected.

<

Add a list entry : the intended suit is less than the suit to be selected.

!=

Add a list entry : the intended suit is unequal to the suit to be selected

==

Add a list entry : the intended suit is equal to the suit to be selected.

Edit

Edit a list entry.

Delete

Delete a list entry.

List of entries

Select a list entry for editing or deleting



Field

Description

Tab CardsSelect


Suit attributes

See Tab CardsNumber

Tab SuitValue

See Tab CardsNumber

Tab Comparison

See Tab CardsNumber

Ranks


A - 2

Select one or more ranks.

Number of ranks


Num

Enter exact number of ranks within selected ranks.

Min

Enter minimum number of ranks within selected ranks.

Max

Enter maximum number of ranks within selected ranks.


Tricks

See Hcp.

N.B. The number of tricks is allowed to be a decimal value.


Losers

See Hcp.

N.B. The number of losers is allowed to be a decimal value.


Covercards

See Hcp.

N.B. The number of covercards is allowed to be a decimal value.


Aces

This window popups when double clicking a cell with an Aces Condition.


Field

Description

Total

Enter total number of aces. The default value is 4. To be used when king(s) count as an ace.

Number of aces


Num

Enter exact number of aces.

Min

Enter minimum number of aces.

Max

Enter maximum number of aces.

Ownership


Owner

Select the owner of the aces. The default value is ‘me’.

Owns

Select the type of ownership. The default value is ‘owns’.


N.B. The number of aces is an integer value.


Kings

See Aces.

N.B. The number of kings is an integer value.


Keycards

See Hcp.

N.B. The number of keycards is an integer value.


Controlcounts

See Hcp.

An ace counts as 2 controls, and a king counts as 1 control.

N.B. The number of controlcounts is an integer value.


Stopper

This window popups when double clicking a cell with a Stopper Condition.


Field

Description

Select a stopper in spades. Only a single suit can be chosen.

Select a stopper in hearts.

Select a stopper in diamonds.

Select a stopper in clubs.

List of Ids

Select a stopper from the list, being an Id of a bid, a denomination, or a suit.

Ownership


Owner

Select the owner of the stopper. The default value is ‘me’.

Owns

Select the type of ownership. The default value is ‘owns’.


Control

This window popups when double clicking a cell with a Control Condition.


Field

Description

Type

Select the type of the control. The default value is ‘mixed’.

Select a control in spades. Only a single suit can be chosen.

Select a control in hearts.

Select a control in diamonds.

Select a control in clubs.

List of Ids

Select a control from the list, being an Id of a bid, a denomination, or a suit.

Ownership


Owner

Select the owner of the control. The default value is ‘me’.

Owns

Select the type of ownership. The default value is ‘owns’.


Trump

This window popups when double clicking a cell with a Trump Condition.


Field

Description

Select spades as trump. Only a single suit can be chosen.

Select hearts as trump

Select diamonds as trump

Select clubs as trump

List of Ids

Select the trump from the list, being an Id of a bid, a denomination, or a suit.


Brackets

This window popups when double clicking a cell with a Brackets Condition.


Field

Description

Relation

Select an ‘AND’ or an ‘OR’ relationship between Conditions. The default value is ‘AND’.

Positive

Select whether the Conditions between the brackets are satisfied ‘yes’ or denied ‘no’. The default value is ‘yes’.


Invoke

This window popups when double clicking a cell with an Invoke Condition.


Field

Description

List of Ids

Select the Macro from the list, that must be invoked.


Goto

This window popups when double clicking a cell with a Goto Condition.


Field

Description

List of Ids

Select the Call or Chapter from the list, where the bidding continues.


General

This window popups when double clicking a cell with a General Condition.


Field

Description

Text field

Enter a textual description for the Condition.


Localisation

The texts of the program’s user interface are in English. The exported, generated output can be localised to your favorite language. This can be realised by selecting a suitable Properties file. Default, the BbnOrganiser has a Properties file for the English language. The page download contains Properties files for other languages.

A Properties file is an ASCII file containing property lines. Each line consists of a keyword and a value string.