Merge pull request #144 from axelboc/readme

Restructure README and show samples of cloze-style templates

README.md

@@ -3,46 +3,136 @@
 **Geography flashcard deck for [Anki](http://ankisrs.net/)** featuring:
 
 - the world's **[206 sovereign states](https://en.wikipedia.org/wiki/List_of_sovereign_states)** (824 cards)
-- **67 overseas territories** and dependent areas (224 cards)
+- **67 overseas territories** and dependent areas (225 cards)
 - **39 oceans and seas** (39 cards, maps only)
 - **7 continents** (7 cards, maps only)
-- for a total of **319 unique notes**, **1094 cards**, **260 flags** and **317 maps**.
-
-| Flag - Country | Map - Country |
-| --- | --- |
-| ![sample-3](https://cloud.githubusercontent.com/assets/2936402/21575808/3ac74916-cf6e-11e6-8857-1cd7aaa02b23.png) | ![sample-4](https://cloud.githubusercontent.com/assets/2936402/22322663/bd0552aa-e3f1-11e6-89d9-38b5a1048eff.png) |
-
-| Country - Capital | Capital - Country |
-| --- | --- |
-| ![sample-1](https://cloud.githubusercontent.com/assets/2936402/21575807/3ac6ebec-cf6e-11e6-849a-19544d5dccf5.png) | ![sample-2](https://cloud.githubusercontent.com/assets/2936402/21575809/3ac77b7a-cf6e-11e6-8d72-76f4d3e21de8.png) |
-
-The deck is available in **English** and **German**. An **extended version** is also available in both languages with the following additional note templates: _Country - Flag_ and _Country - Map_. Use Anki's [filtered deck feature](#custom-study) to study only a specific type of cards (e.g. map to country) or area of the world (e.g. Europe).
-
-The flags and most of the maps are sourced from [Wikimedia Commons](https://commons.wikimedia.org/). They are provided as SVG or PNG and optimised for smaller file size. Some legacy JPEG maps from the original deck (cf. [Background](#background) section below) are still present, but are [marked for replacement](https://github.com/axelboc/anki-ultimate-geography/issues/1#issuecomment-275280721).
-
-To help with memorisation and provide context while learning, most notes include **extra information**:
-- similar flags - e.g. Iceland = _Norway (red background, blue cross)_
-- governance information - e.g. Cayman Islands = _Overseas territory of the United Kingdom_
-- alternative or former country names - e.g. East Timor = _Also known as Timer-Leste_
-- additional capitals (executive or de facto only - e.g. Sucre, Bolivia = _While Sucre is the constitutional capital, La Paz is the seat of government._
-- statehood information - e.g. Transnistria = _Independent state claimed by Moldova_.
+- for a total of **319 unique notes**, **1095 cards**, **260 flags** and **318 maps**.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Features](#features)
+- [Getting started](#getting-started)
+- [Upgrading](#upgrading)
+- [Background](#background)
+- [Deck structure](#deck-structure)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+---
+
+## Features
+
+### Note templates
+
+<table>
+  <tr><th scope="col" colspan="2">Country - Capital</th></tr>
+  <tr><th scope="col">Front</th><th scope="col">Back</th></tr>
+  <tr>
+    <td><img src="doc/Country - Capital -- Front -- Sri Lanka.png"></td>
+    <td><img src="doc/Country - Capital -- Back -- Sri Lanka.png"></td>
+  </tr>
+</table>
+
+<table>
+  <tr><th scope="col" colspan="2">Capital - Country</th></tr>
+  <tr><th scope="col">Front</th><th scope="col">Back</th></tr>
+  <tr>
+    <td><img src="doc/Capital - Country -- Front -- Finland.png"></td>
+    <td><img src="doc/Capital - Country -- Back -- Finland.png"></td>
+  </tr>
+</table>
+
+<table>
+  <tr><th scope="col" colspan="2">Flag - Country</th></tr>
+  <tr><th scope="col">Front</th><th scope="col">Back</th></tr>
+  <tr>
+    <td><img src="doc/Flag - Country -- Front -- Christmas island.png"></td>
+    <td><img src="doc/Flag - Country -- Back -- Christmas island.png"></td>
+  </tr>
+</table>
+
+<table>
+  <tr><th scope="col" colspan="2">Map - Country</th></tr>
+  <tr><th scope="col">Front</th><th scope="col">Back</th></tr>
+  <tr>
+    <td><img src="doc/Map - Country -- Front -- Mexico.png"></td>
+    <td><img src="doc/Map - Country -- Back -- Mexico.png"></td>
+  </tr>
+</table>
+
+### Supplementary information
+
+To help with memorisation and provide context while learning, most notes include extra information:
+
+- **similar flags** - e.g. Iceland = _Norway (red background, blue cross)_
+- **governance information** - e.g. Cayman Islands = _Overseas territory of the United Kingdom_
+- **alternative and former country names** - e.g. East Timor = _Also known as Timer-Leste_
+- **additional capitals** - e.g. Sucre, Bolivia = _While Sucre is the constitutional capital, La Paz is the seat of government._
+- **statehood information** - e.g. Transnistria = _Independent state claimed by Moldova_.
+
+### Translations
+
+The deck is available in **German**.
+
+<table>
+  <tr><th scope="col" colspan="2">German</th></tr>
+  <tr><th scope="col">Front</th><th scope="col">Back</th></tr>
+  <tr>
+    <td><img alt="" src="doc/DE -- Capital - Country -- Front -- Cayman Islands.png"></td>
+    <td><img alt="" src="doc/DE -- Capital - Country -- Back -- Cayman Islands.png"></td>
+  </tr>
+</table>
+
+### Extended deck
+
+The extended version of the deck comes with two additional note templates: _Country - Flag_ and _Country - Map_.
+
+<table>
+  <tr><th scope="col" colspan="2">Country - Flag</th></tr>
+  <tr><th scope="col">Front</th><th scope="col">Back</th></tr>
+  <tr>
+    <td><img alt="" src="doc/EX -- Country - Flag -- Front -- Abkhazia.png"></td>
+    <td><img alt="" src="doc/EX -- Country - Flag -- Back -- Abkhazia.png"></td>
+  </tr>
+</table>
+
+<table>
+  <tr><th scope="col" colspan="2">Country - Map</th></tr>
+  <tr><th scope="col">Front</th><th scope="col">Back</th></tr>
+  <tr>
+    <td><img alt="" src="doc/EX -- Country - Map -- Front -- Guadeloupe.png"></td>
+    <td><img alt="" src="doc/EX -- Country - Map -- Back -- Guadeloupe.png"></td>
+  </tr>
+</table>
+
+### Custom study
+
+Anki's [search feature](http://ankisrs.net/docs/manual.html#searching), coupled with the deck's comprehensive tag structure, allows for the creation of [filtered decks](https://apps.ankiweb.net/docs/manual.html#creating-manually) covering a wide range of learning goals and abilities. Here are some search queries you can use:
+
+- `card:"Flag - Country"` to learn flags and nothing else;
+- `tag:UG::Sovereign_State` to focus on soverign states and exclude dependent territories, water bodies and continents;
+- `-tag:"Oceans+Seas"` (with "`-`" in front of the filter) to learn everything except oceans, seas and other water bodies;
+- `card:"Map - Country" tag:UG::Sovereign_State tag:UG::Europe` to learn the location of Europe's sovereign states;
+- `(card:"Country - Capital" or card:"Capital - Country") tag:UG::Sovereign_State` to learn the capitals of the world's sovereign states.
 
 
 ## Getting started
 
-First-time here? Welcome! If you're happy using the English version of the deck, here is how you can get started:
+First-time here? Welcome! If you're happy using the standard, English version of the deck, here is how to get started:
 
 1. Go to the **[_Releases_ page](https://github.com/axelboc/anki-ultimate-geography/releases)** and find the latest release.
-1. In the release's _Downloads_ section, find the Anki package `Ultimate_Geography_v[...]_EN.apkg` and download it.
+1. In the _Downloads_ section, find the Anki package `Ultimate_Geography_v[...]_EN.apkg` and download it.
 1. Import it in Anki, synchronise your devices and you're good to go!
 
-> You can also download the latest package from the [shared deck page]( https://ankiweb.net/shared/info/2109889812).
+> You can also download the latest Anki package from the [shared deck page]( https://ankiweb.net/shared/info/2109889812).
 
 ### Other languages and versions
 
-The English deck is the only version available as an Anki package. If you'd like to use the German deck or the extended version of the deck in any language, first install the [CrowdAnki add-on](https://github.com/Stvad/CrowdAnki) then follow the steps below.
+The standard English deck is the only version available as an Anki package. If you'd like to use the standard deck in another language, or the extended deck in any language, first install the [CrowdAnki add-on](https://github.com/Stvad/CrowdAnki) then follow the steps below.
 
-> Please note that importing an extended deck on top of a standard deck is not supported. You must either remove the standard deck first (by following the instructions in the [_Major version_](#major-version) section), or import the extended deck in a separate Anki profile.
+> Please note that importing an extended deck on top of a standard deck is not recommended. You should either remove the standard deck first (by following the instructions in the [_Major version_](#major-version) section), or import the extended deck in a separate Anki profile.
 
 1. Go to the [_Releases_ page](https://github.com/axelboc/anki-ultimate-geography/releases) and find the latest release.
 1. In the release's _Downloads_ section, find the ZIP archive of the version you're interested in using (e.g. `Ultimate_Geography_v[...]_DE.zip` for the standard German deck) and download it.
@@ -83,34 +173,22 @@ Upgrading to a major version (e.g. from 2.6 to 3.0) typically leads to a loss of
 
 ## Background
 
-This deck is built on top of an old [shared deck](https://ankiweb.net/shared/info/261823898) that is no longer maintained. Initially, the goal was to address the poor quality of the flag images. However, the scope of the work quickly increased to include putting the deck on GitHub, rethinking the tags and reviewing the whole content. For a full list of changes, check out the [initial release notes](https://github.com/axelboc/anki-ultimate-geography/releases/tag/v2.0).
+This deck is built on top of an old [shared deck](https://ankiweb.net/shared/info/261823898) that is no longer maintained. Initially, the goal was to address the poor quality of the flag images. However, the scope of the work quickly increased to include putting the deck on GitHub, rethinking the tags, cleaning up the notes to remove all HTML markup, and reviewing the whole content. For a full list of changes, check out the [initial release notes](https://github.com/axelboc/anki-ultimate-geography/releases/tag/v2.0).
 
 > This deck was initially released as `v2.0` to distinguish it from its predecessor, which was commonly referred to as `v1.0` (cf. [_Versioning_](CONTRIBUTING.md#versioning) section.)
 
-
 ## Deck structure
 
-> Please beware that changing the structure of the deck may **prevent you from upgrading it**.
+> Please beware that changing the structure of the deck may **prevent you from upgrading it** without losing your progress.
 
 The notes are based on a **note type** called _Ultimate Geography_, which defines **eight fields**: _Country_, _Country info_, _Capital_, _Capital info_, _Capital hint_, _Flag_, _Flag similarity_ and _Map_.
 
-The cards are generated by Anki based on **four templates**: _Country - Capital_, _Capital - Country_, _Flag - Country_ and _Map - Country_. The extended version of the deck includes two additional templates: _Country - Flag_ and _Country - Map_.
+The cards are generated by Anki on import based on **four templates**: _Country - Capital_, _Capital - Country_, _Flag - Country_ and _Map - Country_. The extended version of the deck includes two additional templates: _Country - Flag_ and _Country - Map_.
 
-The appearance of the cards is controlled solely with CSS; the content of the notes is free from HTML formatting.
+The appearance of the cards is controlled solely with CSS; the content of the notes is free from HTML markup.
 
-Every note is tagged. The tags, which are listed below, are prefixed with `UG::` so they don't conflict with other decks. The prefix also allows the [Hierarchical Tags](https://ankiweb.net/shared/info/1089921461) add-on to collapse them into a single group in the Anki browser's sidebar.
+Every note is tagged. The tags, which are listed below by category, are prefixed with `UG::` so they don't conflict with other decks. They can be used to create [filtered decks](https://apps.ankiweb.net/docs/manual.html#creating-manually) for [custom study](#custom-study).
 
 - Type - `UG::Sovereign_State`, `UG::Oceans+Seas`, `UG::Continents`
 - Continent - `UG::Africa`, `UG::America`, `UG::Asia`, `UG::Europe`, `UG::Oceania`
-- Region - `UG::North+Central_America`, `UG::South_America`, `UG::Caribbean`, `UG::Middle_East`, `UG::Southeast_Asia`, `UG::European_Union`
-
-
-## Custom study
-
-Anki's [search feature](http://ankisrs.net/docs/manual.html#searching), coupled with the deck's comprehensive tag structure, allows for the creation of [filtered decks](https://apps.ankiweb.net/docs/manual.html#creating-manually) covering a wide range of learning goals and abilities. For instance, you can:
-
-- use the `card` filter to focus your study on a specific note template - e.g. `card:"Flag - Country"`;
-- use the `tag` filter to focus your study on a specific continent or region of the world - e.g. `tag:"UG::Africa"`;
-- use `tag:"Sovereign_State"` to include only sovereign states and exclude many of the Caribbean and Pacific islands;
-- use `-tag:"Oceans+Seas"` if you're not interested in learning oceans and seas;
-- combine the filters above to create more targetted or more generic decks.
+- Region - `UG::North+Central_America`, `UG::South_America`, `UG::Caribbean`, `UG::Middle_East`, `UG::Southeast_Asia`, `UG::European_Union`, `UG::Mediterranean`