docs: Move event documentation to the events section

This was a bit awkward in the function page.

doc_src/cmds/function.rst

@@ -54,19 +54,7 @@ The following options are available:
 
 If the user enters any additional arguments after the function, they are inserted into the environment :ref:`variable list <variables-lists>` ``$argv``. If the ``--argument-names`` option is provided, the arguments are also assigned to names specified in that option.
 
-By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the :doc:`emit <emit>` builtin. Fish generates the following named events:
-
-- ``fish_prompt``, which is emitted whenever a new fish prompt is about to be displayed.
-
-- ``fish_preexec``, which is emitted right before executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.
-
-- ``fish_posterror``, which is emitted right after executing a command with syntax errors. The commandline is passed as the first parameter.
-
-- ``fish_postexec``, which is emitted right after executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.
-
-- ``fish_exit`` is emitted right before fish exits.
-
-- ``fish_cancel``, which is emitted when a commandline is cleared (used for terminal-shell integration).
+The event handler switches (``on-event``, ``on-variable``, ``on-job-exit``, ``on-process-exit`` and ``on-signal``) cause a function to run automatically at specific events. New named events for ``--on-event`` can be fired using the :doc:`emit <emit>` builtin. Fish already generates a few events, see :ref:`event` for more.
 
 Functions may not be named the same as a reserved keyword. These are elements of fish syntax or builtin commands which are essential for the operations of the shell. Current reserved words are ``[``, ``_``, ``and``, ``argparse``, ``begin``, ``break``, ``builtin``, ``case``, ``command``, ``continue``, ``else``, ``end``, ``eval``, ``exec``, ``for``, ``function``, ``if``, ``not``, ``or``, ``read``, ``return``, ``set``, ``status``, ``string``, ``switch``, ``test``, ``time``, and ``while``.
 

doc_src/language.rst

@@ -1747,6 +1747,35 @@ To specify a signal handler for the WINCH signal, write::
         echo Got WINCH signal!
     end
 
+Fish already the following named events for the ``--on-event`` switch:
+
+- ``fish_prompt`` is emitted whenever a new fish prompt is about to be displayed.
+
+- ``fish_preexec`` is emitted right before executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.
+
+- ``fish_posterror`` is emitted right after executing a command with syntax errors. The commandline is passed as the first parameter.
+
+- ``fish_postexec`` is emitted right after executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.
+
+- ``fish_exit`` is emitted right before fish exits.
+
+- ``fish_cancel`` is emitted when a commandline is cleared.
+
+Events can be fired with the :doc:`emit <cmds/emit>` command, and do not have to be defined before. The names just need to match. For example::
+
+  function handler --on-event imdone
+      echo generator is done $argv
+  end
+
+  function generator
+      sleep 1
+      # The "imdone" is the name of the event
+      # the rest is the arguments to pass to the handler
+      emit imdone with $argv
+  end
+
+If there are multiple handlers for an event, they will all be run, but the order might change between fish releases, so you should not rely on it.
+
 Please note that event handlers only become active when a function is loaded, which means you need to otherwise :doc:`source <cmds/source>` or execute a function instead of relying on :ref:`autoloading <syntax-function-autoloading>`. One approach is to put it into your :ref:`configuration file <configuration>`.
 
 For more information on how to define new event handlers, see the documentation for the :doc:`function <cmds/function>` command.