Doku fuer Hooks
Hook-Funktionen und weitere Libhooks.
Ausserdem ein paar Typos und Klarstellungen in aelteren Manpages zu
Libhooks.
Change-Id: I27de063d852ccb3971379503ab041682d711be9c
diff --git a/doc/libhooks/H_HOOK_ALCOHOL b/doc/libhooks/H_HOOK_ALCOHOL
new file mode 100644
index 0000000..de14a58
--- /dev/null
+++ b/doc/libhooks/H_HOOK_ALCOHOL
@@ -0,0 +1,45 @@
+H_HOOK_ALCOHOL
+==============
+
+HOOK
+----
+
+ H_HOOK_ALCOHOL
+
+DEFINIERT IN
+------------
+
+ /sys/hook.h
+
+GERUFEN VON
+-----------
+
+ /std/living/life.c
+
+BESCHREIBUNG
+------------
+
+ Wird bei Veraenderung von P_ALCOHOL im Lebewesen ausgegeben. Aenderung der
+ Daten und Abbruch sind moeglich.
+ Wenn eine Set-Methode auf P_ALCOHOL existiert, kann das Ausloesen des Hooks
+ verhindert werden.
+
+HOOK-DATEN
+----------
+
+ int alcohol
+ Der Neue Wert der Property.
+
+RUECKGABEWERTE
+--------------
+
+ ({ <status>, <daten> })
+ <status> : H_NO_MOD, H_ALTERED, H_CANCELLED
+ <daten> : int alcohol
+
+SIEHE AUCH
+----------
+
+ HRegisterToHook(), HUnregisterFromHook(), HookFlow(), P_ALCOHOL
+
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/libhooks/H_HOOK_CONSUME b/doc/libhooks/H_HOOK_CONSUME
index 0394b86..ef91f23 100644
--- a/doc/libhooks/H_HOOK_CONSUME
+++ b/doc/libhooks/H_HOOK_CONSUME
@@ -3,6 +3,7 @@
HOOK
----
+
H_HOOK_CONSUME
DEFINIERT IN
@@ -31,6 +32,8 @@
BEMERKUNGEN
-----------
+ testonly kann durch den Hook nicht veraendert werden.
+
Die in "man consume" erwaehnte alte Form des Mappings wird leider noch
benutzt, Stand heute (16.02.2018) u.A. von /std/pub. Beruecksichtigt das
in eurem Code.
@@ -47,4 +50,4 @@
HRegisterToHook(), HUnregisterFromHook(), HookFlow(), consume()
-Letzte Aenderung: 16.02.2018, Bugfix
+Letzte Aenderung: 06.10.2018, Bugfix
diff --git a/doc/libhooks/H_HOOK_DEFEND b/doc/libhooks/H_HOOK_DEFEND
new file mode 100644
index 0000000..6e69c7f
--- /dev/null
+++ b/doc/libhooks/H_HOOK_DEFEND
@@ -0,0 +1,55 @@
+H_HOOK_DEFEND
+=============
+
+HOOK
+----
+
+ H_HOOK_DEFEND
+
+DEFINIERT IN
+------------
+
+ /sys/hook.h
+
+GERUFEN VON
+-----------
+
+ /std/living/combat.c
+
+BESCHREIBUNG
+------------
+
+ Wird im Defend() eines Lebewesens ausgeloest. Es ist moeglich das Defend()
+ abzubrechen oder die Daten zu veraendern.
+ Dieser Hook kommt nach der Auswertung von P_TMP_DEFEND_HOOK zum Zuge, kann
+ also auch die durch diesen modifizierten Daten aendern.
+ Die Daten des Legacy-Hooks stehen, sofern vorhanden, in
+ spell[EINFO_DEFEND][DEFEND_HOOK].
+
+ Insb. wird dieser Hook aber auch erst nach Abfrage der Defender
+ ausgefuehrt. Von diesen sind evtl. bereits Meldungen ausgegeben worden,
+ auch wenn das Defend() an dieser Stelle vom Hook abgebrochen wird.
+
+ Parierwaffen, Ruestungen und Skills kommen erst nach dem Hook zum Zug.
+
+HOOK-DATEN
+----------
+
+ Es wird ein array uebergeben.
+ ({int dam, string* dam_type, mapping spell, object enemy})
+ Die Werte sind bereits normalisiert D.h., eine Ueberpruefung auf korrekte
+ Datentypen ist hier ueberfluessig.
+
+RUECKGABEWERTE
+--------------
+
+ ({ <status>, <daten> })
+ <status> : H_NO_MOD, H_CANCELLED, H_ALTERED
+ <daten> : wie uebergebenes Datenarray
+
+SIEHE AUCH
+----------
+
+ HRegisterToHook(), HUnregisterFromHook(), HookFlow(), Defend()
+
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/libhooks/H_HOOK_DIE b/doc/libhooks/H_HOOK_DIE
new file mode 100644
index 0000000..7e10882
--- /dev/null
+++ b/doc/libhooks/H_HOOK_DIE
@@ -0,0 +1,45 @@
+H_HOOK_DIE
+==========
+
+HOOK
+----
+
+ H_HOOK_DIE
+
+DEFINIERT IN
+------------
+
+ /sys/hook.h
+
+GERUFEN VON
+-----------
+
+ /std/living/life.c
+
+BESCHREIBUNG
+------------
+
+ Wird im die() eines Lebewesens ausgeloest. Es ist moeglich das die()
+ abzubrechen oder die Daten zu veraendern.
+
+HOOK-DATEN
+----------
+
+ Es wird ein Array uebergeben:
+ ({poisondeath})
+
+ - poisondeath: Ist das Lebewesen an Gift gestorben?
+
+RUECKGABEWERTE
+--------------
+
+ ({ <status>, <daten> })
+ <status> : H_NO_MOD, H_CANCELLED, H_ALTERED
+ <daten> : wie uebergebenes Datenarray
+
+SIEHE AUCH
+----------
+
+ HRegisterToHook(), HUnregisterFromHook(), HookFlow(), die()
+
+Letzte Aenderung: 05.10.2022, Bugfix
diff --git a/doc/libhooks/H_HOOK_DRINK b/doc/libhooks/H_HOOK_DRINK
new file mode 100644
index 0000000..f0d104d
--- /dev/null
+++ b/doc/libhooks/H_HOOK_DRINK
@@ -0,0 +1,45 @@
+H_HOOK_DRINK
+============
+
+HOOK
+----
+
+ H_HOOK_DRINK
+
+DEFINIERT IN
+------------
+
+ /sys/hook.h
+
+GERUFEN VON
+-----------
+
+ /std/living/life.c
+
+BESCHREIBUNG
+------------
+
+ Wird bei Veraenderung von P_DRINK im Lebewesen ausgegeben. Aenderung der
+ Daten und Abbruch sind moeglich.
+ Wenn eine Set-Methode auf P_DRINK existiert, kann das Ausloesen des Hooks
+ verhindert werden.
+
+HOOK-DATEN
+----------
+
+ int drink
+ Der Neue Wert der Property.
+
+RUECKGABEWERTE
+--------------
+
+ ({ <status>, <daten> })
+ <status> : H_NO_MOD, H_ALTERED, H_CANCELLED
+ <daten> : int drink
+
+SIEHE AUCH
+----------
+
+ HRegisterToHook(), HUnregisterFromHook(), HookFlow(), P_DRINK
+
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/libhooks/H_HOOK_FOOD b/doc/libhooks/H_HOOK_FOOD
new file mode 100644
index 0000000..dff8110
--- /dev/null
+++ b/doc/libhooks/H_HOOK_FOOD
@@ -0,0 +1,45 @@
+H_HOOK_FOOD
+===========
+
+HOOK
+----
+
+ H_HOOK_FOOD
+
+DEFINIERT IN
+------------
+
+ /sys/hook.h
+
+GERUFEN VON
+-----------
+
+ /std/living/life.c
+
+BESCHREIBUNG
+------------
+
+ Wird bei Veraenderung von P_FOOD im Lebewesen ausgegeben. Aenderung der
+ Daten und Abbruch sind moeglich.
+ Wenn eine Set-Methode auf P_FOOD existiert, kann das Ausloesen des Hooks
+ verhindert werden.
+
+HOOK-DATEN
+----------
+
+ int food
+ Der Neue Wert der Property.
+
+RUECKGABEWERTE
+--------------
+
+ ({ <status>, <daten> })
+ <status> : H_NO_MOD, H_ALTERED, H_CANCELLED
+ <daten> : int food
+
+SIEHE AUCH
+----------
+
+ HRegisterToHook(), HUnregisterFromHook(), HookFlow(), P_FOOD
+
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/libhooks/H_HOOK_HP b/doc/libhooks/H_HOOK_HP
index e80791f..5cbae10 100644
--- a/doc/libhooks/H_HOOK_HP
+++ b/doc/libhooks/H_HOOK_HP
@@ -5,15 +5,17 @@
/sys/hook.h
AUSGELOeST VON:
- /std/living/life.c
+ /std/player/life.c
BESCHREIBUNG:
Wird ausgeloest, wenn sich die P_HP eines Spielers aendern.
Dieser Hook laeuft nach der Aenderung der Lebenspunkte. Es ist nicht
moeglich, diesen Hook abzubrechen oder die Lebenspunkte zu aendern.
+ Eine Set-Methode auf P_HP kann das Ausloesen des Hooks verhindern.
EVENT-DATEN:
- Es werden die neuen Lebenspunkte des Spielers uebergebe.
+ int hp
+ Die neuen Lebenspunkte des Spielers.
RUeCKGABEWERTE:
({ <status>, <daten> })
@@ -24,5 +26,5 @@
HRegisterToHook(), HUnregisterFromHook(), HookFlow()
-----------------------------------------------------------------------------
-7.2.2016, Zesstra
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/libhooks/H_HOOK_INIT b/doc/libhooks/H_HOOK_INIT
new file mode 100644
index 0000000..75fefd0
--- /dev/null
+++ b/doc/libhooks/H_HOOK_INIT
@@ -0,0 +1,46 @@
+H_HOOK_INIT
+===========
+
+HOOK
+----
+
+ H_HOOK_INIT
+
+DEFINIERT IN
+------------
+
+ /sys/hook.h
+
+GERUFEN VON
+-----------
+
+ /std/room.c
+
+BESCHREIBUNG
+------------
+
+ Wird im init() eines Raumes ausgeloest. Es ist moeglich den Hook
+ abzubrechen.
+
+ANMERKUNG
+---------
+
+ ACHTUNG: Ein Abbruch des init() kann zu schweren Bugs fuehren.
+
+HOOK-DATEN
+----------
+
+ keine
+
+RUECKGABEWERTE
+--------------
+
+ ({ <status> })
+ <status>: H_NO_MOD, H_CANCELLED
+
+SIEHE AUCH
+----------
+
+ HRegisterToHook(), HUnregisterFromHook(), HookFlow()
+
+Letzte Aenderung: 06.10.2002, Bugfix
diff --git a/doc/libhooks/H_HOOK_INSERT b/doc/libhooks/H_HOOK_INSERT
new file mode 100644
index 0000000..f334d99
--- /dev/null
+++ b/doc/libhooks/H_HOOK_INSERT
@@ -0,0 +1,43 @@
+H_HOOK_INSERT
+=============
+
+HOOK
+----
+
+ H_HOOK_INSERT
+
+DEFINIERT IN
+------------
+
+ /sys/hook.h
+
+GERUFEN VON
+-----------
+
+ /std/player/restrictions.c
+
+BESCHREIBUNG
+------------
+
+ Wird ausgeloest, wenn ein Gegenstand ins Inventar eines Spielers bewegt
+ wird. Es ist nicht moeglich, diesen Hook abzubrechen oder die Daten zu
+ veraendern.
+
+HOOK-DATEN
+----------
+
+ object ob
+ Das eingefuegt Objekt.
+
+RUECKGABEWERTE
+--------------
+
+ ({ H_NO_MOD, <daten> })
+ <daten> : Das eingefuegte Objekt
+
+SIEHE AUCH
+----------
+
+ HRegisterToHook(), HUnregisterFromHook(), HookFlow()
+
+Letzte Aenderung: 06.10.2002, Bugfix
diff --git a/doc/libhooks/H_HOOK_MOVE b/doc/libhooks/H_HOOK_MOVE
index c521a95..9ed1326 100644
--- a/doc/libhooks/H_HOOK_MOVE
+++ b/doc/libhooks/H_HOOK_MOVE
@@ -19,8 +19,9 @@
BESCHREIBUNG
------------
- Wird im move() eines Lebewesens ausgeloest. Es ist moeglich das move()
- abzubrechen oder die Daten zu veraendern.
+ Wird im move() eines Lebewesens ausgeloest, **bevor** die Bewegung
+ stattgefunden hat. Es ist moeglich das move() abzubrechen oder die Daten zu
+ veraendern.
HOOK-DATEN
----------
diff --git a/doc/libhooks/H_HOOK_POISON b/doc/libhooks/H_HOOK_POISON
new file mode 100644
index 0000000..cf0cedc
--- /dev/null
+++ b/doc/libhooks/H_HOOK_POISON
@@ -0,0 +1,45 @@
+H_HOOK_POISON
+=============
+
+HOOK
+----
+
+ H_HOOK_POISON
+
+DEFINIERT IN
+------------
+
+ /sys/hook.h
+
+GERUFEN VON
+-----------
+
+ /std/living/life.c
+
+BESCHREIBUNG
+------------
+
+ Wird bei Veraenderung von P_POISON im Lebewesen ausgegeben. Aenderung der
+ Daten und Abbruch sind moeglich.
+ Wenn eine Set-Methode auf P_POISON existiert, kann das Ausloesen des Hooks
+ verhindert werden.
+
+HOOK-DATEN
+----------
+
+ int poison
+ Der Neue Wert der Property.
+
+RUECKGABEWERTE
+--------------
+
+ ({ <status>, <daten> })
+ <status> : H_NO_MOD, H_ALTERED, H_CANCELLED
+ <daten> : int poison
+
+SIEHE AUCH
+----------
+
+ HRegisterToHook(), HUnregisterFromHook(), HookFlow(), P_POISON
+
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/libhooks/H_HOOK_SP b/doc/libhooks/H_HOOK_SP
index c64f98e..1b009f4 100644
--- a/doc/libhooks/H_HOOK_SP
+++ b/doc/libhooks/H_HOOK_SP
@@ -5,15 +5,17 @@
/sys/hook.h
AUSGELOeST VON:
- /std/living/life.c
+ /std/player/life.c
BESCHREIBUNG:
Wird ausgeloest, wenn sich die P_SP eines Spielers aendern.
Dieser Hook laeuft nach der Aenderung der Konzentrationspunkte. Es ist
nicht moeglich, diesen Hook abzubrechen oder die Lebenspunkte zu aendern.
+ Eine Set-Methode auf P_SP kann das Ausloesen des Hooks verhindern.
EVENT-DATEN:
- Es werden die neuen Konzentrationspunkte des Spielers uebergeben.
+ int sp
+ Die neuen Konzentrationspunkte dees Spielers.
RUeCKGABEWERTE:
({ <status>, <daten> })
@@ -24,4 +26,4 @@
HRegisterToHook(), HUnregisterFromHook(), HookFlow()
-----------------------------------------------------------------------------
-7.2.2016, Zesstra
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/sphinx/lfun/HIsHookConsumer.rst b/doc/sphinx/lfun/HIsHookConsumer.rst
new file mode 100644
index 0000000..5f83efb
--- /dev/null
+++ b/doc/sphinx/lfun/HIsHookConsumer.rst
@@ -0,0 +1,39 @@
+HIsHookConsumer()
+=================
+
+FUNKTION
+--------
+
+ int HIsHookConsumer(int hookid, object|closure consumer)
+
+DEFINIERT IN
+------------
+
+ /std/hook_provider.c
+ /sys/hook.h
+
+ARGUMENTE
+---------
+
+ - hookid: gibt den Hook-Typ an
+ - consumer: Objekt oder Closure. Wenn ein Objekt uebergeben wird, wird
+ eine Closure auf :doc:`HookCallback` an diesem Objekt erstellt.
+
+BESCHREIBUNG
+------------
+
+ Prueft, ob eine Closure als consumer fuer einen bestimmten Hook eingetragen
+ ist.
+
+RUECKGABEWERTE
+--------------
+
+ 1 : Closure ist als consumer registriert
+ 0 : Closure nicht als Konsument gefunden
+
+SIEHE AUCH
+----------
+
+ :doc:`HRegisterToHook`, :doc:`HUnregisterFromHook`, :doc:`HookCallback`
+
+Letzte Aenderung: 08.10.2022, Bugfix
diff --git a/doc/sphinx/lfun/HListHooks.rst b/doc/sphinx/lfun/HListHooks.rst
new file mode 100644
index 0000000..dd7343e
--- /dev/null
+++ b/doc/sphinx/lfun/HListHooks.rst
@@ -0,0 +1,57 @@
+HListHooks()
+============
+
+FUNKTION
+--------
+
+ int* HListHooks()
+
+DEFINIERT IN
+------------
+
+ /std/hook_provider.c
+ /sys/hook.h
+
+ARGUMENTE
+---------
+
+ keine
+
+BESCHREIBUNG
+------------
+
+ Diese Methode liefert eine Liste von Hooktypen, fuer die das Objekt
+ Registrierungen akzeptiert. Standardmaessig bieten die Mudlib-Basis-
+ objekte folgende Hooks an:
+ Spielerobjekte: H_HOOK_MOVE, H_HOOK_DIE, H_HOOK_DEFEND, H_HOOK_ATTACK,
+ H_HOOK_HP, H_HOOK_SP, H_HOOK_ATTACK_MOD, H_HOOK_ALCOHOL
+ H_HOOK_FOOD, H_HOOK_DRINK, H_HOOK_POISON, H_HOOK_CONSUME,
+ H_HOOK_TEAMROWCHANGE ,H_HOOK_INSERT
+ NPCs: H_HOOK_MOVE, H_HOOK_DIE, H_HOOK_DEFEND, H_HOOK_ATTACK,
+ H_HOOK_ATTACK_MOD, H_HOOK_ALCOHOL, H_HOOK_FOOD, H_HOOK_DRINK,
+ H_HOOK_POISON, H_HOOK_CONSUME, H_HOOK_TEAMROWCHANGE
+ Raeume: H_HOOK_EXIT_USE, H_HOOK_INIT
+ Dinge: keine
+
+RUECKGABEWERTE
+--------------
+
+ Integer-Array der angebotenen Hook-IDs
+
+BEISPIEL
+--------
+
+.. code-block:: pike
+
+ // Bietet das Objekt einen Consume-Hook an?
+ if(H_HOOK_CONSUME in ob->HListHooks())
+ {
+ do_something();
+ }
+
+SIEHE AUCH
+----------
+
+ :doc:`HRegisterToHook`, :doc:`HUnregisterFromHook`, :doc:`HIsHookConsumer`
+
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/sphinx/lfun/HRegisterToHook.rst b/doc/sphinx/lfun/HRegisterToHook.rst
new file mode 100644
index 0000000..01d9c77
--- /dev/null
+++ b/doc/sphinx/lfun/HRegisterToHook.rst
@@ -0,0 +1,78 @@
+HRegisterToHook()
+=================
+
+FUNKTION
+--------
+
+ int HRegisterToHook(int hookid, object|closure consumer, int hookprio,
+ int consumertype, int timeInSeconds)
+
+DEFINIERT IN
+------------
+
+ /std/hook_provider.c
+ /sys/hook.h
+
+ARGUMENTE
+---------
+
+ - hookid: gibt den Hook-Typ an
+ Man kann sich nur fuer Hooktypen eintragen, die die Methode
+ :doc:`HListHooks` angeboten hat.
+ - consumer: Objekt oder Closure. Wenn ein Objekt uebergeben wird, wird
+ eine Closure auf :doc:`HookCallback` an diesem Objekt erstellt und
+ gespeichert, andernfalls wird die uebergebene Closure gespeichert.
+ Diese Closure wird spaeter beim Ausloesen des Hooks aufgerufen.
+ - hookprio: Gibt die Prioritaet an, mit der der Hook laufen soll.
+ Diese Angabe bestimmt die Reihenfolge, in der die Hooks in der Liste der
+ Hooks eingetragen werden. Siehe Abschnitt Beschreibung fuer Details.
+ - consumertype: Gibt an, um welche Art von Consumer es sich handelt.
+ - timeInSeconds: gibt die Laufzeit des Hooks an. Falls 0 eingetragen wird,
+ laeuft der Hook ewig.
+
+BESCHREIBUNG
+------------
+
+ Registriert ein Objekt oder eine Closure als Hook-Konsument.
+
+ Die Callback-Methode wird mit folgenden Argumenten gerufen:
+ - object hooksource: das Objekt, in welchem das Ereignis ausgeloest wurde
+ - int hookid: die ID des Hooks
+ - mixed hookdata: die Daten des Hooks (siehe Doku zum jeweiligen Hook)
+
+ Fuer hookprio sind folgende Werte vorgesehen (Konstanten aus hook.h):
+ - H_HOOK_LIBPRIO(x)
+ - H_HOOK_GUILDPRIO(x) oder
+ - H_HOOK_OTHERPRIO(x).
+ x darf 0, 1 oder 2 sein (je niedriger, desto hoeher die Prioritaet).
+
+ Fuer consumertype gibt es vier festgelegte Arten, die fuer alle Hooks
+ existieren koennen, aber nicht muessen (Konstanten aus hook.h):
+ - H_LISTENER: Wird nur informiert
+ - H_DATA_MODIFICATOR: Kann Daten des Ereignisses aendern
+ - H_HOOK_MODIFICATOR: Kann das Ereignis zusaetzlich abbrechen
+ - H_HOOK_SURVEYOR: Kann zusaetzlich entscheiden, ob sich Objekte
+ registrieren, Daten modifizieren oder Ereignisse abbrechen koennen
+ Die Methode :doc:`HConsumerTypeIsAllowed` gibt
+ Aufschluss darueber, welche Consumer-Typen tatsaechlich freigegeben sind.
+
+RUECKGABEWERTE
+--------------
+
+ 1 : Registrierung erfolgreich
+ -1 : Hook unbekannt
+ -2 : consumer ist keine closure und es konnte kein Callback auf
+ HookCallback im consumer erstellt werden.
+ -3 : Consumer ist bereits registriert
+ -4 : Consumer-Typ ist nicht erlaubt
+ -5 : hookprio ist nicht erlaubt
+ -6 : Surveyor hat Registrierung nicht erlaubt
+ -7 : zuviele Hooks registriert / kein Hookeintrag frei
+
+SIEHE AUCH
+----------
+
+ :doc:`HUnregisterFromHook`, :doc:`HookCallback`, :doc:`HListHooks`,
+ :doc:`HIsHookConsumer`
+
+Letzte Aenderung: 05.10.2022, Bugfix
diff --git a/doc/sphinx/lfun/HUnregisterFromHook.rst b/doc/sphinx/lfun/HUnregisterFromHook.rst
new file mode 100644
index 0000000..056ef9f
--- /dev/null
+++ b/doc/sphinx/lfun/HUnregisterFromHook.rst
@@ -0,0 +1,41 @@
+HUnregisterFromHook()
+=====================
+
+FUNKTION
+--------
+
+ int HUnregisterFromHook(int hookid, object|closure consumer)
+
+DEFINIERT IN
+------------
+
+ /std/hook_provider.c
+ /sys/hook.h
+
+ARGUMENTE
+---------
+
+ - hookid: gibt den Hook-Typ an
+ - consumer: Objekt oder Closure. Wenn ein Objekt uebergeben wird, wird
+ eine Closure auf :doc:`HookCallback` an diesem Objekt erstellt und
+ versucht diese auszutragen, andernfalls wird versuchtdie uebergebene
+ Closure ausgetragen.
+
+BESCHREIBUNG
+------------
+
+ Hebt die Registrierung von <consumer> fuer einen bestimmten Hook-Typ
+ wieder auf.
+
+RUECKGABEWERTE
+--------------
+
+ 1 : Austragen erfolgreich
+ 0 : consumer nicht als Konsument gefunden
+
+SIEHE AUCH
+----------
+
+ :doc:`HRegisterToHook`, :doc:`HookCallback`, :doc:`HIsHookConsumer`
+
+Letzte Aenderung: 06.10.2022, Bugfix
diff --git a/doc/sphinx/lfun/HookCallback.rst b/doc/sphinx/lfun/HookCallback.rst
new file mode 100644
index 0000000..c3b60df
--- /dev/null
+++ b/doc/sphinx/lfun/HookCallback.rst
@@ -0,0 +1,66 @@
+HookCallback()
+==============
+
+FUNKTION
+--------
+
+ mixed HookCallback(object hooksource, int hookid, mixed hookdata)
+
+DEFINIERT IN
+------------
+
+ Eigenen Objekten
+
+ARGUMENTE
+---------
+
+ - hooksource: Das Objekt, in dem das Ereignis ausgeloest wurde
+ - hookid: Hooktyp des ausgeloesten Hooks
+ - hookdata: Daten des ausgeloesten Hooks
+ (S. Doku des jeweiligen Hooks.)
+
+BESCHREIBUNG
+------------
+
+ Standard-Callback-Methode fuer Hooks. Wird beim Registrieren ein Objekt
+ uebergeben, wird versucht, eine Closure auf HookCallback() an diesem Objekt
+ zu erstellen. Man kann die Funktion auch anders benennen und direkt als
+ Closure uebergeben. Dies ist insb. bei mehreren Hooks im gleichen Objekt
+ hilfreich, weil es den Code uebersichtlicher macht. Die Argumente muessen
+ jedoch immer die gleichen wie bei HookCallback() sein.
+
+ Die Reihenfolge des Aufrufs der Konsumenten ist Surveyor, Hook-Modifikator,
+ Data-Modifikator, Listener. Innerhalb der Gruppen wird nach Prioritaet
+ abgearbeitet.
+ Ein Surveyor-Hook kann verhindern, dass Hooks bestimmte Aenderungen
+ durchfuehren.
+
+RUECKGABEWERTE
+--------------
+
+ ({<status>, <hookdata>})
+
+ - Status: Eine der folgenden Konstanten:
+ - H_NO_MOD: keine Veraenderung
+ - H_ALTERED: Daten des Hooks geaendert
+ - H_CANCELLED: Die Ausfuehrung der Hook-Kette und das ausloesende
+ Ereignis werden abgebrochen
+ Nicht alle Hooks unterstuetzen jeden Status.
+ - hookdata: Die ggf. modifizierten Hookdaten.
+ (S. Doku des jeweiligen Hooks.)
+
+BEMERKUNGEN
+-----------
+
+ Bitte nutzt in neuem code nicht mixed, sondern unions entsprechend der
+ Dokumentation der verwendeten Hooks.
+
+ Auch reine Listener-Objekte muesse nein Array zurueckgeben, dessen erstes
+ Element H_NO_MOD sein muss.
+
+SIEHE AUCH
+----------
+
+ :doc:`HRegisterToHook`, :doc:`HUnregisterFromHook`, unions
+
+Letzte Aenderung: 06.10.2022, Bugfix