Documentation BbnOrganiser 1.10
BbnOrganiser is a program for processing a bridge bidding system. Its main features are:
Edit the bidding calls and their meanings.
Store the bidding system in a file obeying the Bridge Bidding Notation (BBN).
Import BBN files in the current file.
Generate an ASCII text file by exporting the bidding system.
Compute probabilities of hand distributions.
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:
Configuration
Macros
Chapters
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.
The user interface consists of the screen, the menu bar, popup menus, and dialog windows.
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 |
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.
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.
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:
Header
Text
Chapters or Calls
Footer
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.
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.
The Description of a Call is shown in the same row as that Call. It indicates whether a Call is conventional, forcing, etc.
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.)
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.
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 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 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.
The following windows activated from the menu need further explanation.
This window popups when selecting the Edit / Find menu item.
After inserting the text to find you can press the Enter key one extra time to execute the find function.
The cell with the found text becomes the current cell. If the current cell already contains the text, then the current cell remains unchanged.
You can press F3 to find the next instance of the text.
The option Regular expressions can be used to find text patterns. A summary of regular-expression constructs can be found at e.g. http://www.tistis.nl/bbn/regular_expression.htm .
The most recent texts are saved to the user’s directory, and loaded at the next program start.
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). |
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 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:
Each window has an OK button for accepting the made changes and a CANCEL button for denying the made changes.
Pressing the Enter key has the same function as pressing the OK button (except for the Text Object).
Pressing the Escape key has the same function as pressing the CANCEL button.
Many options are preceeded by a checkbox, that has to be checked before data can be entered. In the screendumps below some checkboxes have been checked to show the options clearly.
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. |
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’. |
This window popups when double clicking the Text cell.
Field |
Description |
Text area |
Extensive description of the Chapter. |
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’. |
Summary |
Select
that the Call is a summary of a bidding sequence. The default
value is ‘no’. |
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. |
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’. |
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’. |
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.
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.
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. |
See Hcp.
N.B. The number of tricks is allowed to be a decimal value.
See Hcp.
N.B. The number of losers is allowed to be a decimal value.
See Hcp.
N.B. The number of covercards is allowed to be a decimal value.
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.
See Aces.
N.B. The number of kings is an integer value.
See Hcp.
N.B. The number of keycards is an integer value.
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.
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’. |
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’. |
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. |
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’. |
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. |
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. |
This window popups when double clicking a cell with a General Condition.
Field |
Description |
Text field |
Enter a textual description for the Condition. |
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.