* markdownization of documentation

4 files changed, 41 insertions, 7 deletions

diff --git a/doc/races.txt b/doc/races.md
index 2ca20da..e1966d2 100644
--- a/doc/races.txt
+++ b/doc/races.md
@@ -1,5 +1,8 @@
-== Race selection ==
+Race selection
+==============
+
 Races included in the standings:
+
  * all World Championship of Drivers races run to Formula One regulations (so no Indianapolis 500 in the 50s) from 1950 to 1980
  * all World Championship of Drivers races run to Formula Two regulations in 1952-53
  * all Formula One World Championship races since 1981
@@ -9,14 +12,17 @@ Races included in the standings:
  * races with mixed formula entries (e.g. F1/F2 or F1/FLibre) are separated by class and only F1 class (and F2 class in 1952-53) is scored, apart from joined F1-F2 World Championship races (German Grands Prix from 50s and 60s and 1958 Moroccan GP)
 
 Race importance factor:
+
  * WCoD and FOWC race importance constitutes 100% of base value
  * all other races get 50% of base value
  * qualifying sessions get 10% of the value for respective race
  * all races of the same category are scored identically, even if the race has been red-flagged before what would be full points situation
 
 Heats and aggregates:
+
  * for multi-heat races with bracket-style heats and a final heats count as qualifying sessions and the final count as a race (except for Bologna Sprints, in which every heat from the full bracket get qualifying importance)
  * for multi-heat races with aggregate-style standings the initial grid counts as qualifying and the aggregate results count as a race
 
 Other remarks:
+
  * all qualifying sessions are listed as held on the previous day relative to the race - simply to avoid chronology mix-ups and to minimize the chances of two ratings for a driver for one day
diff --git a/doc/results.txt b/doc/results.md
index 43dda5b..d819ac2 100644
--- a/doc/results.txt
+++ b/doc/results.md
@@ -1,9 +1,12 @@
-== Scoring rules ==
+Scoring rules
+=============
+
 Every race or ranked qualifying session results for each entry are handed ordinal numbers as "groups" in which the entry was classified.
 
 For qualifying, a group is simply the qualifying position (not applying any carryover/technical grid drop penalties, but applying disqualification/exclusion/grid penalties for offences during the ranked session).
 
 For races the following rules apply:
+
  * race winning entry forms group "1"
  * among the drivers classified on the lead lap, other groups are as follows: 2-3 places are group "2", 4-5 places are group "3", 6-10 places are group "4", 11-15 places are group "5", etc.
  * for drivers classified outside the lead lap, the groups are formed by the drivers classified with the same numbers of completed laps (each distinct lap number as a separate group)
@@ -17,6 +20,7 @@ After separating session results into groups, all entries from non-"0" groups fo
 All such duels are then treated as input for Elo rating algorithm.
 
 Specific rules regarding Elo implementation for this application's purposes:
+
  * rankings are applied (evaluated) after each session (note: debug information for Bologna Sprints does not display correct "previous" ratings: ratings are applied after each heat, yeat debug info displays inital rating from before the event; this applies to any possible situation in which drivers take part in multiple sessions in one day)
  * no minimum rating limit for driver is enforced
  * drivers are rated from their first entry (there's no initial grace period, see: challenges.txt)
@@ -24,16 +28,19 @@ Specific rules regarding Elo implementation for this application's purposes:
  * driver group disparity is varied to accommodate for dynamic shifts of relative performance within the F1 field (caused by technical changes) - see below
 
 Other than that, standard Elo rating conventions apply:
+
  * drivers start with identical initial rating
  * duels between high-ranked drivers change their rankings by fewer points than duels between low-ranked drivers
 
 Field disparity change:
+
  * higher disparity leads to more rating inflation - as disparity is a measure of rating difference that yields a certian probability of driver's victory, so higher disparity leads to more attribution for a victory to a driver (and less attribution to the shift of performance, e.g. car performance change)
  * higher rating deviation in the months prior to a race suggests a shift in relative performance (some drivers gain a lot, some divers lose a lot), so there's a need for damping further changes a bit - by lowering disparity
  * once the ratings are stabilized (meaning relative performance within the field had settled), disparity can be increased
  * this helps with the initial "rolling start" phase of the ranking (1946-1949 races)
 
 Specific parameters which are configurable:
+
  * initial driver ranking
  * initial disparity factor (ranking difference which drops the possibility of lower-ranked driver's win by the factor of 10)
  * duel importance (base, i.e. for drivers ranked below importance thresholds) for all race types
diff --git a/doc/sources.txt b/doc/sources.md
index ee10bcd..a9512d9 100644
--- a/doc/sources.txt
+++ b/doc/sources.md
@@ -1,8 +1,20 @@
+Data sources:
+=============
+
 Championship races:
+-------------------
+
 1950-1951 - wikipedia
 1952-1953 - second-a-lap.blogspot.com
 1954+ - ergast.com/mrd
 
 Non-championship races:
+-----------------------
 1950+ - www.silhouet.com/motorsport/archive/f1
 1952-1953 - second-a-lap.blogspot.com
+1954+ - chicanef1.com
+
+Qualifying:
+-----------
+2003+ - ergast.com/mrd
+1954+ - chicanef1.com
diff --git a/doc/sql.txt b/doc/sql.md
index a21b607..1f4f08b 100644
--- a/doc/sql.txt
+++ b/doc/sql.md
@@ -1,7 +1,9 @@
-Useful queries:
+Useful queries for application database:
+=======================================
 
- - overall top rating progression
+ * overall top rating progression
 
+```
 CREATE OR REPLACE VIEW max_date_rankings AS
        SELECT MAX(ranking) max_ranking,
               rank_date max_rank_date
@@ -18,9 +20,11 @@ WHERE max_ranking > (
       SELECT MAX(mr.max_ranking) FROM max_date_rankings mr
       WHERE mr.max_rank_date < max_date_rankings.max_rank_date
 );
+```
 
- - overall top peak ratings
+ * overall top peak ratings
 
+```
 SELECT drivers.driver,
        rankings.ranking,
        rankings.rank_date
@@ -32,9 +36,11 @@ INNER JOIN (
 JOIN drivers ON rankings._driver = drivers.id
 GROUP BY rankings._driver
 ORDER BY rankings.ranking DESC;
+```
 
- - highest exit ratings
+ * highest exit ratings
 
+```
 SELECT drivers.driver,
        rankings.ranking,
          rankings.rank_date
@@ -45,9 +51,11 @@ INNER JOIN (
 JOIN drivers ON rankings._driver = drivers.id
 WHERE rankings.rank_date < CURDATE() - INTERVAL 1 YEAR
 ORDER BY rankings.ranking DESC;
+```
 
- - year-by-year rating inflation
+ * year-by-year rating inflation
 
+```
 SELECT YEAR(rank_date),
        MAX(ranking),
        MIN(ranking),
@@ -57,3 +65,4 @@ SELECT YEAR(rank_date),
 FROM rankings
 GROUP BY YEAR(rank_date)
 ORDER BY YEAR(rank_date) ASC;
+```