Documentation update.

CHANGELOG.md

@@ -213,6 +213,8 @@
 * When a legacy theme set had a video view style but did not have a valid md_video entry then the video player would still start (and play the audio)
 * Clearing a game in the metadata editor would sometimes not remove all media files (if there were both a .jpg and a .png for a certain file type)
 * The tile property for the image element did not work correctly with SVG images
+* Defining an itemScale (logoScale) property lower than 1.0 for the carousel did not work correctly
+* Carousel text did not get scaled/multiplied correctly with the itemScale property (bug retained for legacy themes for maximum backward compatibility)
 * Letters would sometimes get rendered with ugly edge artifacts, visible when scaling text on the carousel
 * Text opacity did not work correctly in some places, such as for the help prompts
 * ScrollableContainer faded semi-transparent text to fully opaque when resetting

THEMES-DEV.md

@@ -70,7 +70,7 @@ With the new theme engine the view presets were removed and the only views now a
 
 In addition to the variant support which provides an unlimited flexibility for creating custom theme profiles, support for specific aspect ratios was introduced. This makes it possible to define different theme configuration for different display aspect ratios and to provide the user with the option to choose between these from the _UI Settings_ menu. That could for example be choice between a 16:9 and a 4:3 layout, or perhaps also a vertical screen orientation layout in addition to these.
 
-As well new theming abilities like Lottie animations were added with the new theme engine.
+As well new theming abilities like GIF and Lottie animations were added with the new theme engine.
 
 The following are the most important changes compared to the legacy theme structure:
 
@@ -95,6 +95,13 @@ Attempting to use any of the legacy logic in the new theme structure will make t
 
 Except the points mentioned above, theme configuration looks pretty similar to the legacy theme structure, so anyone having experience with these older themes should hopefully feel quite at home with the new theme engine. Probably the most important thing to keep in mind is that as there are no longer any view presets available, some more effort is needed from the theme developer to define values for some elements. This is especially true for zIndex values as elements could now be hidden by other elements if care is not taken to explicitly set the zIndex for each of them. This additional work is however a small price to pay for the much more powerful and flexible theming functionality provided by the new theme engine.
 
+Note that the legacy theme engine had quite inaccurate text sizing and font rendering and while this has been greatly improved in the new engine, for legacy themes most old bugs are retained for maximum backward compatibility. This means that you may need to revise font sizes and text placements when porting a legacy theme to the new engine. Here are some examples:
+
+* Line spacing for the textlist element was not consistently applied across different screen resolutions
+* Carousel text entries did not multiply the font size by the itemScale (logoScale) property value
+* The defined line spacing was not always applied for automatically sized text elements
+* Font sizes were rounded to integers, leading to imprecise text sizing across different resolutions (the rounding was also done incorrectly)
+
 ## Simple example
 
 Here is a very simple theme that changes the color of the game name text:
@@ -1240,8 +1247,8 @@ Properties:
 * `fontPath` - type: PATH
     - Path to a TrueType font (.ttf).
 * `fontSize` - type: FLOAT
-    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the font's bounding box, the actual glyphs (characters) don't normally fill this entire area.
+    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
-    - Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value can get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e. `fontSize` can be set to twice that of the y axis of the `size` property. Any value above that will be clamped.
+    - Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e. `fontSize` can be set to twice that of the y axis of the `size` property. Any value above that will be clamped.
     - Default is `0.045`
 * `horizontalAlignment` - type: STRING
     - Controls alignment on the X axis.
@@ -1257,7 +1264,7 @@ Properties:
     - Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
     - Default is `none` (original letter case is retained)
 * `lineSpacing` - type: FLOAT
-    - Controls the space between lines (as a multiple of font height).
+    - Controls the space between lines (as a multiple of the font height). Due to the imprecise nature of typefaces where certain glyphs (characters) may exceed the requested font size, it's recommended to keep this value at around `1.1` or higher for multi-line text fields. This way overlapping glyphs or characters being cut off at the top or bottom will be prevented.
     - Minimum value is `0.5` and maximum value is `3`
     - Default is `1.5`
 * `opacity` - type: FLOAT
@@ -1310,8 +1317,8 @@ Properties:
 * `fontPath` - type: PATH
     - Path to a TrueType font (.ttf).
 * `fontSize` - type: FLOAT
-    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the font's bounding box, the actual glyphs (characters) don't normally fill this entire area.
+    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
-    - Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value can get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e. `fontSize` can be set to twice that of the y axis of the `size` property. Any value above that will be clamped.
+    - Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e. `fontSize` can be set to twice that of the y axis of the `size` property. Any value above that will be clamped.
     - Default is `0.045`
 * `horizontalAlignment` - type: STRING
     - Controls alignment on the X axis.
@@ -1383,8 +1390,8 @@ Properties:
 * `fontPath` - type: PATH
     - Path to a TrueType font (.ttf).
 * `fontSize` - type: FLOAT
-    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the font's bounding box, the actual glyphs (characters) don't normally fill this entire area.
+    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
-    - Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value can get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e. `fontSize` can be set to twice that of the y axis of the `size` property. Any value above that will be clamped.
+    - Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e. `fontSize` can be set to twice that of the y axis of the `size` property. Any value above that will be clamped.
     - Default is `0.045`
 * `color` - type: COLOR
 * `backgroundColor` - type: COLOR
@@ -1519,12 +1526,12 @@ Properties:
     - Minimum value is `0` and maximum value is `20`
     - Default is `8`
 * `itemSize` - type: NORMALIZED_PAIR
-    - Both axes need to be defined.
+    - Size of the item prior to multiplication by the `itemScale` value, i.e. the size of all unselected items. Both axes need to be defined.
     - Minimum value per axis is `0.05` and maximum value per axis is `1`
     - Default is `0.25 0.155`
 * `itemScale` - type: FLOAT.
     - Selected item is increased in size by this scale.
-    - Minimum value is `0.5` and maximum value is `3`
+    - Minimum value is `0.2` and maximum value is `3`
     - Default is `1.2`
 * `itemTransitions` - type: STRING
     - How to render item transitions when navigating the carousel. By default a slide animation will be played when moving between items but if this property is set to `instant` instead then the transitions will be immediate.
@@ -1599,13 +1606,14 @@ Properties:
 * `fontPath` - type: PATH
     - Path to a TrueType font (.ttf) used as fallback if there is no `staticItem` / `itemType` image defined or found, and if `defaultItem` has not been defined.
 * `fontSize` - type: FLOAT
-    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the font's bounding box, the actual glyphs (characters) don't normally fill this entire area.
+    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area. This property value is effectively multiplied by the `itemScale` value for the currently selected item (but if this property is omitted then the default value will not get multiplied by `itemScale`).
+    - Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size.
     - Default is `0.085`
 * `letterCase` - type: STRING
     - Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
     - Default is `none` (original letter case is retained)
 * `lineSpacing` - type: FLOAT
-    - Controls the space between lines (as a multiple of font height).
+    - Controls the space between lines (as a multiple of the font height). Due to the imprecise nature of typefaces where certain glyphs (characters) may exceed the requested font size, it's recommended to keep this value at around `1.1` or higher. This way overlapping glyphs or characters being cut off at the top or bottom will be prevented.
     - Minimum value is `0.5` and maximum value is `3`
     - Default is `1.5`
 * `fadeAbovePrimary` - type: BOOLEAN
@@ -1662,7 +1670,7 @@ Properties:
     - Secondary color; what this means depends on the text list. For example, for game lists, it is the color of a folder.
 * `fontPath` - type: PATH
 * `fontSize` - type: FLOAT
-    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the font's bounding box, the actual glyphs (characters) don't normally fill this entire area.
+    - Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
     - Default is `0.045`
 * `horizontalAlignment` - type: STRING
     - Controls alignment on the X axis.
@@ -1675,7 +1683,7 @@ Properties:
     - Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
     - Default is `none` (original letter case is retained)
 * `lineSpacing` - type: FLOAT
-    - Controls the space between lines (as a multiple of font height).
+    - Controls the space between lines (as a multiple of the font height).
     - Minimum value is `0.5` and maximum value is `3`
     - Default is `1.5`
 * `indicators` - type: STRING
@@ -1745,8 +1753,8 @@ Properties:
     - Default is the same value as iconColor.
 * `fontPath` - type: PATH
 * `fontSize` - type: FLOAT
-    - This property implicitly sets the icon size and is therefore the means to change the overall size of the helpsystem element.  This calculation is based on the font's bounding box, the actual glyphs (characters) don't normally fill this entire area.
+    - This property implicitly sets the icon size and is therefore the means to change the overall size of the helpsystem element. This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
-    - Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value can get clamped to a larger relative size.
+    - Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size.
     - Default is `0.035`
 * `entrySpacing` - type: FLOAT
     - Spacing between the help element pairs.

USERGUIDE-DEV.md

@@ -2923,7 +2923,7 @@ For this example, we've downloaded the [alekfull-nx-es-de](https://github.com/an
 ~/.emulationstation/themes/es-theme-carbon
 ```
 
-We now have four entries in the _Theme set_ selector in the UI settings menu, i.e. _alekfull-nx-es-de, es-theme-carbon, modern-DE and slate-DE_.
+We now have four entries in the _Theme set_ selector in the UI settings menu, i.e. _alekfull-nx-es-de, es-theme-carbon, modern-DE_ and _slate-DE_.
 
 Although you should place additional themes in your ES-DE home directory, the default slate-DE and modern-DE themes are located in the installation folder as they come bundled with the application. For example this could be `/usr/share/emulationstation/themes/` or `/usr/local/share/emulationstation/themes/` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/` on macOS or `C:\Program Files\EmulationStation-DE\themes\` on Windows. If using the portable ES-DE release on Windows, the themes folder will be located in the root of the EmulationStation-DE directory.
 

USERGUIDE.md

@@ -2833,7 +2833,7 @@ For this example, we've downloaded the [alekfull-nx-retropie](https://github.com
 ~/.emulationstation/themes/es-theme-carbon
 ```
 
-We now have four entries in the _Theme set_ selector in the UI settings menu, i.e. _alekfull-nx-retropie, es-theme-carbon, modern-DE and rbsimple-DE_.
+We now have four entries in the _Theme set_ selector in the UI settings menu, i.e. _alekfull-nx-retropie, es-theme-carbon, modern-DE_ and _rbsimple-DE_.
 
 Although you should place additional themes in your ES-DE home directory, the default rbsimple-DE and modern-DE themes are located in the installation folder as they come bundled with the application. For example this could be `/usr/share/emulationstation/themes/` or `/usr/local/share/emulationstation/themes/` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/` on macOS or `C:\Program Files\EmulationStation-DE\themes\` on Windows. If using the portable ES-DE release on Windows, the themes folder will be located in the root of the EmulationStation-DE directory.