English version of the README

3 files changed, 225 insertions, 2 deletions

diff --git a/README.en.md b/README.en.md
new file mode 100644
index 0000000..8c5da0c
--- /dev/null
+++ b/README.en.md
@@ -0,0 +1,109 @@
+AusButler for JFR Teamy suite
+=============================
+
+Tools that allows calculation and presentation of a normalized butler (a so-called "Australian butler") for tournaments directed with JFR Teamy suite.
+
+Installation
+------------
+
+1. Download the program package from author's website.
+2. Unpack it to the desired directory.
+3. Configure appropriate database connection.
+4. Run `butler.exe` in application directory.
+
+Program invocation
+------------------
+
+Program, in any order, accepts command line arguments which relate to actions conducted by the application:
+
+ * `calculate` calculates normalized butler and writes it in the event database
+ * `generate` compiles HTML pages with all results present in the normalized butler database
+ * `send` transmits the pages to the FTP server via Goniec (if `generate` action is selected)
+
+Invoking the application without any of the above arguments is equivalent to providing all of them (`calculate`, `generate` and `send`).
+
+Additionally, the program by default waits for user input after finishing - this may be turned off, by providing `nowait` argument.
+
+Configuration files
+-------------------
+
+The application relies on five configuration files, JSON-formatted, placed in the `config` subdirectory.
+
+`db.json`
+
+Defines event database connection parameters:
+
+ * `user` - DB username
+ * `pass` - DB password
+ * `db` - event database name
+ * `host` - DB server location
+
+`butler.json`
+
+Defines butler calculation parameters.
+
+Normalized butler for the pair in a segment is calculated as follows:
+
+ * raw butler for the pair is limited to the `cutoff_point` value
+ * results above `cutoff_point` are included only partially, as defined per `cutoff_rate` (e.g., by default: `32` and `0.1` mean that 10% of the result above 32 IMP counts)
+ * the result is normalized to IMP per board
+ * average score of the opponents (their raw butler score per board) is added, scaled to the `opponent_factor` parameter (e.g. the default `0.5` means half of the opponents' average is added)
+ * the result is recalculated as a score for the entire segment
+ * if the `only_current` is set, opponents' average is calculated only from segments up to the considered one - so that way normalized butler does not take into account opponents' results from the entire event, but consequent results do not change the calculation for previous segments
+
+All calculations are independent from the way raw butler is calculated for all the pairs.
+
+Finally, the `segments_in_table_limit` parameters defines how many latest segments are presented in detail in the summary table for the normalized butler (`PREFIXnormbutler.html`). All the previous segments are included in the table header, in compliance with JFR Teamy convention.
+
+`goniec.json`
+
+Defines standard parameters for Goniec transmission.
+
+ * `enabled` turns the transmission on
+ * `host` and `port` point to the Goniec location
+
+`logoh.json`
+
+Sets the mapping for text strings used by the application within generated pages to the event database translation identifiers. Typically, doesn't need any adjustments.
+
+Every string should be present in the `logoh` table of the event database.
+
+**BEWARE**: in case the program raises `KeyError: NUMERIC_ID` error in lines responsible for translating strings, you should reload the correct `.language` into the JFR Teamy event database.
+
+`translation.json`
+
+Sets translations for the strings that are generated by the program, but are not present in the JFR Teamy event database.
+
+It consists of a dictionary of values including Polish (`pl`) and English (`en`) variations of the string.
+
+The application detects the language version used in the event database based on the string with ID 18 from the event database (`ROUND` for English, `RUNDA` for Polish).
+
+Page templates
+--------------
+
+The `template` directory contains fully customizable page templates for the files generated by the program.
+
+ * `table.html` is the template for the normalized butler summary table - `PREFIXnormbutler.html` file
+ * `frame.html` is the frame template for the normalized butler resutls of single segments - `PREFIXbutlerSEGMENT.htm` files
+ * `segment.html` is the template for the normalized butler pairs resutls of single segments - `PREFIXbutlerSEGMENT.html` files
+ * `macros.html` contains various partial templates used in multiple places of other templates - stuff like headers, separators, result table rows or page footer
+
+In most cases there's no need to modify these templates - they're compatible with the standard JFR Teamy formatting.
+
+Authors
+-------
+
+The author of the application is Michał Klichowicz (mkl).
+
+This was created for Polish Bridge Union, from the initiative of the Polish Open Team coach, Piotr Walczak.
+
+The method was adopted from the *normalized datum* calculated by the Australian Bridge Federation, according to the [2016 Australian National Championships supplementary regulations](http://www.abfevents.com.au/events/spnot/2016/include/2016_SN_Supp_Regs.pdf).
+
+License
+-------
+
+The application is distributed under a [simplified 2-clause BSD license](LICENSE).
+
+~~~
+
+`Breathe on, little sister, breathe on.`
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8c5da0c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,109 @@
+AusButler for JFR Teamy suite
+=============================
+
+Tools that allows calculation and presentation of a normalized butler (a so-called "Australian butler") for tournaments directed with JFR Teamy suite.
+
+Installation
+------------
+
+1. Download the program package from author's website.
+2. Unpack it to the desired directory.
+3. Configure appropriate database connection.
+4. Run `butler.exe` in application directory.
+
+Program invocation
+------------------
+
+Program, in any order, accepts command line arguments which relate to actions conducted by the application:
+
+ * `calculate` calculates normalized butler and writes it in the event database
+ * `generate` compiles HTML pages with all results present in the normalized butler database
+ * `send` transmits the pages to the FTP server via Goniec (if `generate` action is selected)
+
+Invoking the application without any of the above arguments is equivalent to providing all of them (`calculate`, `generate` and `send`).
+
+Additionally, the program by default waits for user input after finishing - this may be turned off, by providing `nowait` argument.
+
+Configuration files
+-------------------
+
+The application relies on five configuration files, JSON-formatted, placed in the `config` subdirectory.
+
+`db.json`
+
+Defines event database connection parameters:
+
+ * `user` - DB username
+ * `pass` - DB password
+ * `db` - event database name
+ * `host` - DB server location
+
+`butler.json`
+
+Defines butler calculation parameters.
+
+Normalized butler for the pair in a segment is calculated as follows:
+
+ * raw butler for the pair is limited to the `cutoff_point` value
+ * results above `cutoff_point` are included only partially, as defined per `cutoff_rate` (e.g., by default: `32` and `0.1` mean that 10% of the result above 32 IMP counts)
+ * the result is normalized to IMP per board
+ * average score of the opponents (their raw butler score per board) is added, scaled to the `opponent_factor` parameter (e.g. the default `0.5` means half of the opponents' average is added)
+ * the result is recalculated as a score for the entire segment
+ * if the `only_current` is set, opponents' average is calculated only from segments up to the considered one - so that way normalized butler does not take into account opponents' results from the entire event, but consequent results do not change the calculation for previous segments
+
+All calculations are independent from the way raw butler is calculated for all the pairs.
+
+Finally, the `segments_in_table_limit` parameters defines how many latest segments are presented in detail in the summary table for the normalized butler (`PREFIXnormbutler.html`). All the previous segments are included in the table header, in compliance with JFR Teamy convention.
+
+`goniec.json`
+
+Defines standard parameters for Goniec transmission.
+
+ * `enabled` turns the transmission on
+ * `host` and `port` point to the Goniec location
+
+`logoh.json`
+
+Sets the mapping for text strings used by the application within generated pages to the event database translation identifiers. Typically, doesn't need any adjustments.
+
+Every string should be present in the `logoh` table of the event database.
+
+**BEWARE**: in case the program raises `KeyError: NUMERIC_ID` error in lines responsible for translating strings, you should reload the correct `.language` into the JFR Teamy event database.
+
+`translation.json`
+
+Sets translations for the strings that are generated by the program, but are not present in the JFR Teamy event database.
+
+It consists of a dictionary of values including Polish (`pl`) and English (`en`) variations of the string.
+
+The application detects the language version used in the event database based on the string with ID 18 from the event database (`ROUND` for English, `RUNDA` for Polish).
+
+Page templates
+--------------
+
+The `template` directory contains fully customizable page templates for the files generated by the program.
+
+ * `table.html` is the template for the normalized butler summary table - `PREFIXnormbutler.html` file
+ * `frame.html` is the frame template for the normalized butler resutls of single segments - `PREFIXbutlerSEGMENT.htm` files
+ * `segment.html` is the template for the normalized butler pairs resutls of single segments - `PREFIXbutlerSEGMENT.html` files
+ * `macros.html` contains various partial templates used in multiple places of other templates - stuff like headers, separators, result table rows or page footer
+
+In most cases there's no need to modify these templates - they're compatible with the standard JFR Teamy formatting.
+
+Authors
+-------
+
+The author of the application is Michał Klichowicz (mkl).
+
+This was created for Polish Bridge Union, from the initiative of the Polish Open Team coach, Piotr Walczak.
+
+The method was adopted from the *normalized datum* calculated by the Australian Bridge Federation, according to the [2016 Australian National Championships supplementary regulations](http://www.abfevents.com.au/events/spnot/2016/include/2016_SN_Supp_Regs.pdf).
+
+License
+-------
+
+The application is distributed under a [simplified 2-clause BSD license](LICENSE).
+
+~~~
+
+`Breathe on, little sister, breathe on.`
diff --git a/README.pl.md b/README.pl.md
index ed0cfe2..2fa6c8f 100644
--- a/README.pl.md
+++ b/README.pl.md
@@ -48,10 +48,11 @@ Butler dla pary w danym segmencie obliczany jest w następujący sposób:
  * wynik powyżej `cutoff_point` zaliczany jest jedynie w części, określonej przez `cutoff_rate` (np. domyślne: `32` i `0.1` oznacza, że zaliczane jest 10% wyniku powyżej 32 IMP)
  * tak uzyskany wynik przeliczany jest na średnią na rozdanie
  * do niego dodawana jest średnia na rozdanie pary przeciwnej (z butler nieznormalizowanego), przeskalowana o parametr `opponent_factor` (np. domyślne `0.5` oznacza, że dodawana jest połowa średniej na rozdanie przeciwników)
+ * wynik przeliczany jest z powrotem na wartość w całym segmencie
  * jeśli ustawiony jest parametr `only_current`, średnia przeciwników wyliczana jest jedynie z niepóźniejszych segmentów - czyli tak wyliczony butler nie uwzględnia dla pierwszych segmentów średniej przeciwników z całych zawodów, ale wyniki dla wcześniejszych segmentów nie zmieniają się pod wpływem wyników kolejnych segmentów
 
 Wszystkie obliczenia nie zależą od sposobu wyliczania nieznormalizowanego butlera dla wszystkich par.
- 
+
 W końcu, parametr `segments_in_table_limit` określa, ile segmentów najnowszych widocznych jest szczegółowo w zbiorczej tabeli znormalizowanego butlera (`PREFIXnormbutler.html`). Wszystkie wcześniejsze segmenty dołączone są w nagłówku tabeli, zgodnie z konwencją JFR Teamy.
 
 `goniec.json`
@@ -60,7 +61,7 @@ Określa standardowe parametry przesyłania plików Gońcem.
 
  * `enabled` włącza wysyłanie Gońcem
  * `host` i `port` wskazują lokalizację Gońca
- 
+
 `logoh.json`
 
 Ustawia mapowanie łańcuchów tekstowych używanych przez aplikację w generowanych stronach na identyfikatory do pobrania tekstów z bazy danych turnieju. Przeważnie nie wymaga ingerencji.
@@ -102,3 +103,7 @@ Licencja
 --------
 
 Aplikacja udostępniana jest na [uproszczonej, 2-punktowej licencji BSD](LICENSE).
+
+~~~
+
+`Breathe on, little sister, breathe on.`