More docs on MCI/views/theming

docs/art/themes.md

@@ -6,10 +6,12 @@ title: Themes
 ENiGMA½ comes with an advanced theming system allowing system operators to highly customize the look and feel of their boards. A given installation can have as many themes as you like for your users to choose from.
 
 ## General Information
-Themes live in `art/themes/`. Each theme (and thus it's *theme ID*) is a directory within the `themes` directory. The theme itself is simply a collection of art files, and a `theme.hjson` file that further defines layout, colors & formatting, etc. ENiGMA½ comes with a default theme by [Luciano Ayres](http://blocktronics.org/tag/luciano-ayres/) of [Blocktronics](http://blocktronics.org/) called Mystery Skull. This theme is in `art/themes/luciano_blocktronics`, and thus it's *theme ID* is `luciano_blocktronics`.
+Themes live in `art/themes/`. Each theme (and thus it's *theme ID*) is a directory within the `themes` directory. The theme itself is simply a collection of art files, and a `theme.hjson` file that further defines layout, colors & formatting, etc.
+
+ENiGMA½ comes with a default theme by [Luciano Ayres](http://blocktronics.org/tag/luciano-ayres/) of [Blocktronics](http://blocktronics.org/) called Mystery Skull. This theme is in `art/themes/luciano_blocktronics`, and thus it's *theme ID* is `luciano_blocktronics`.
 
 ## Art
-For information on art files, see [General Art Information](general.md). TL;DR: In general, to theme a piece of art, create a version of it in your themes directory.
+For information on art files, see [General Art Information](general.md). In general, to theme a piece of art, create a version of it in your themes directory.
 
 :memo: Remember that by default, the system will allow for randomly selecting art (in one of the directories mentioned above) by numbering it: `FOO1.ANS`, `FOO2.ANS`, etc.!
 
@@ -67,8 +69,20 @@ Major areas to override/theme:
 * `mci`: Set per-MCI code properties such as `height`, `width`, text styles, etc. See [MCI Codes](mci.md) for a more information.
 
 Two formats for `mci` blocks are allowed:
-* Verbose where a form ID(s) are supplied.
 * Shorthand if only a single/first form is needed.
+* Verbose where a form ID(s) are supplied (required if multiple forms are used)
+
+Example: Shorthand `mci` format:
+```hjson
+matrix: {
+    mci: {
+        VM1: {
+            itemFormat: "|03{text}"
+            focusItemFormat: "|11{text!styleFirstLower}"
+        }
+    }
+}
+```
 
 Example: Verbose `mci` with form IDs:
 ```hjson
@@ -88,18 +102,6 @@ newUserFeedbackToSysOp: {
 }
 ```
 
-Example: Shorthand `mci` format:
-```hjson
-matrix: {
-    mci: {
-        VM1: {
-            itemFormat: "|03{text}"
-            focusItemFormat: "|11{text!styleFirstLower}"
-        }
-    }
-}
-```
-
 ##### Custom Range Info Formatting
 Many modules support "custom range" MCI items. These are MCI codes that are left to the user to define using a format object specific to the module. For example, consider the `msg_area_list` module: This module sets MCI codes 10+ (`%TL10`, `%TL11`, etc.) as "custom range". When theming you can place these MCI codes in your artwork then define the format in `theme.hjson`:
 
@@ -112,7 +114,7 @@ messageAreaChangeCurrentArea: {
 ```
 
 ## Creating Your Own
-:warning: ***IMPORTANT!*** It is recommended you don't make any customisations to the included `luciano_blocktronics' theme. Instead, create your own and make changes to that instead:
+:warning: ***IMPORTANT!*** Do not make any customizations to the included `luciano_blocktronics' theme. Instead, create your own and make changes to that instead:
 
 1. Copy `/art/themes/luciano_blocktronics` to `art/themes/your_board_theme`
 2. Update the `info` block at the top of the theme.hjson file:
@@ -125,10 +127,41 @@ info: {
 }
 ```
 
-3. If desired, you may make this the default system theme in `config.hjson` via `theme.default`. `theme.preLogin` may be set if you want this theme used for pre-authenticated users. Both of these values also accept `*` if you want the system to radomly pick.
+3. If desired, you may make this the default system theme in `config.hjson` via `theme.default`. `theme.preLogin` may be set if you want this theme used for pre-authenticated users. Both of these values also accept `*` if you want the system to randomly pick.
 ``` hjson
 theme: {
     default: your_board_theme
     preLogin: *
 }
 ```
+
+## Theming Example
+Let's run through an example!
+
+Consider the following `menu.hjson` entry:
+```hjson
+superFancyMenu: {
+    art: FANCY.ANS
+    // ...some other stuff...
+}
+```
+
+With a file of `FANCY.ANS` in `art/themes/fancy_theme` containing the following MCI codes:
+* TL1 (Generic text label)
+* BN2 (Predefined: Board Name)
+
+An entry in your `theme.hjson` could look like this:
+```hjson
+superFancyMenu: {
+    mci: {
+        TL1: {
+            //  supply the full format of the TL1 View
+            text: |02ENiGMA|10½ |08v|03|VN
+        }
+        BN2: {
+            //  Make Board Name l33t style
+            style: l33t
+        }
+    }
+}
+```