1 files changed, 109 insertions, 0 deletions
diff --git a/desktop/durden/README b/desktop/durden/README
new file mode 100644
index 0000000000..d1aaaa3e6d
--- /dev/null
+++ b/desktop/durden/README
@@ -0,0 +1,109 @@
+Durden is a free (3-clause BSD) desktop environment for Arcan,
+thus it requires a working arcan installation, optionally set-up
+with compatible launch targets etc.
+
+STARTING:
+
+distr/durden is a support script that can be run to try and
+automatically set everything up and start. It also takes care of
+relaunch/recover if the program terminated abnormally.
+
+If you have a system that uses the "XDG" set of directories, the script
+will build the directory tree in XDG_DATA_HOME/arcan, otherwise it will
+use $HOME/.arcan. To help debug issues, you can create a 'logs' folder
+in that directory and both engine output, Lua crash dumps and
+frameserver execution will be stored there.
+
+CONFIGURATION (RUNTIME)
+
+Most changes, from visuals to window management behavior and input
+device actions, can be done from within durden and the UI itself using
+the menu HUD. By default, this is accessed from META1+G for (global) and
+META1+T for current window (target).
+
+All actions in durden are mapped into a huge virtual filesystem tree.
+Keybindings, UI buttons etc. are all simply paths within this
+filesystem.
+
+These are covered in much more detail on the webpage, but the ones you
+might want to take extra note of is:
+
+ /global/input/bind/custom
+ /global/system/shutdown/yes
+ /global/open/terminal
+ /global/input/keyboard/maps/bind_sym
+ /global/input/keyboard/maps/bind_utf8
+
+Another thing to note is that at startup, after a crash or keyboard
+plug event, a fallback helper is activated. This triggers after a
+number of keypresses that does not activate a valid keybinding. It will
+then query for re-binding key functions,
+(meta keys, global menu, menu navigation) as a means for recovering from
+a broken or unknown keyboard.
+
+You can also reach most paths with a mouse by right- clicking on the
+active workspace indicator on the statusbar.
+
+CONFIGURATION (MANUAL)
+
+There are four ways of configuring durden without using the UI:
+
+1.The arcan_db tool
+
+This works offline (without durden running) and only after first
+successful run. All current settings are stored in a database.
+This can be viewed, and changed, like this:
+
+ arcan_db show_appl durden
+ arcan_db add_appl_kv durden my_key
+
+Or clear all settings and revert to defaults on the next run:
+
+ arcan_db drop_appl durden
+
+This is also used to control which programs (targets) and sets of
+arguments (configuration) durden is allowed to run.
+This restriction is a safety/security measure. Something like:
+
+  arcan_db add_target test BINARY /usr/bin/test arg1
+  arcan_db add_config test default arg2 arg3
+
+Would be added to /global/open/target/test
+
+2.Files
+
+The default settings used on an empty database is found in:
+
+  durden/config.lua
+
+You can also control what is being run at startup in:
+
+  durden/autorun.lua
+
+The first time durden is run, the following script will be run:
+
+  durden/firstrun.lua
+
+Advanced input device configuration is in durden/devmaps for the various
+categories of devices.
+
+3.Controls
+
+Everything can be accessed and controlled (while running) using a domain
+socket.
+This is enabled through the (global/settings/system/control=name) path.
+
+If enabled, it will appear in durden/ipc/name.
+You can use the socat tool to interact with it and control everything as
+if using input in the UI directly.
+
+The commands accepted by this socket is any of
+(ls, readdir, eval, read, write, exec) to navigate the menu tree, as
+well as a 'monitor' command which lets you monitor subsystem activity.
+
+There is also a 'MONITOR' command that lets you monitor one or several
+subsystems.
+
+There is also a tool in arcan that can be built and run, arcan_cfgfs,
+which allows the control socket to be mounted and treated like a
+filesystem.