make event listing more clear

1 files changed, 32 insertions, 91 deletions

diff --git a/README b/README
index f21cb2e..0ec03ba 100644
--- a/README
+++ b/README
@@ -433,7 +433,8 @@ Copying the Uzbl object and creating public functions should be taken with care
 ### EVENTS ###
 
 unlike commands, events are not handled in uzbl itself, but are propagated (dispatched) asynchronously through
-a text stream on stdout.  You'll usually use uzbl by piping it's output to a so called 'event handler'
+a text stream on stdout and/or through a socket.  You'll usually use uzbl by piping it's output to a so called 'event manager'
+or by having the EM listen to a socket.
 - makes it possible to use whichever language you want for event handling (python, perl, bash, .. you name it).
   you'll usually send commands (see above) back to uzbl through its fifo or socket
 - keybindings use x keysyms
@@ -441,102 +442,42 @@ a text stream on stdout.  You'll usually use uzbl by piping it's output to a so
 - see example event_handler.py
 
 Note: cookie events are not sent to an event handler but handled internally through the cookie handler because of their synchronous nature.
-Cookie events are really something completely different from all other events.  maybe someday we'll use http proxies or something for cookies, but
-for now we still use the handler code)
+Cookie events are really something completely different from all other events.  maybe someday we'll use http proxies or something for cookies
+or synchronous events (which also have other nice use cases), but for now we still use the handler code)
 
 Basically all events have this format:
 
      EVENT [uzbl_instance_name] EVENT_NAME event_details
 
 
-Reported events and their specific format:
-
-- on start uzbl will generate:
-
-     EVENT [uzbl_instance_name] INSTANCE_START process_id
-
-- on exit:
-
-     EVENT [uzbl_instance_name] INSTANCE_EXIT process_id
-
-- whenever an uzbl variable is set:
-
-     EVENT [uzbl_instance_name] VARIABLE_SET variable_name str|int|float variable_value
-
-     Note: str|int|float denote the type of variable_value
-
-- upon execution of an uzbl command:
-
-     EVENT [uzbl_instance_name] COMMAND_EXECUTED command_name optional_command_arguments
-
-- when the size or position of the uzbl window changes:
-
-     EVENT [uzbl_instance_name] GEOMETRY_CHANGED WIDTHxHEIGHT+X_POSITION+Y_POSITION
-
-- when the fifo and/or the socket path is set or changed:
-
-     EVENT [uzbl_instance_name] FIFO_SET path_to_fifo
-     EVENT [uzbl_instance_name] SOCKET_SET path_to_socket
-
-- when a website is being loaded:
-
-     EVENT [uzbl_instance_name] LOAD_COMMIT uri
-     EVENT [uzbl_instance_name] LOAD_START uri
-     EVENT [uzbl_instance_name] LOAD_FINISHED uri
-     EVENT [uzbl_instance_name] LOAD_ERROR reason_of_error
-
-- when the title of the uzbl window changes:
-
-     EVENT [uzbl_instance_name] TITLE_CHANGED title_name
-
-- when content needs to be downloaded:
-
-     EVENT [uzbl_instance_name] DOWNLOAD_REQUEST download_uri
-
-- when you hover with the mouse over a link:
-
-     EVENT [uzbl_instance_name] LINK_HOVER uri
-     EVENT [uzbl_instance_name] LINK_UNHOVER uri
-
-- when you press or release a key:
-
-     EVENT [uzbl_instance_name] KEY_PRESS key_name
-     EVENT [uzbl_instance_name] KEY_RELEASE key_name
-
-- when you select some text inside the uzbl window:
-
-     EVENT [uzbl_instance_name] SELECTION_CHANGED selected_text
-
-- when a new uzbl window is created:
-
-     EVENT [uzbl_instance_name] NEW_WINDOW uri
-
-- upon opening/closing of the webinspector window:
-
-     EVENT [uzbl_instance_name] WEBINSPECTOR open
-     EVENT [uzbl_instance_name] WEBINSPECTOR close
-
-- when the uzbl windows gained/lost keyboard focus
-
-     EVENT [uzbl_instance_name] FOCUS_GAINED
-     EVENT [uzbl_instance_name] FOCUS_LOST
-
-- when a editable HTML is clicked
-
-     EVENT [uzbl_instance_name] FORM_ACTIVE
-
-- when the document body or any non-editable element is clicked
-
-     EVENT [uzbl_instance_name] ROOT_ACTIVE
-
-- when the include commands succesfully loads a file
-
-     EVENT [uzbl_instance_name] FILE_INCLUDED /path/to/file
-
-- when uzbl-core is in xembed mode
-
-     EVENT [uzbl_instance_name] PLUG_CREATED plug-id
-
+* Reported events:
+  - `EVENT [uzbl_instance_name] INSTANCE_START process_id`: uzbl startup
+  - `EVENT [uzbl_instance_name] INSTANCE_EXIT process_id`: uzbl shutdown
+  - `EVENT [uzbl_instance_name] VARIABLE_SET variable_name str|int|float variable_value`.  Note: str|int|float denote the type of variable_value
+  - `EVENT [uzbl_instance_name] COMMAND_EXECUTED command_name optional_command_arguments`
+  - `EVENT [uzbl_instance_name] GEOMETRY_CHANGED WIDTHxHEIGHT+X_POSITION+Y_POSITION`: when the size or position of the uzbl window changes
+  - `EVENT [uzbl_instance_name] FIFO_SET path_to_fifo`
+  - `EVENT [uzbl_instance_name] SOCKET_SET path_to_socket`
+  - `EVENT [uzbl_instance_name] LOAD_COMMIT uri`
+  - `EVENT [uzbl_instance_name] LOAD_START uri`
+  - `EVENT [uzbl_instance_name] LOAD_FINISHED uri`
+  - `EVENT [uzbl_instance_name] LOAD_ERROR reason_of_error`
+  - `EVENT [uzbl_instance_name] TITLE_CHANGED title_name`: when the title of the webpage (and hence maybe, the window title) changed
+  - `EVENT [uzbl_instance_name] DOWNLOAD_REQUEST download_uri`: when content needs to be downloaded
+  - `EVENT [uzbl_instance_name] LINK_HOVER uri`: mouse hovers over a link
+  - `EVENT [uzbl_instance_name] LINK_UNHOVER uri`: same but unhover.
+  - `EVENT [uzbl_instance_name] KEY_PRESS key_name`: press of a keyboard key or mouse button
+  - `EVENT [uzbl_instance_name] KEY_RELEASE key_name`: release of keyboard key or mouse button
+  - `EVENT [uzbl_instance_name] SELECTION_CHANGED selected_text`: when you select text inside the uzbl window
+  - `EVENT [uzbl_instance_name] NEW_WINDOW uri`: creation of new uzbl window
+  - `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 gained 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
 
 
 ### COMMAND LINE ARGUMENTS