Documentation update.

CHANGELOG.md

@@ -11,8 +11,8 @@
 ### Detailed list of changes
 
 * Added alternative emulators support where additional emulators can be defined in es_systems.xml and be selected system-wide or per game via the user interface
-* Populated the bundled es_systems.xml files with alternative emulator entries for must RetroArch cores
+* Populated the bundled es_systems.xml files with alternative emulator entries for most RetroArch cores
-* Added a virtual keyboard partly based on code from batocera-emulationstation
+* Added a virtual keyboard, partly based on code from batocera-emulationstation
 * Added the ability to make complementary game system customizations without having to replace the entire bundled es_systems.xml file
 * Added support for an optional \<systemsortname\> tag for es_systems.xml that can be used to override the default \<fullname\> systems sorting
 * Improved the gamelist filter screen to not allow filtering of values where there is no actual data to filter, e.g. Favorites for a system with no favorite games
@@ -20,7 +20,9 @@
 * Added the ability to filter on blank/unknown values for Genre, Player, Developer, Publisher and Alternative emulator.
 * Added a filter for "Alternative emulator" and sorted the filters in the same order as the metadata editor fields
 * Added a menu option to change the application exit key combination
+* Lowered the minimum supported screen resolution from 640x480 to 224x224 to support arcade cabinet displays such as those running at 384x224 and 224x384
 * Expanded the themeable options for "helpsystem" to support custom button graphics, dimmed text and icon colors, upper/lower/camel case and custom spacing
+* Made the scrolling speed of ScrollableContainer more consistent across various screen resolutions and display aspect ratios
 * Added support for using the left and right trigger buttons in the help prompts
 * Removed the "Choose" entry from the help prompts in the gamelist view
 * Changed the "Toggle screensaver" help entry in the system view to simply "Screensaver"
@@ -32,6 +34,7 @@
 * Changed the filter description "Text filter (game name)" to "Game name"
 * Added support for multi-select total count and exclusive multi-select to OptionListComponent
 * Achieved a massive speed improvement for OptionListComponent by not resizing each added MenuComponent row (most notable in the filter GUI)
+* Made multiple optimizations to the GUI components by removing lots of unnecessary function calls for sizing, placement, opacity changes etc.
 * Added support for a new type of "flat style" button to ButtonComponent
 * Added support for correctly navigating arbitrarily sized ComponentGrid entries, i.e. those spanning multiple cells
 * Bundled the bold font version of Fontfabric Akrobat
@@ -39,6 +42,7 @@
 * Replaced all built-in matrix and vector data types and functions with GLM library equivalents
 * Replaced some additional math functions and moved the remaining built-in functions to a math utility namespace
 * Added a function to generate MD5 hashes
+* Made an optimization for SVG graphics to avoid a lot of unnecessary re-rasterizations
 * Moved the "complex" mode functionality from GuiComplexTextEditPopup into GuiTextEditPopup and removed the source files for the former
 * Replaced the String::Utils::trim function with better code and removed some inline text trimming throughout the application
 * Increased the warning level for Clang/LLVM and GCC by adding -Wall, -Wpedantic and some additional flags
@@ -49,10 +53,12 @@
 
 ### Bug fixes
 
-* When multi-scraping in interactive mode with "Auto-accept single game matches" enabled, the game name could not be refined if there were no games found
+* Setting a really small font size in a theme would crash the application
-* When multi-scraping in interactive mode, the game counter was not decreased when skipping games, making it impossible to skip the final games in the queue
+* When scraping in interactive mode with "Auto-accept single game matches" enabled, the game name could not be refined if there were no games found
-* When multi-scraping in interactive mode, "No games found" results could be accepted using the "A" button
+* When scraping in interactive mode, the game counter was not decreased when skipping games, making it impossible to skip the final games in the queue
+* When scraping in interactive mode, "No games found" results could be accepted using the "A" button
 * When scraping in interactive mode, any refining done using the "Y" button shortcut would not be shown when doing another refine using the "Refine search" button
+* Under some circumstances ScrollableContainer (used for the game descriptions) would contain a partially rendered bottom line
 * Removing games from custom collections did not remove their filter index entries
 * Input consisting of only whitespace characters would get accepted by TextEditComponent which led to various strange behaviors
 * Leading and trailing whitespace characters would not get trimmed from the collection name when creating a new custom collection

THEMES-DEV.md

@@ -1,83 +1,90 @@
 # EmulationStation Desktop Edition (ES-DE) v1.2 (development version) - Themes
 
-**Note:** If creating theme sets specifically for ES-DE, please add `-DE` to the theme name, as in `rbsimple-DE`. Because the ES-DE theme support has already deviated somehow from the RetroPie EmulationStation fork and will continue to deviate further in the future, the theme set will likely not be backwards compatible. It would be confusing and annoying for a user that downloads and attempts to use an ES-DE theme set in another EmulationStation fork only to get crashes, error messages or corrupted graphics. At least the -DE extension is a visual indicator that it's an ES-DE specific theme set.
+**Note:** This document is only relevant for the current ES-DE development version, if you would like to see the documentation for the latest stable release, refer to [THEMES.md](THEMES.md) instead.
 
-Also note that this document is only relevant for the current ES-DE development version, if you would like to see the documentation for the latest stable release, refer to [THEMES.md](THEMES.md) instead.
+If creating theme sets specifically for ES-DE, please add `-DE` to the theme name, as in `rbsimple-DE`. Because the ES-DE theme support has already deviated somehow from the RetroPie EmulationStation fork and will continue to deviate further in the future, the theme set will likely not be backwards compatible. It would be confusing and annoying for a user that downloads and attempts to use an ES-DE theme set in another EmulationStation fork only to get crashes, error messages or corrupted graphics. At least the -DE extension is a visual indicator that it's an ES-DE specific theme set.
 
-ES-DE allows each system to have its own "theme." A theme is a collection **views** that define some **elements**, each with their own **properties**.
+Table of contents:
 
-The first place ES-DE will check for a theme is in the system's `<path>` folder, for a theme.xml file:
+[[_TOC_]]
-* `[SYSTEM_PATH]/theme.xml`
 
-If that file doesn't exist, ES-DE will try to find the theme in the current **theme set**.  Theme sets are just a collection of individual system themes arranged in the "themes" folder under some name.  A theme set can provide a default theme that will be used if there is no matching system theme.  Here's an example:
+## Introduction
+
+ES-DE allows the grouping of themes for multiple game systems into a **theme set**. Each theme is a collection of **views** that define some **elements**, each with their own **properties**.
+
+Every game system has its own subdirectory within the theme set directory structure, and these are defined in the systems configuration file `es_systems.xml` either via the optional `<theme>` tag, or otherwise via the mandatory `<name>` tag. When ES-DE populates a system on startup it will look for a file named `theme.xml` in each such directory.
+
+By placing a theme.xml file directly in the root of the theme set directory, that file will be processed as a default if there is no game-specific theme.xml file available.
+
+In the example below, we have a theme set named `mythemeset-DE` which includes the `snes` and `nes` systems. Assuming you have some games installed for these systems, the files `mythemeset-DE/nes/theme.xml` and `mythemeset-DE/snes/theme.xml` will be processed on startup. If there are no games available for a system, its theme.xml file will be skipped.
+
+The directory structure of our example theme set could look something like the following:
 
 ```
 ...
    themes/
-      my_theme_set/
+      mythemeset-DE/
-         snes/
+         core/
-            theme.xml
+            font.ttf
-            my_cool_background.jpg
+            bold_font.ttf
+            frame.png
 
          nes/
             theme.xml
-            my_other_super_cool_background.jpg
+            background.jpg
+            logo.svg
+            logo_video.svg
 
-         common_resources/
-            my_font.ttf
-
-         theme.xml (Default theme)
-      another_theme_set/
          snes/
             theme.xml
-            some_resource.svg
+            background.jpg
+            logo.svg
+            logo_video.svg
+
+         fonts.xml
+         theme.xml
 ```
 
-The theme set system makes it easy for users to try different themes and allows distributions to include multiple theme options.  Users can change the currently active theme set in the "UI Settings" menu.  The option is only visible if at least one theme set exists.
+The theme set approach makes it easy for users to install different themes and choose between them from the _UI Settings_ menu.
 
 There are two places ES-DE can load theme sets from:
-* `[HOME]/.emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml`
+* `[HOME]/.emulationstation/themes/[THEME_SET]/`
-* `[INSTALLATION PATH]/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml`
+* `[INSTALLATION PATH]/themes/[THEME_SET]/`
 
 An example installation path would be: \
-`/usr/share/emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml`
+`/usr/share/emulationstation/themes/rbsimple-DE/`
 
-`[SYSTEM_THEME]` is the `<theme>` tag for the system, as defined in `es_systems.cfg`.  If the `<theme>` tag is not set, ES-DE will use the system's `<name>`.
+If a theme set with the same name exists in both locations, the one in the home directory will be loaded and the other one will be skipped.
 
-If both files happen to exist, ES-DE will pick the first one (the one located in the home directory).
+## Simple example
-
-Again, the `[CURRENT_THEME_SET]` value is set in the "UI Settings" menu.  If it has not been set yet or the previously selected theme set is missing, the first available theme set will be used as the default.
-
-# Simple Example
 
 Here is a very simple theme that changes the description text's color:
 
 ```xml
-
 <theme>
     <formatVersion>7</formatVersion>
     <view name="detailed">
         <text name="description">
             <color>00FF00</color>
         </text>
-        <image name="my_image" extra="true">
+        <image name="frame" extra="true">
             <pos>0.5 0.5</pos>
             <origin>0.5 0.5</origin>
             <size>0.8 0.8</size>
-            <path>./my_art/my_awesome_image.jpg</path>
+            <path>./core/frame.png</path>
         </image>
     </view>
 </theme>
 ```
 
-# How it works
+## How it works
 
-Everything must be inside a `<theme>` tag.
+Everything must be contained within a `<theme>` tag.
 
-**The `<formatVersion>` tag *must* be specified**. This is the version of the theming system the theme was designed for.
+The `<formatVersion>` tag **must** be specified. This is the version of the theming system the theme was designed for.
 The current version is 7.
 
-A *view* can be thought of as a particular "screen" within EmulationStation. Views are defined like this:
+A _view_ can be thought of as a particular "screen" within ES-DE. Views are defined like this:
 
 ```xml
 <view name="ViewNameHere">
@@ -85,63 +92,61 @@ A *view* can be thought of as a particular "screen" within EmulationStation. Vie
 </view>
 ```
 
-
+An *element* is a particular visual element, such as an image or a piece of text.  You can either modify an element that already exists for a particular view, as was done for the "description" example:
-
-An *element* is a particular visual element, such as an image or a piece of text.  You can either modify an element that already exists for a particular view (as is done in the "description" example), like this:
 
 ```xml
-    <elementTypeHere name="ExistingElementNameHere">
+<elementTypeHere name="ExistingElementNameHere">
-        ... define properties here ...
+    ... define properties here ...
-    </elementTypeHere>
+</elementTypeHere>
 ```
 
-Or, you can create your own elements by adding `extra="true"` (as is done in the "my_image" example) like this:
+Or you can create your own elements by adding `extra="true"`, as was done for the "frame" example:
 
 ```xml
-    <elementTypeHere name="YourUniqueElementNameHere" extra="true">
+<elementTypeHere name="YourUniqueElementNameHere" extra="true">
-        ... define properties here ...
+    ... define properties here ...
-    </elementTypeHere>
+</elementTypeHere>
 ```
 
-"Extra" elements will be drawn in the order they are defined (so define backgrounds first!).  When they get drawn relative to the pre-existing elements depends on the view.  Make sure "extra" element names do not clash with existing element names!  An easy way to protect against this is to just start all your extra element names with some prefix like "e_".
+"Extra" elements will be drawn in the order they are defined (so make sure to define backgrounds first).  In what order they get drawn relative to the pre-existing elements depends on the view.  Make sure "extra" element names do not clash with existing element names. An easy way to protect against this is to just start all your extra element names with a prefix such as "e_".
 
 
 
-*Properties* control how a particular *element* looks - for example, its position, size, image path, etc.  The type of the property determines what kinds of values you can use.  You can read about the types below in the "Reference" section.  Properties are defined like this:
+*Properties* control how a particular *element* looks - for example its position, size, image path etc.  The type of the property determines what kinds of values you can use.  You can read about the types below in the "Reference" section.  Properties are defined like this:
 
 ```xml
-        <propertyNameHere>ValueHere</propertyNameHere>
+<propertyNameHere>ValueHere</propertyNameHere>
 ```
 
 
-# Advanced Features
+## Advanced features
 
-It is recommended that if you are writing a theme you launch EmulationStation with the `--debug` and `--windowed` switches.  This way you can read error messages without having to check the log file.  You can also reload the current gamelist view and system view with `Ctrl-R` if `--debug` is specified.
+If you are writing a theme it's recommended to launch ES-DE with the `--debug` flag from a terminal window. If on Unix you can also pass the `--windowed` and `--resolution` flags to avoid having the application window fill the entire screen. On macOS and Windows you only need to pass the `--resolution` flag to accomplish this. By doing so, you can read error messages directly in the terminal window without having to open the log file.  You can also reload the current gamelist view and system view with `Ctrl-R` if the `--debug` flag has been set.
 
 ### The `<include>` tag
 
-You can include theme files within theme files, similar to `#include` in C (though the internal mechanism is different, the effect is the same).  Example:
+You can include theme files within theme files, for example:
 
-`~/.emulationstation/all_themes.xml`:
+`~/.emulationstation/themes/mythemeset-DE/fonts.xml`:
 ```xml
-
 <theme>
     <formatVersion>7</formatVersion>
     <view name="detailed">
         <text name="description">
-            <fontPath>./all_themes/myfont.ttf</fontPath>
+            <fontPath>./core/font.ttf</fontPath>
+            <fontSize>0.035</fontSize>
             <color>00FF00</color>
         </text>
     </view>
 </theme>
 ```
 
-`~/.emulationstation/snes/theme.xml`:
+`~/.emulationstation/themes/mythemeset-DE/snes/theme.xml`:
 ```xml
 
 <theme>
     <formatVersion>7</formatVersion>
-    <include>./../all_themes.xml</include>
+    <include>./../fonts.xml</include>
     <view name="detailed">
         <text name="description">
             <color>FF0000</color>
@@ -150,84 +155,77 @@ You can include theme files within theme files, similar to `#include` in C (thou
 </theme>
 ```
 
-Is equivalent to this `snes/theme.xml`:
+The above is equivalent to the following:
 ```xml
 
 <theme>
     <formatVersion>7</formatVersion>
     <view name="detailed">
         <text name="description">
-            <fontPath>./all_themes/myfont.ttf</fontPath>
+            <fontPath>./core/font.ttf</fontPath>
+            <fontSize>0.035</fontSize>
             <color>FF0000</color>
         </text>
     </view>
 </theme>
 ```
 
-Notice that properties that were not specified got merged (`<fontPath>`) and the `snes/theme.xml` could overwrite the included files' values (`<color>`).  Also notice the included file still needed the `<formatVersion>` tag.
+Note that properties can get merged. In the above example the `<color>` tag from `fonts.xml` got overwritten by the equivalent tag in `snes/theme.xml`. This happens because that tag was effectively declared after the first `<color>` tag. Also be aware that the included file still needed the `<formatVersion>` tag.
 
 
 ### Theming multiple views simultaneously
 
-Sometimes you want to apply the same properties to the same elements across multiple views.  The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas).  So, for example, to easily apply the same header to the basic, grid, and system views:
+Sometimes you want to apply the same properties to the same elements across multiple views.  The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas).  So for example, to apply the same logo to the basic and detailed views you could write the following:
 
 ```xml
-
 <theme>
     <formatVersion>7</formatVersion>
-    <view name="basic, grid, system">
+    <view name="basic, detailed">
         <image name="logo">
-            <path>./snes_art/snes_header.png</path>
+            <path>./snes/logo.svg</path>
         </image>
     </view>
-    <view name="detailed">
+    <view name="video">
         <image name="logo">
-            <path>./snes_art/snes_header_detailed.png</path>
+            <path>./snes/logo_video.svg</path>
         </image>
     </view>
 </theme>
 ```
 
 This is equivalent to:
-```xml
 
+```xml
 <theme>
     <formatVersion>7</formatVersion>
     <view name="basic">
         <image name="logo">
-            <path>./snes_art/snes_header.png</path>
+            <path>./snes/logo.svg</path>
         </image>
     </view>
     <view name="detailed">
         <image name="logo">
-            <path>./snes_art/snes_header_detailed.png</path>
+            <path>./snes/logo.svg</path>
         </image>
     </view>
-    <view name="grid">
+    <view name="video">
         <image name="logo">
-            <path>./snes_art/snes_header.png</path>
+            <path>./snes/logo_video.svg</path>
         </image>
     </view>
-    <view name="system">
-        <image name="logo">
-            <path>./snes_art/snes_header.png</path>
-        </image>
-    </view>
-    ... and any other view that might try to look up "logo" ...
 </theme>
 ```
 
 
 ### Theming multiple elements simultaneously
 
-You can theme multiple elements *of the same type* simultaneously.  The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas), just like it does for views, as long as the elements have the same type.  This is useful if you want to, say, apply the same color to all the metadata labels:
+You can theme multiple elements *of the same type* simultaneously.  The `name` attribute actually works as a list (delimited by any characters of `\t\r\n ,` - that is, whitespace and commas). This is useful if you want to, say, apply the same color to all the metadata labels:
 
 ```xml
-
 <theme>
     <formatVersion>7</formatVersion>
     <view name="detailed">
-        <!-- Weird spaces/newline on purpose! -->
+        <!-- Weird spaces/newline on purpose -->
         <text name="md_lbl_rating, md_lbl_releasedate, md_lbl_developer, md_lbl_publisher,
         md_lbl_genre,    md_lbl_players,        md_lbl_lastplayed, md_lbl_playcount">
             <color>48474D</color>
@@ -238,7 +236,6 @@ You can theme multiple elements *of the same type* simultaneously.  The `name` a
 
 Which is equivalent to:
 ```xml
-
 <theme>
     <formatVersion>7</formatVersion>
     <view name="detailed">
@@ -270,20 +267,16 @@ Which is equivalent to:
 </theme>
 ```
 
-Just remember, *this only works if the elements have the same type!*
+Just remember, _this only works if the elements have the same type._
-
-### Element rendering order with z-index
-
-You can now change the order in which elements are rendered by setting `zIndex` values.  Default values correspond to the default rendering order while allowing elements to easily be shifted without having to set `zIndex` values for every element.  Elements will be rendered in order from smallest z-index to largest.
 
 
-#### Navigation sounds
+### Navigation sounds
 
-The navigation sounds are configured globally per theme set, so it needs to be defined as a feature and with the view set to the special 'all' category.
+Navigation sounds are configured globally per theme set, so it needs to be defined as a feature and with the view set to the special "all" category.
 It's recommended to put these elements in a separate file and include it from the main theme file (e.g. `<include>./navigationsounds.xml</include>`).
 There are seven different navigation sounds that can be configured. The names as well as the element structure should be self-explanatory based
 on the example below.
-Starting EmulationStation with the --debug flag will provide feedback on whether any navigation sound elements were read from the theme set. If no navigation sound is provided by the theme, ES-DE will use the bundled navigation sound file as a fallback. This is done per sound, so the theme could provide for example one or two custom sound files while using the bundled ES-DE sounds for the other samples.
+Starting ES-DE with the --debug flag will provide feedback on whether any navigation sound elements were read from the theme set. If no navigation sounds are provided by the theme set, ES-DE will use the bundled navigation sounds as a fallback. This is done per sound file, so the theme could provide for example one or two custom sound files while using the bundled ES-DE sounds for the other samples.
 
 Example debug output:
 ```
@@ -297,7 +290,6 @@ Jul 12 11:28:58 Debug:  Sound::getFromTheme(): Tag not found, using fallback sou
 Example `navigationsounds.xml`, to be included from the main theme file:
 
 ```xml
-
 <theme>
     <formatVersion>7</formatVersion>
     <feature supported="navigationsounds">
@@ -328,14 +320,18 @@ Example `navigationsounds.xml`, to be included from the main theme file:
 </theme>
 ```
 
-#### Defaults
+### Element rendering order with zIndex
 
-##### system
+You can change the order in which elements are rendered by setting their `zIndex` values. All elements have a default zIndex value so you only need to define it for the elements you wish to override. Elements will be rendered in order from smallest zIndex value to largest.
+
+Below are the default zIndex values per element type:
+
+#### system
 * Extra Elements `extra="true"` - 10
 * `carousel name="systemcarousel"` - 40
 * `text name="systemInfo"` - 50
 
-##### basic, detailed, grid, video
+#### basic, detailed, video, grid
 * `image name="background"` - 0
 * Extra Elements `extra="true"` - 10
 * `textlist name="gamelist"` - 20
@@ -374,12 +370,12 @@ Example `navigationsounds.xml`, to be included from the main theme file:
 ### Theme variables
 
 Theme variables can be used to simplify theme construction.  There are 2 types of variables available.
-* System Variables
+* System variables
-* Theme Defined Variables
+* Theme defined variables
 
-#### System Variables
+#### System variables
 
-System variables are system specific and are derived from the values in es_systems.cfg.
+System variables are system specific and are derived from the values in es_systems.xml.
 * `system.name`
 * `system.fullName`
 * `system.theme`
@@ -406,9 +402,23 @@ or to specify only a portion of the value of a theme property:
 ````
 
 
-# Reference
+## Reference
+
+### Views, their elements, and themeable properties:
+
+#### system
+* `helpsystem name="help"` - ALL
+    - The help system style for this view.
+* `carousel name="systemcarousel"` -ALL
+    - The system logo carousel
+* `image name="logo"` - PATH | COLOR
+    - A logo image, to be displayed in the system logo carousel.
+* `text name="logoText"` - FONT_PATH | COLOR | FORCE_UPPERCASE | LINE_SPACING | TEXT
+    - A logo text, to be displayed system name in the system logo carousel when no logo is available.
+* `text name="systemInfo"` - ALL
+    - Displays details of the system currently selected in the carousel.
+* You can use extra elements (elements with `extra="true"`) to add your own backgrounds, etc.  They will be displayed behind the carousel, and scroll relative to the carousel.
 
-## Views, their elements, and themeable properties:
 
 #### basic
 * `helpsystem name="help"` - ALL
@@ -422,7 +432,6 @@ or to specify only a portion of the value of a theme property:
 * `textlist name="gamelist"` - ALL
     - The gamelist.  `primaryColor` is for games, `secondaryColor` is for folders.  Centered by default.
 
----
 
 #### detailed
 * `helpsystem name="help"` - ALL
@@ -530,7 +539,6 @@ or to specify only a portion of the value of a theme property:
         * `text name="md_name"` - ALL
             - The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default
 
----
 
 #### grid
 * `helpsystem name="help"` - ALL
@@ -585,23 +593,8 @@ or to specify only a portion of the value of a theme property:
         * `text name="md_name"` - ALL
             - The "name" metadata (the game name). Unlike the others metadata fields, the name is positioned offscreen by default
 
----
 
-#### system
+### Types of properties:
-* `helpsystem name="help"` - ALL
-    - The help system style for this view.
-* `carousel name="systemcarousel"` -ALL
-    - The system logo carousel
-* `image name="logo"` - PATH | COLOR
-    - A logo image, to be displayed in the system logo carousel.
-* `text name="logoText"` - FONT_PATH | COLOR | FORCE_UPPERCASE | LINE_SPACING | TEXT
-    - A logo text, to be displayed system name in the system logo carousel when no logo is available.
-* `text name="systemInfo"` - ALL
-    - Displays details of the system currently selected in the carousel.
-* You can use extra elements (elements with `extra="true"`) to add your own backgrounds, etc.  They will be displayed behind the carousel, and scroll relative to the carousel.
-
-
-## Types of properties:
 
 * NORMALIZED_PAIR - two decimals, in the range [0..1], delimited by a space.  For example, `0.25 0.5`.  Most commonly used for position (x and y coordinates) and size (width and height).
 * NORMALIZED_RECT - four decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5 0.10 0.30`.  Most commonly used for padding to store top, left, bottom and right coordinates.
@@ -612,7 +605,7 @@ or to specify only a portion of the value of a theme property:
 * STRING - a string of text.
 
 
-## Types of elements and their properties:
+### Types of elements and their properties:
 
 Common to almost all elements is a `pos` and `size` property of the NORMALIZED_PAIR type.  They are normalized in terms of their "parent" object's size; 99% of the time, this is just the size of the screen.  In this case, `<pos>0 0</pos>` would correspond to the top left corner, and `<pos>1 1</pos>` the bottom right corner (a positive Y value points further down).  `pos` almost always refers to the top left corner of your element.  You *can* use numbers outside of the [0..1] range if you want to place an element partially or completely off-screen.
 
@@ -797,7 +790,7 @@ Can be created as an extra.
 * `zIndex` - type: FLOAT.
     - z-index value for component.  Components will be rendered in order of z-index value from low to high.
 
-EmulationStation borrows the concept of "nine patches" from Android (or "9-Slices"). Currently the implementation is very simple and hard-coded to only use 48x48px images (16x16px for each "patch"). Check the `data/resources` directory for some examples (button.png, frame.png).
+ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Currently the implementation is very simple and hard-coded to only use 48x48px images (16x16px for each "patch"). Check the `data/resources` directory for some examples (button.png, frame.png).
 
 #### rating
 
@@ -947,6 +940,8 @@ EmulationStation borrows the concept of "nine patches" from Android (or "9-Slice
 The help system is a special element that displays a context-sensitive list of actions the user can take at any time.  You should try and keep the position constant throughout every screen.  Keep in mind the "default" settings (including position) are used whenever the user opens a menu.
 
 
+## Example theme sets
+
 To see some examples of EmulationStation themes, the following resources are recommended:
 
 https://aloshi.com/emulationstation#themes

THEMES.md

@@ -40,7 +40,7 @@ There are two places ES-DE can load theme sets from:
 An example installation path would be: \
 `/usr/share/emulationstation/themes/[CURRENT_THEME_SET]/[SYSTEM_THEME]/theme.xml`
 
-`[SYSTEM_THEME]` is the `<theme>` tag for the system, as defined in `es_systems.cfg`.  If the `<theme>` tag is not set, ES-DE will use the system's `<name>`.
+`[SYSTEM_THEME]` is the `<theme>` tag for the system, as defined in `es_systems.xml`.  If the `<theme>` tag is not set, ES-DE will use the system's `<name>`.
 
 If both files happen to exist, ES-DE will pick the first one (the one located in the home directory).
 
@@ -74,7 +74,7 @@ Everything must be inside a `<theme>` tag.
 **The `<formatVersion>` tag *must* be specified**. This is the version of the theming system the theme was designed for.
 The current version is 6.
 
-A *view* can be thought of as a particular "screen" within EmulationStation. Views are defined like this:
+A *view* can be thought of as a particular "screen" within ES-DE. Views are defined like this:
 
 ```xml
 
@@ -112,7 +112,7 @@ Or, you can create your own elements by adding `extra="true"` (as is done in the
 
 # Advanced Features
 
-It is recommended that if you are writing a theme you launch EmulationStation with the `--debug` and `--windowed` switches.  This way you can read error messages without having to check the log file.  You can also reload the current gamelist view and system view with `Ctrl-R` if `--debug` is specified.
+It is recommended that if you are writing a theme you launch ES-DE with the `--debug` and `--windowed` switches.  This way you can read error messages without having to check the log file.  You can also reload the current gamelist view and system view with `Ctrl-R` if `--debug` is specified.
 
 ### The `<include>` tag
 
@@ -279,7 +279,7 @@ The navigation sounds are configured globally per theme set, so it needs to be d
 It's recommended to put these elements in a separate file and include it from the main theme file (e.g. `<include>./navigationsounds.xml</include>`).
 There are seven different navigation sounds that can be configured. The names as well as the element structure should be self-explanatory based
 on the example below.
-Starting EmulationStation with the --debug flag will provide feedback on whether any navigation sound elements were read from the theme set. If no navigation sound is provided by the theme, ES-DE will use the bundled navigation sound file as a fallback. This is done per sound, so the theme could provide for example one or two custom sound files while using the bundled ES-DE sounds for the other samples.
+Starting ES-DE with the --debug flag will provide feedback on whether any navigation sound elements were read from the theme set. If no navigation sound is provided by the theme, ES-DE will use the bundled navigation sound file as a fallback. This is done per sound, so the theme could provide for example one or two custom sound files while using the bundled ES-DE sounds for the other samples.
 
 Example debug output:
 ```
@@ -375,7 +375,7 @@ Theme variables can be used to simplify theme construction.  There are 2 types o
 
 #### System Variables
 
-System variables are system specific and are derived from the values in es_systems.cfg.
+System variables are system specific and are derived from the values in es_systems.xml.
 * `system.name`
 * `system.fullName`
 * `system.theme`
@@ -793,7 +793,7 @@ Can be created as an extra.
 * `zIndex` - type: FLOAT.
     - z-index value for component.  Components will be rendered in order of z-index value from low to high.
 
-EmulationStation borrows the concept of "nine patches" from Android (or "9-Slices"). Currently the implementation is very simple and hard-coded to only use 48x48px images (16x16px for each "patch"). Check the `data/resources` directory for some examples (button.png, frame.png).
+ES-DE borrows the concept of "nine patches" from Android (or "9-Slices"). Currently the implementation is very simple and hard-coded to only use 48x48px images (16x16px for each "patch"). Check the `data/resources` directory for some examples (button.png, frame.png).
 
 #### rating