add description for (most) event handlers

docs/include-cmd-scripting.rst

@@ -199,17 +199,35 @@
 `event.*` commands
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+rTorrent events are merely :ref:`multi commands <multi-type>`
+that are called automatically when certain things happen,
+like completion of a download item.
+
+You can trigger them manually by calling them on selected items (e.g. via ``rtxmlrpc``).
+Make sure though that the registered handlers do not have adverse effects when called repeatedly,
+i.e. know what you're doing.
+
+The handlers for an event can be listed like so:
+
+.. code-block:: bash
+
+    rtxmlrpc --repr method.get '' event.download.finished
+
+Note that practically all the events have pre-registered system handlers,
+often starting with a digit, ``!``, or ``~``, for ordering reasons.
+
+
 .. glossary::
 
     event.download.closed
     event.download.opened
 
-        **TODO**
+        Download item was closed / opened.
 
     event.download.paused
     event.download.resumed
 
-        **TODO**
+        Download item was paused / resumed.
 
     event.download.hash_done
     event.download.hash_failed
@@ -226,15 +244,17 @@
     event.download.inserted_new
     event.download.inserted_session
 
-        **TODO**
+        ``inserted`` is *always* called when an item is added to the main downloads list.
+        After that, ``inserted_session`` is called when the source of that item is the session state (on startup),
+        or else ``inserted_new`` is called for items newly added via a ``load`` command.
 
     event.download.finished
 
-        **TODO**
+        Download item is complete.
 
     event.download.erased
 
-        **TODO**
+        Download item was removed.
 
     event.view.hide
     event.view.show

docs/scripting.rst

@@ -135,6 +135,8 @@ If a command is ``private``, it can only be called from within rTorrent, but not
 **TODO** static?!
 
 
+.. _basic-type:
+
 value, bool, string, list (subtypes: static, private, const)
    These are the standard object types, ``value`` is an integer,
    and ``bool`` just a convention of using the integer values ``0`` for :term:`false` and ``1`` for true.
@@ -146,6 +148,9 @@ value, bool, string, list (subtypes: static, private, const)
 
         :term:`method.insert.value`
 
+
+.. _simple-type:
+
 simple (subtypes: static, private, const)
    Simple commands are defined once and cannot be changed dynamically like ``multi`` ones.
    They can still contain a sequence of several commands in a given order,
@@ -170,6 +175,9 @@ simple (subtypes: static, private, const)
 
         :term:`method.insert.simple`
 
+
+.. _multi-type:
+
 multi (subtypes: static, private, const, rlookup)
    A multi command is an array of ``simple`` commands, indexed by a name.
    When you call a multi command, the sequence is executed in order of the keys