Documentation
BbnOrganiser 1.7
Introduction
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.
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:
- 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.
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:
- 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.
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.
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.
- 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.
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). |
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:
- 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.
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’. |
|
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 Double. |
|
rdb |
Select Redouble. |
|
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.