From 6a01c05ec9f75a8aece6e964c92d22b470b69214 Mon Sep 17 00:00:00 2001
From: Bryan Ashby <bryan@l33t.codes>
Date: Sat, 17 Nov 2018 21:04:44 -0700
Subject: [PATCH] Show art docs

---
 docs/_includes/nav.md    |  1 +
 docs/modding/show-art.md | 70 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 docs/modding/show-art.md

diff --git a/docs/_includes/nav.md b/docs/_includes/nav.md
index c8cb67c9..4c2fc0f6 100644
--- a/docs/_includes/nav.md
+++ b/docs/_includes/nav.md
@@ -73,6 +73,7 @@
     - [Rumorz]({{ site.baseurl }}{% link modding/rumorz.md %})
     - [File Transfer Protocol Select]({{ site.baseurl }}{% link modding/file-transfer-protocol-select.md %})
     - [Onelinerz]({{ site.baseurl }}{% link modding/onelinerz.md %})
+    - [Show Art]({{ site.baseurl }}{% link modding/show-art.md %})
 
   - Administration
     - [oputil]({{ site.baseurl }}{% link admin/oputil.md %})
diff --git a/docs/modding/show-art.md b/docs/modding/show-art.md
new file mode 100644
index 00000000..c00d7009
--- /dev/null
+++ b/docs/modding/show-art.md
@@ -0,0 +1,70 @@
+---
+layout: page
+title: User List
+---
+## The Show Art Module
+The built in `show_art` module add some advanced ways in which you can configure your system to display art assets beyond what a standard menu entry can provide. For example, based on user selection of a file or message base area.
+
+## Configuration
+### Config Block
+Available `config` block entries:
+* `method`: Set the method in which to show art. See **Methods** below.
+* `optional`: Is this art required or optional? If non-optional and we cannot show art based on `method`, it is an error.
+* `key`: Used for some `method`s. See **Methods**
+
+### Methods
+#### Extra Args
+When `method` is `extraArgs`, the module selects an *art spec* from a value found within `extraArgs` that were passed to `show_art` by `key`. Consider the following:
+
+Given an `menu.hjson` entry:
+```hjson
+showWithExtraArgs: {
+    module: show_art
+    config: {
+        method: extraArgs
+        key: fooBaz
+    }
+}
+```
+If the `showWithExtraArgs` menu was entered and passed `extraArgs` as the following:
+```json
+{
+    fizzBang : true,
+    fooBaz : "LOLART"
+}
+```
+
+...then the system would use the *art spec* of `LOLART`.
+
+#### Area & Conferences
+Handy for inserting into File Base, Message Conferences, or Mesage Area selections selections. When `method` is `fileBaseArea`, `messageConf`, or `messageArea` the selected conf/area's associated *art spec* is utilized. Example:
+
+Given a file base entry in `config.hjson`:
+```hjson
+areas: {
+    all_ur_base: {
+        name: All Your Base
+        desc: chown -r us ./base
+        art: ALLBASE
+    }
+}
+```
+
+A menu entry may look like this:
+```hjson
+showFileBaseAreaArt: {
+    module: show_art
+    config: {
+        method: fileBaseArea
+        cls: true
+        pause: true
+        menuFlags: [ "popParent", "noHistory" ]
+    }
+}
+```
+
+...if the user choose the "All Your Base" area, the *art spec* of `ALLBASE` would be selected and displayed.
+
+The only difference for `messageConf` or `messageArea` methods are where the art is defined (which is always next to the conf or area declaration in `config.hjson`).
+
+While `key` can be overridden, the system uses `areaTag` for message/file area selections, and `confTag` for conference selections by default.