summaryrefslogtreecommitdiff
path: root/README.pl.md
blob: cfcafae72fe51aa48639b660f56154ff3f9469b7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
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](https://github.com/emkael/jfrteamy-ausbutler/releases).
2. Rozpakować paczkę do pożądanego katalogu.
3. [Skonfigurować odpowiednie połączenie z bazą danych](#pliki-konfiguracyjne).
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`](config/db.json.EXAMPLE)

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`](config/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)
 * 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`](config/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`](config/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`](config/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`](template/table.html) to szablon tabeli zbiorczej znormalizowanego butlera - pliku `PREFIXnormbutler.html`
 * [`frame.html`](template/frame.html) to szablon ramki wyświetlającej wyniki znormalizowanego butlera pojedynczego segmentu - plików `PREFIXbutlerSEGMENT.htm`
 * [`segment.html`](template/segment.html) to szablon tabeli wyników znormalizowanego butlera dla poszczególnych par w pojedynczym segmencie - plików `PREFIXbutlerSEGMENT.html`
 * [`macros.html`](template/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).

---

`Breathe on, little sister, breathe on.`