Polish README and LICENSE

2 files changed, 129 insertions, 0 deletions

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..b996b29
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2017, Michał
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.pl.md b/README.pl.md
new file mode 100644
index 0000000..ed0cfe2
--- /dev/null
+++ b/README.pl.md
@@ -0,0 +1,104 @@
+AusButler dla pakietu JFR Teamy
+===============================
+
+Narzędzie umożliwiające obliczanie i prezentację znormalizowanego butlera (tzw. "australijskiego butlera") w turniejach prowadzonych przy użyciu pakietu JFR Teamy.
+
+Instalacja
+----------
+
+1. Ściągnąć paczkę z programem ze strony autora.
+2. Rozpakować paczkę do pożądanego katalogu.
+3. Skonfigurować odpowiednie połączenie z bazą danych.
+4. Wywołać w katalogu programu plik `butler.exe`.
+
+Wywołanie programu
+------------------
+
+Program przyjmuje w linii poleceń, w dowolnej kolejności, szereg argumentów, odpowiadających akcjom wykonywanym przez aplikację:
+
+ * `calculate` przelicza znormalizowanego butlera i wpisuje go do bazy danych
+ * `generate` generuje strony HTML z wszystkimi obecnymi w bazie wynikami znormalizowanego butlera
+ * `send` wysyła je Gońcem do serwera FTP (pod warunkiem wybrania akcji `generate`)
+
+Wywołanie programu bez żadnego z powyższych argumentów jest równoważne podaniu wszystkich argumentów (`calculate`, `generate` i `send`).
+
+Dodatkowo, program domyślnie czeka po wykonaniu na wciśnięcie dowolnego klawisza - opcję tę można wyłączyć, przekazując do programu argument `nowait`.
+
+Pliki konfiguracyjne
+--------------------
+
+Aplikacja korzysta z pięciu plików konfiguracyjnych, formatu JSON, umiejscowionych w podkatalogu `config` katalogu programu.
+
+`db.json`
+
+Określa parametry połączenia z bazą danych turnieju:
+
+ * `user` - nazwę użytkownika
+ * `pass` - hasło użytkownika
+ * `db` - nazwę bazy turnieju
+ * `host` - serwer bazy danych
+
+`butler.json`
+
+Definiuje parametry obliczania butlera znormalizowanego.
+
+Butler dla pary w danym segmencie obliczany jest w następujący sposób:
+
+ * butler danej pary ograniczany jest do wartości `cutoff_point`
+ * 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)
+ * 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`
+
+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.
+
+Każdy tekst powinien znajdować się w tabeli `logoh` bazy danych turnieju.
+
+**UWAGA**: w przypadku wystąpienia w programie błędu `KeyError: ID_TŁUMACZENIA` w liniach wskazujących na pobieranie tłumaczeń, należy do bazy danych turnieju w JFR Teamy wczytać ponownie poprawny plik `.language`.
+
+`translation.json`
+
+Ustawia teksty tłumaczeń, używane w stronach generowanych przez program, a niezawarte domyślnie w bazach turniejów JFR Teamy.
+
+Składa się ze słownika wartości określających polską (`pl`) i angielską (`en`) formę łańcucha tekstowego.
+
+Program wykrywa wersję językową ustawioną w bazie danych turnieju na podstawie obecnego w bazie danych łańcucha o ID 18 (`ROUND` po angielsku, `RUNDA` po polsku).
+
+Szablony stron
+--------------
+
+Katalog `template` zawiera w pełni modyfikowalne szablony stron generowanych przez program.
+
+ * `table.html` to szablon tabeli zbiorczej znormalizowanego butlera - pliku `PREFIXnormbutler.html`
+ * `frame.html` to szablon ramki wyświetlającej wyniki znormalizowanego butlera pojedynczego segmentu - plików `PREFIXbutlerSEGMENT.htm`
+ * `segment.html` to szablon tabeli wyników znormalizowanego butlera dla poszczególnych par w pojedynczym segmencie - plików `PREFIXbutlerSEGMENT.html`
+ * `macros.html` zawiera szablony wstawek używanych w różnych miejscach innych szablonów - nagłówków, separatorów, wierszy tabeli wyników czy stopki stron
+
+W większości przypadków użycia nie ma potrzeby modyfikowania tych szablonów - są one zgodne z formatowaniem JFR Teamy.
+
+Autorzy
+-------
+
+Autorem programu jest Michał Klichowicz (mkl).
+
+Program powstał na potrzeby Polskiego Związku Brydża Sportowego, za namową kapitana reprezentacji Polski open, Piotra Walczaka.
+
+Metoda jest adaptacją znormalizowanego butlera obliczanego w rozgrywkach Australijskiej Federacji Brydżowej, wg opisu z [Mistrzostw Australii 2016](http://www.abfevents.com.au/events/spnot/2016/include/2016_SN_Supp_Regs.pdf).
+
+Licencja
+--------
+
+Aplikacja udostępniana jest na [uproszczonej, 2-punktowej licencji BSD](LICENSE).