Docs:xcbXorg: Document apiParams, providerParams and devSelector

Add documentation that explains how to construct a devSpec for matching
and attaching windows from Xorg using the xcbXorg sense API lib.

docs/api-xcb-provider-xorg.md

@@ -0,0 +1,121 @@
+# DeviceSpec: API `xcb`, provider `xorg`
+
+## Overview
+
+The `xcb` API with the `xorg` provider allows Harikoff to interact with Xorg 
+server windows. This can be used to capture visual data from specific windows 
+or entire screens managed by the Xorg server.
+
+## DeviceSpec Format
+
+The general format of a device-spec for the `xcb` API with the `xorg` provider 
+is:
+```
+sensor-type|implexor|xcb(api-params)|xorg(provider-params)|deviceSelector
+```
+
+* `sensor-type` is always either '`+idev`' (interoceptor), '`+edev`' 
+  (extrospector), or '`+adev`' (actuator).
+* `implexor` is the name of the implexor algorithm that should be used with 
+  the data that is provided by the `provider` via the `api`.
+* `api` is `xcb` in this case, and the `api-params` in parentheses may be 
+  omitted, in which case the parentheses will be empty, but the parentheses 
+  must always be written out.
+* `provider` is `xorg` in this case, and the `provider-params` in parentheses 
+  may be omitted, in which case the parentheses will be empty, but the 
+  parentheses must always be written out.
+* `deviceSelector` is the idiosyncratic label/name used by the `provider` to 
+  identify the specific window or screen you want to access via that 
+  `provider`.
+
+## `api-params` and `provider-params`
+
+### `api-params`
+
+The `api-params` for the `xcb` API can include the following:
+
+* `dev-id` or `devid`: Specifies that the `deviceSelector` is a numeric window 
+  ID. The ID can be specified in decimal or hexadecimal format.
+* `dev-string`, `dev-str`, `devstr`, or `devstring`: Specifies that the 
+  `deviceSelector` is an exact window name.
+* `dev-substring`, `dev-substr`, `devsubstr`, or `devsubstring`: Specifies 
+  that the `deviceSelector` is a substring match (default).
+
+Example:
+```
+xcb(dev-id)|123456
+xcb(dev-id)|0x1e240
+xcb(dev-string)|exact-window-name
+xcb(dev-substring)|window-name
+```
+
+### `provider-params`
+
+The `provider-params` for the `xorg` provider can include the following:
+
+* `display`: The display number (e.g., `0` for `:0`).
+* `screen`: The screen number within the display (e.g., `0` for the first 
+  screen).
+
+Example:
+```
+xorg(display=0|screen=0)
+```
+
+## `deviceSelector`
+
+The `deviceSelector` can be one of the following:
+
+* A numeric window ID.
+* A window name (exact match or substring match).
+
+### Matching Types
+
+* By default, the `deviceSelector` is treated as a substring match.
+* To specify an exact match, use the `dev-string` parameter.
+* To specify a numeric window ID, use the `dev-id` parameter.
+
+Example:
+```
+xcb(dev-substring)|window-name
+xcb(dev-string)|exact-window-name
+xcb(dev-id)|123456
+```
+
+## Escaping Whitespace
+
+In `deviceSelector` and other string tokens, whitespace can be included by 
+prefixing it with a backslash (`\`). The backslash will be discarded during 
+parsing.
+
+Example:
+```
+xcb(dev-string)|My\ Exact\ Window\ Name
+```
+
+## Examples
+
+### To attach a specific window by name (substring match):
+```
++edev|visual-implexor|xcb(dev-substring)|xorg(display=0|screen=0)|my-window
+```
+This will attach to a window whose name contains "my-window" as a substring.
+
+### To attach a specific window by exact name:
+```
++edev|visual-implexor|xcb(dev-string)|xorg(display=0|screen=0)|My\ Exact\ Window\ Name
+```
+This will attach to a window whose name exactly matches "My Exact Window Name".
+
+### To attach a specific window by numeric ID:
+```
++edev|visual-implexor|xcb(dev-id)|xorg(display=0|screen=0)|123456
+```
+This will attach to a window with the numeric ID `123456`.
+
+### To attach the entire screen:
+```
++edev|visual-implexor|xcb()|xorg(display=0|screen=0)|all
+```
+This will attach to the entire screen `0` of display `0`.
+