Begin documenting EM requests.

Finished "BIND" and "MODE_BIND" so far.

Signed-off-by: Dan Hackney <dan@haxney.org>

1 files changed, 45 insertions, 43 deletions

diff --git a/README b/README
index bb661f2..4482fcf 100644
--- a/README
+++ b/README
@@ -433,55 +433,57 @@ Basically all events have this format:
 * `EVENT [uzbl_instance_name] WEBINSPECTOR open`: Upon opening webinspector window.
 * `EVENT [uzbl_instance_name] WEBINSPECTOR close`: Upon closing webinspector window.
 * `EVENT [uzbl_instance_name] FOCUS_GAINED`: When `uzbl` window gains keyboard focus.
-* `EVENT [uzbl_instance_name] FOCUS_LOST`: when uzbl window lost keyboard focus
-* `EVENT [uzbl_instance_name] FORM_ACTIVE`: when a editable HTML is clicked
-* `EVENT [uzbl_instance_name] ROOT_ACTIVE`: when the document body or any non-editable element is clicked
-* `EVENT [uzbl_instance_name] FILE_INCLUDED /path/to/file`: when the include commands succesfully loads a file
-* `EVENT [uzbl_instance_name] PLUG_CREATED plug-id`: when uzbl-core is in xembed mode
-* `EVENT [uzbl_instance_name] BUILTINS command_list`: shows a list of all uzbl commands, whitespace separated, on startup
-
-* Events/requests which the EM and its plugins listens for:
-  - `BIND` and `MODE_BIND`: define global resp. per-mode key/button binds.
-    `request BIND <keycmd> = <command>` # set global binding (this is a shortcut for `request MODE_BIND global <keycmd> = <command>`)
-    `request MODE_BIND <modespec> <keycmd> = <command>`
-    The `<modespec>` can be anything like 'command', 'insert,command', 'global', 'global,-insert'.
-    The `<keycmd>` has a special syntax:
-       * `<keycmd>` ends with an underscore: the command will only be invoked after pressing return/enter. If the user enters text where `<string>` has the underscore, `%s` in the `<command>` string will be replaced by this text. (optional)
-       * `<keycmd>` ends with an asterisk: similar behavior as with an underscore, but also makes the binding incremental (i.e. the command will be invoked on every keystroke).
-       * `<keycmd>` ends with an '!': the command will only be invoked after pressing return/enter, no replacement happens. this is useful for preventing 'x' to match when you want to bind 'xx' also.
-       * `<keycmd>` ends on a different character: you need to type the full string, which will trigger the command immediately, without pressing enter/return.
-       * TODO explain stacked bindings and multi-stage (is that the same?) and what else am i missing? modkeys, showing a prompt mid-bind.
-    The `<keycmd>` can be any representation of a key on your keyboard or a mousebutton. (note: not all mousebuttons work correctly yet)
-    examples:
-       * `event BIND o _ = uri %s`
-         - uzbl will load the url when you type: 'o <url><enter>'
-       * `event BIND /*  = search %s`
-         - a search command which is called on every character typed after the slash, letting you see the search narrow down while typing.
-         - Hitting return, enter or esc will terminate the search.
-       * `event BIND ZZ  = exit`
-         - When you type `ZZ` and nothing else, the exit command will be triggered immediately.
-  - `MODE_CONFIG`: ??
-     request MODE_CONFIG <mode> <key> = <value
-  - `ON_EVENT`: allows you to bind misc commands to misc events
+* `EVENT [uzbl_instance_name] FOCUS_LOST`: When `uzbl` window loses keyboard focus.
+* `EVENT [uzbl_instance_name] FORM_ACTIVE`: When an editable HTML is clicked.
+* `EVENT [uzbl_instance_name] ROOT_ACTIVE`: When the document body or any non-editable element is clicked.
+* `EVENT [uzbl_instance_name] FILE_INCLUDED filename`: When the `include` commands successfully loads a file, given by `filename`.
+* `EVENT [uzbl_instance_name] PLUG_CREATED plug_id`: When `uzbl-core` is in Xembed mode, `plug_id` is the Xembed ID used.
+* `EVENT [uzbl_instance_name] BUILTINS command_list`: Shows a list of all `uzbl` commands, whitespace separated, on startup.
+
+Events/requests which the EM and its plugins listens for
+
+* `BIND` and `MODE_BIND`: define global resp. per-mode key/button binds.
+    - `request BIND <keycmd> = <command>` Set global binding (this is a shortcut for `request MODE_BIND global <keycmd> = <command>`).
+    - `request MODE_BIND <modespec> <keycmd> = <command>` Set a local binding for `<modespec>`. The `<modespec>` can be anything like `command`, `insert,command`, `global`, `global,-insert`.
+
+  The `<keycmd>` has a special syntax:
+    - `<keycmd>` ends with an `_`: the command will only be invoked after pressing return/enter. If the user enters text where `<string>` has the underscore, `%s` in the `<command>` string will be replaced by this text (optional).
+    - `<keycmd>` ends with an `*`: similar behavior as with an underscore, but also makes the binding incremental (i.e. the command will be invoked on every keystroke).
+    - `<keycmd>` ends with an `!`: the command will only be invoked after pressing return/enter, no replacement happens. this is useful for preventing `x` to match when you want to bind `xx` also.
+    - `<keycmd>` ends on a different character: you need to type the full string, which will trigger the command immediately, without pressing enter/return.
+    - TODO explain stacked bindings and multi-stage (is that the same?) and what else am i missing? modkeys, showing a prompt mid-bind.
+
+  The `<keycmd>` can be any representation of a key on your keyboard or a mousebutton. (note: not all mousebuttons work correctly yet). Examples:
+
+    - `event BIND o _ = uri %s`
+      - `uzbl` will load the url when you type: `o <url><enter>`
+    - `event BIND /*  = search %s`
+      - A `search` command which is called on every character typed after the slash, letting you see the search narrow down while typing.
+      - Hitting return, enter or esc will terminate the search.
+    - `event BIND ZZ  = exit`
+      - When you type `ZZ` and nothing else, the `exit` command will be triggered immediately.
+* `MODE_CONFIG`: ??
+     request MODE_CONFIG <mode> <key> = <value>
+* `ON_EVENT`: allows you to bind misc commands to misc events
      request ON_EVENT <EVENT_NAME> <command>
-  - `PROGRESS_CONFIG`
+* `PROGRESS_CONFIG`
      request PROGRESS_CONFIG <key> = <value>
-  - `MODMAD`
+* `MODMAD`
      request MODMAP From To
-  - `IGNORE_KEY`
+* `IGNORE_KEY`
      request IGNORE_KEY <glob>
-  - `MODKEY_ADDITION`
+* `MODKEY_ADDITION`
      request MODKEY_ADDITION <key1> <key2> <keyn> <result>
-  - `TOGGLE_MODES`
+* `TOGGLE_MODES`
      event TOGGLE_MODES <mode1> <mode2> ... <moden>
-  - `APPEND_KEYCMD`: append `<string> to keycmd
-  - `INJECT_KEYCMD <string>`: replace keycmd by `<string>`
-  - `KEYCMD_DELETE`
-  - `KEYCMD_STRIP_WORD`
-  - `KEYCMD_EXEC_CURRENT`: (tries to) execute whatever is in the keycmd
-  - `SET_KEYCMD`
-  - `SET_CURSOR_POS`
-  - `START_COMPLETION`: TODO explain completion
+* `APPEND_KEYCMD`: append `<string> to keycmd
+* `INJECT_KEYCMD <string>`: replace keycmd by `<string>`
+* `KEYCMD_DELETE`
+* `KEYCMD_STRIP_WORD`
+* `KEYCMD_EXEC_CURRENT`: (tries to) execute whatever is in the keycmd
+* `SET_KEYCMD`
+* `SET_CURSOR_POS`
+* `START_COMPLETION`: TODO explain completion