From f0aa611904597674aab0cb6e802886b7ed183534 Mon Sep 17 00:00:00 2001
From: Bryan Ashby <bryan@l33t.codes>
Date: Sun, 5 Aug 2018 21:22:45 -0600
Subject: [PATCH] Better abracadabra docs!

---
 docs/modding/local-doors.md | 41 +++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 13 deletions(-)

diff --git a/docs/modding/local-doors.md b/docs/modding/local-doors.md
index b9620748..719a992b 100644
--- a/docs/modding/local-doors.md
+++ b/docs/modding/local-doors.md
@@ -5,28 +5,43 @@ title: Local Doors
 ## The abracadabra Module
 The `abracadabra` module provides a generic and flexible solution for many door types. Through this module you can execute native processes & scripts directly, and process I/O through stdio or a temporary TCP server.
 
-The `abracadabra` `config` block can contain the following:
-* `name`: Used as a key for tracking number of clients using a particular door
-* `dropFileType`: Specifies the type of drop file to generate (See table below)
-* `cmd`: Path to executable to launch
+## Configuration
+The `abracadabra` `config` block can contain the following members:
+* `name`: Used as a key for tracking number of clients using a particular door.
+* `dropFileType`: Specifies the type of drop file to generate (See **Argument Variables** below).
+* `cmd`: Path to executable to launch.
 * `args`: Array of argument(s) to pass to `cmd`. See below for information on variables that can be used here.
+* `cwd`: Set the Current Working Directory for `cmd`. Defaults to the directory of `cmd`.
 * `nodeMax`: Max number of nodes that can access this door at once. Uses `name` as a mapping key
 * `tooManyArt`: Art file spec to display if too many instances are already in use
 * `io`: Where to process I/O. Can be `stdio` or `socket`
+* `encoding`: Specify the door's encoding. Defaults to `cp437`. Linux binaries for example, often produce `utf8`.
 
+### Drop File Types
 Drop file types specified by `dropFileType`:
 * `DOOR`: [DOOR.SYS](http://goldfndr.home.mindspring.com/dropfile/doorsys.htm)
 * `DOOR32`: [DOOR32.SYS](http://wiki.bbses.info/index.php/DOOR32.SYS)
 * `DORINFO`: [DORINFOx.DEF](http://goldfndr.home.mindspring.com/dropfile/dorinfo.htm)
 
-Variables for use in `args`:
-* `{node}`: Current node number
-* `{dropFile}`: Path to generated drop file
-* `{userId}`: Current user ID
-* `{srvPort}`: Tempoary server port when `io` is `socket`
+### Argument Variables
+The following variables may be used in `{args}` entries:
+* `{node}`: Current node number.
+* `{dropFile}`: Drop _filename_ only.
+* `{dropFilePath}`: Full path to generated drop file.
+* `{userId}`: Current user ID.
+* `{userName}`: _Sanatized_ username. Safe for filenames, etc.
+* `{userNameRaw}`: _Raw_ username. May not be safe for filenames!
+* `{srvPort}`: Tempoary server port when `io` is set to `socket`.
+* `{cwd}`: Current Working Directory.
 
+Example:
+```hjson
+args: [
+    "-D", "{dropFile}", "-N", "{node}"
+]
+```
 
-### DOSEMU with abracadabra
+## DOSEMU with abracadabra
 [DOSEMU](http://www.dosemu.org/) can provide a good solution for running legacy DOS doors when running on Linux systems. For this, we will create a virtual serial port (COM1) that communicates via stdio.
 
 As an example, here are the steps for setting up Pimp Wars:
@@ -82,12 +97,12 @@ doorPimpWars: {
 
 ```
 
-### QEMU with abracadabra
+## QEMU with abracadabra
 [QEMU](http://wiki.qemu.org/Main_Page) provides a robust, cross platform solution for launching doors under many platforms (likely anwywhere Node.js is supported and ENiGMA½ can run). Note however that there is an important and major caveat: **Multiple instances of a particular door/OS image should not be run at once!** Being more flexible means being a bit more complex. Let's look at an example for running L.O.R.D. under a UNIX like system such as Linux or FreeBSD.
 
 Basically we'll be creating a bootstrap shell script that generates a temporary node specific `go.bat` to launch our door. This will be called from `autoexec.bat` within our QEMU FreeDOS partition.
 
-#### Step 1: Create a FreeDOS image
+### Step 1: Create a FreeDOS image
 [FreeDOS](http://www.freedos.org/) is a free mostly MS-DOS compatible DOS package that works well for running 16bit doors. Follow the [QEMU/FreeDOS](https://en.wikibooks.org/wiki/QEMU/FreeDOS) guide for creating an `freedos_c.img`. This will contain FreeDOS itself and installed BBS doors.
 
 After this is complete, copy LORD to C:\DOORS\LORD within FreeDOS. An easy way to tranfer files from host to DOS is to use QEMU's vfat as a drive. For example:
@@ -100,7 +115,7 @@ With the above you can now copy files from D: to C: within FreeDOS and add the f
 CALL E:\GO.BAT
 ```
 
-#### Step 2: Create a bootstrap script
+### Step 2: Create a bootstrap script
 Our bootstrap script will prepare `GO.BAT` and launch FreeDOS. Below is an example: