partial upd.

FossilOrigin-Name: 9e71d472019e6fab98c107cddbc576a4e8b4ffdaef1b3ab04ecd4b70577ece5b

browser.md

@@ -21,6 +21,16 @@ the selected item, and use the select (enter) binding to activate.
 Holding meta1 while activating a resource will spawn the resource in the
 background while keeping the menu active.
 
+# Preview Controls
+
+Via get <i>global/settings/browser</i> a number of preview controls are
+exposed. The ones currently available are:
+
+- Preview (image, all or none) changes the types that will be previewed
+- Timer controls how much time that should be elapsed before the preview is activated
+- Position controls video preview starting position
+- Trigger (selection, visibility) controls if preview should be triggered by selection or as soon as a label is visible
+
 # Special Paths
 
 Holding meta1 while pressing ESCAPE will have you go up one level in the
@@ -42,6 +52,5 @@ sorting order.
 - Toggle file details on/off
 - Map client bchunk- hint events to spawn browser for universal
   open/save file-picking
-- Video playback in preview windows
 - Selectable namespace (global or appl-)
 - Extend menu bindings to cover browser paths

ipc.md

@@ -10,22 +10,25 @@ will not be covered here.
 
 ## Control
 
-<i>control</i> can be used to run menu commands. This is slightly dangerous as
-quite a number of menu paths were written with an interactive user in mind.
-Therefore it is also possible to define a custom whitelist (see
-[security](security) so that only benign menu path can be activated externally.
+<i>control</i> is a default-off, unix domain socket that can be used to
+perform external control of the entire desktop. There is a tool in the
+arcan source distribution, arcan\_cfgfs that can be used with FUSE to
+mount the file system so that you can interact with it using the normal
+command-line tools.
 
-control is split into two IPC channels, <i>control</i> and <i>control_out</i>.
+Otherwise, you can write your own tools to communicate via the trivial
+text protocol (commands: ls, read, exec, write, monitor) or use socat
+like:
 
-In addition to allowing normal paths, e.g. #/some/thing/here to be activated,
-there are a few ftp/filesystem like commands that can be used to query the
-current menu state. These are:
+    socat - unix-client:$HOME/.arcan/appl-out/durden/ipc/control
+
+All the commands end with either a single line OK and a linefeed, or
+an error message starting with Exxx.
 
 <i>read /path/to/something</i>
 
-read will write path-specific data to <i>control_out</i>, terminated by a
-single OK line or an EINVAL if the path doesn't exist. Trying to read a
-value that leads to a value entry path would output something like:
+Read simply lists the attributes and, depending on the path, additional
+metadata about a path.
 
     name: myname
     label: Name Field
@@ -34,33 +37,42 @@ value that leads to a value entry path would output something like:
 
 <i>ls /path</i>
 
-ls will write out the contents of a menu directory to <i>control_out</i>,
-terminated by a single OK line or an EINVAL if the path doesn't exist. The
-contents of each entry is simply the name- field of the corresponding menu
-path, with a type specific suffix, / for submenus, = for value paths.
+ls will list the contents of a menu directory, terminated by a single OK
+and linefeed oror an EINVAL if the path doesn't exist.
 
 <i>exec /path/to/action</i>
 
-exec will invoke the currently specified path, writing OK on a single line
-to <i>control_out</i> or EINVAL if the path does not exist or if it points
-to a submenu.
+exec will invoke the currently specified action path.
 
 <i>write /path/to/key=value</i>
 
-write will access the specified path and try to assign it the contents of
-<i>value</i>. It will write OK on a single line to <i>control_out</i> or
-EINVAL if the path does not point to a <i>value</i> entry or if the supplied
-value didn't pass validation.
+write works like <i>exec</i> but is used for value paths, that is paths
+which require a value to be provided in order to work properly.
 
 <i>eval /path/to/key=value</i>
 
-eval works just like <i>write</i> with the exception that the actual
-values are not committed, you only get OK or EINVAL back if the path accepts
-the value in its current form or not.
+### Monitor Mode
+
+The command 'monitor' is special, as it will change the state of the connection
+to only accept monitor commands. These are used to listen to one or many of the
+event subsystems that make out the core of durden.
+
+    monitor all
+
+Will become very noisy, whileas:
+
+    monitor wm
+
+Will only show window manager events. To get a list of currently available groups
+simply call monitor without any arguments and the list will be returned in the
+following EINVAL error message.
+
+The second monitor command disable monitoring and returns the connection back to
+a normal state.
 
 ## Output
 
-<i>output</i> is used to convey custom messages, like when a user-defined
+<i>output</i> is a FIFO used to convey custom messages, like when a user-defined
 statusbar button is clicked. There is also a hidden menu path (=bind only) that
 allows you to pass a custom message to the output channel. This path can be
 found at <i>global/system/output_msg</i>.

menu.md

@@ -3,7 +3,7 @@ layout: default
 ---
 
 'The Menu' is a key feature in Durden, where all the internal features are
-exposed and controlled. Underneath the surface, the menu covers two directory
+exposed and controlled. Underneath the surface, the menu covers two primary
 trees (one 'global' and one 'target') where each entry describes either
 a subdirectory, an action or a key/value input. The global tree convers system
 wide settings, and the target tree covers the currently selected window.
@@ -31,25 +31,20 @@ not.
 
 Underneath the surface, these paths are evaluated like this:
 
-    !open/target
-    #clipboard/paste
-    !settings/visual/mouse_scale=5
+    /global/open/target
+    /target/clipboard/paste
+    /global/settings/visual/mouse_scale=5
 
-With \! being used to pick the global directory, and the \# for the target
-directory. The =5 in the example above is a binding to setting a specific
-key/value pair (here, setting the mouse cursor scale factor to 5).
-
-<b>All the path references in the documentation or elsewhere points to a
-logic 'name' which may be different from the language- specific 'label' that
-is presented when navigating the UI.</b>
+The =5 in the example above is a binding to setting a specific key/value pair
+(here, setting the mouse cursor scale factor to 5).
 
 Due to key naming restrictions, paths currently bound to custom keys will
 have a slightly diffferent format in the database. Inspecting them will look
 something like this:
 
-    arcan_db show_appl durden |grep cust
-       custg_m1_m2_p=workspace/switch
-       custs_m1_h=clipboard/paste
+    arcan_db show_appl durden |grep custom
+       custom_m1_m2_p=/global/workspace/switch
+       custom_m1_h=/target/clipboard/paste
 
 ## Navigation
 
@@ -76,15 +71,16 @@ not (red like in the screenshot).
 ## Binding Keys
 
 Though this falls under normal input management, there is a special feature
-worth noting in this context. When making a new binding by going to Input/
-Bind/Custom, you will be prompted to pick the menu path to bind.
+worth noting in this context. When making a new binding by going to
+/global/input/bind/custom, you will be prompted to pick the menu path to bind.
+
+If you select an action, there's nothing complicated going on - that particular
+action will be bound. If you select a key/value target, the default is that the
+value you entered will be the actually bound value but if you hold META1 when
+selecting the entry, the actual dialog prompt will be bound instead.
 
-If you select an action, there's nothing complicated going on - that
-particular action will be bound. If you select a key/value target, you can
-chose between binding the dialog itself or the specific value you enter by
-holding META1 when pressing SELECT to activate the dialog. In a similar way,
-you can bind activating a subdirectory by holding META1 pressed when pressing
-SELECT.
+In a similar fashion, you can also bind the navigation directory itself
+by holding META1 when pressing SELECT.
 
 ## Widgets <a name="widgets"></a>
 
@@ -94,8 +90,8 @@ during startup (see the .lua files in the widgets subpath) that explicitly
 binds their activation to certain paths and patterns.
 
 These are used to provide extra information, like the ASCII- table shown when
-going for "Input/Keyboard/Map/Bind-UTF8" and the list of keybindings shown when
-going for "Input/Bind/Custom" like in the screenshot below:
+going for "global/input/keyboard/map/bind_utf8" and the list of keybindings
+shown when going for "global/input/bind/custom" like in the screenshot below:
 
 <center><a href="images/widget.png">
 	<img alt="widget screenshot" src="images/widget.png" style="width: 50%"/>
@@ -107,54 +103,23 @@ by dropping a txt file in the widgets/cheatsheets path. The first line of the
 file is a lua pattern that will match against the identity of the window, and
 new groups are indiciated with an empty line.
 
-There is also the experimental option to run external widgets. When a client
-connects to arcan, it registers a type for its primary segment, and durden
-gives special treatment based on advertised type. A 'Game' segment, for
-instance, would get access to different input routing paths.
+## Multicast
 
-There is a 'Widget' type where subsegments, clipboards and other features are
-disabled. These gets forced to a maximum size, and are routed to the global
-menu. To write such a client is a little bit of work, though Arcan has a
-support layer (also Lua scriptable) as part of the 'TUI' (text-UI) subsystem.
-Refer to the Arcan wiki for more on this feature.
+There is also a way to emit the same /target path to a group of windows by
+using any of the available subpaths to /windows, where you can affect all
+windows, windows of a specific type and so on.
 
 ## Advanced
 
-Since many advanced menu features rely on figuring out a particular path,
-it would be convenient to be able to quickly enumerate the list of possible
-options, particularly since the logical path used for a binding will likely
-differ from the visual labels you see due to internationalization.
-
-If you use the following special command:
-
-     arcan durden dump_menus
-
-Durden will write the accessible global menu tree to stdout, and the target
-tree for a 'standard/null' window (so window type specific entries will not
-be shown). You can then use that dump to better define your bindings.
-An example of such a dump can be found [here](menus.txt).
-
-However, this dump will not be very accurate, as the menus are dynamically
-generated and regenerated based on what the available hardware and the
-selected window can do _currently_.
-
-For some menu paths, your only options are to read the source code (the
-menu entries are not particularly hard to read as they are mostly small
-tables with well known fields), and to increasing the debuglevel further
-(-g -g).
-
-Some menu entries are also marked as 'invisible'. This means that they
-are only shown when you are interactively binding a menu path to a key.
-The reason for this may be that they serve no purpose when a UI is inactive,
-or accidentaly activating them would yield in some dangerous state
-transition - like toggling displays on/off.
+It is also possible to mount the menu tree as a real filesystem, though with
+some performance drawbacks at the moment. See the separate 'arcan-cfgfs' tool
+that comes with your distribution or as part of the <i>src/tools/acfgfs</i>
+path in the arcan source repository, along with the section on [ipc](ipc).
 
 ## Coming Features
 The following changes are planned for the menu:
 
- - Mouse and touchpad gesture navigation
  - Mouse Cursor warping to reduce movement
- - Tooltips for each entry
  - Better Widget- area layouting
  - Client- provided menus merged into target- group
- - "Popup"- style for floating layout mode
+ - Alternative representations: radial menu, popup, ...

statusbar.md

@@ -17,13 +17,13 @@ as workspaces gets tagged or if a window on a workspace alerts for attention.
 Each display gets its own statusbar, though the behavior settings apply globally.
 
 # Tuning
-Statusbar specific settings can be found at <i>global/config/statusbar</i> and
+Statusbar specific settings can be found at <i>global/settings/statusbar</i> and
 covers some visual properties (position, sizing / padding), presence of dynamic
 buttons and if it should only be active when the HUD is, or not.
 
 Other visual settings are part of the shader subsystem and can be found in
-<i>global/config/shaders/UI</i>, while some text positioning options that apply
-to both titlebar and statusbar are at <i>global/config/bars</i>.
+<i>global/settings/visual/shaders/UI</i>, while some text positioning options that apply
+to both titlebar and statusbar are at <i>global/settings/visual/bars</i>.
 
 # Layout button
 The first button indicates the current layouting mode for the active workspace,

terminal.md

@@ -17,7 +17,7 @@ and other controls via the [input labels](input) system.
 Most changes to the visual configuration are activated globally and immediately,
 and cover properties like the active font, fallback/alternate glyph source,
 font size, background opacity and so on. These properties can be be accessed
-through the <i>global/config/terminal</i> menu path.
+through the <i>global/settings/terminal</i> menu path.
 
 The default settings and behavior for the terminal archetype can be low-level
 inspected via the <i>durden/atypes/terminal.lua</i> source.

tools.md

@@ -12,7 +12,7 @@ Menu HUD.
 The included tools are:
 [Model Viewer](#model), [Dropdown Terminal](#dropdown)
 [Autolayouter](autolay), [Advanced Float](#advfloat), [Overview](#overview),
-[Flair](#flair) and the [Overlay](#overlay).
+[Flair](#flair),[Overlay](#overlay) and [VRViewer](#vrviewer).
 
 # Dropdown Terminal <a name="dropdown"/>
 
@@ -153,9 +153,18 @@ a background image to be set.
 The tool is easily extendable by modifying the scripts in the tools/flair
 subfolder.
 
+# VRViewer <a name="vrviewer"/>
+
+The VR viewer tool shares much of its setup and structure with that of the separate
+DE (<a href="https://github.com/letoram/safespaces">Safespaces</a>. Its primary
+role here is to act as a data viewer rather than a DE within a DE.
+
+Its menu structure is deep and rather complicated, and it is better to look at the
+default spaces (tools/vr
+
 # Future Changes
 - On-screen Keyboard
 - Touchpad Configuration
-- VR support for model viewer
 - Notification Agents
+- Gesture Analyzer
 - Composition Surface for sharing/recording

widgets.md

@@ -57,7 +57,15 @@ line. Colors are chosen by stepping through the palette defined in
 	<img alt="cheat-sheet" src="images/cheat.png" style="width: 50%"/>
 </a></center>
 
+# Input
+The input widget is activated via the <i>target/input</i> path, but only if
+a client has announced any input labels. If so, the logical name will be shown
+as the widget helper text. Clicking on a label will send a press/release pair
+of that specific input label to the client.
+
 # Future Changes
+- Support for enabling / disabling specific widgets
+- Override and remember widget positioning
 - External clients with "WIDGET" primary segid
 - Widget for analog input filter tuning
 - Widget for color picking