diff options
author | emkael <emkael@tlen.pl> | 2017-05-09 01:24:32 +0200 |
---|---|---|
committer | emkael <emkael@tlen.pl> | 2017-05-09 02:51:40 +0200 |
commit | a20ce3ae94732af03f600065a7c26588b6a7e2b8 (patch) | |
tree | f9391677ac41b509ce17cc6f1d77e417085cda70 /README.pl.md | |
parent | 9ad496966ab94c37cbf4208ec1fd39257cb60410 (diff) |
Polish README and LICENSE
Diffstat (limited to 'README.pl.md')
-rw-r--r-- | README.pl.md | 104 |
1 files changed, 104 insertions, 0 deletions
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). |