Automatisch erzeugte Manpages.
Damit nicht jeder sphinx auf dem Rechner haben muss,
behalten wir bis auf weiteres die aus den .rst
erzeugten Manpoages auch im Repo.
Change-Id: Id556c0d11cf5f79659d8350952ce1c014d81ea44
diff --git a/doc/lfun/RegisterHelperObject b/doc/lfun/RegisterHelperObject
index aa1cb66..af33a5c 100644
--- a/doc/lfun/RegisterHelperObject
+++ b/doc/lfun/RegisterHelperObject
@@ -1,113 +1,145 @@
-FUNKTION:
- int RegisterHelperObject(object helper, int type,
- string|closure callback);
+RegisterHelperObject()
+**********************
-DEFINIERT IN:
- /std/living/helpers.c
-ARGUMENTE:
- object helper
- Das Objekt, das bei einem Lebewesen als Hilfsobjekt registriert
- werden soll. Das Objekt muss sich dazu nicht im Inventar des
- Lebewesens befinden.
- int type
- Helfertyp, einer der in /sys/living/helpers.h definierten Typen:
- - HELPER_TYPE_AERIAL fuer die Flug-/Segelunterstuetzung
- - HELPER_TYPE_AQUATIC fuer Tauchunterstuetzung
- string|closure callback
- Closure oder Funktionsname als String; dies ist die Funktion, die im
- Objekt helper gerufen wird, um abzufragen, ob es sich aktuell fuer
- zustaendig erklaert oder nicht.
+FUNKTION
+========
-BESCHREIBUNG:
- Das Objekt "helper" wird als Hilfsobjekt fuer bestimmte Aktivitaeten wie
- zum Beispiel Fliegen oder Tauchen registriert.
-
- Die als Callback uebergebene Funktion wird bei der Abfrage der
- P_*_HELPERS-Properties (siehe unten) aufgerufen und deren
- Rueckgabewert in der Property vermerkt.
-
- Der Rueckgabewert der Callback-Methode muss im Wertebereich
- 0..10000 liegen, wobei ein Wert von 0 bedeutet, dass das Hilfsobjekt
- sich gerade nicht zustaendig fuehlt. Bei den Werten >0 ist es dem
- abfragenden Objekt ueberlassen, wie es diese Daten bewertet.
+ int RegisterHelperObject(object helper, int type,
+ string|closure callback);
- Die Funktion muss existieren und public sein, d.h. von aussen gerufen
- werden koennen.
-
- Die Funktion bekommt das Spielerobjekt und das abfragende Objekt als
- Parameter uebergeben.
-HINWEIS:
- Es ist ein Unterschied, ob sich ein Objekt via UnregisterHelperObject()
- als Helfer austraegt, oder ob der Aufruf der Callback-Funktion eine
- 0 zurueckgibt. Im letzteren Fall ist das Objekt nach wie vor
- registriert und kann trotzdem vom abfragenden Objekt als
- funktionsfaehig angesehen werden.
+DEFINIERT IN
+============
-RUECKGABEWERTE:
- 1 Objekt wurde erfolgreich registriert (HELPER_SUCCESS)
- -1 angegebenes Hilfsobjekt existiert nicht (HELPER_NO_CALLBACK_OBJECT)
- -2 angegebenes Hilfsobjekt ist bereits fuer diese Art der
- Unterstuetzung registriert (HELPER_ALREADY_LISTED)
+ /std/living/helpers.c
-BEISPIELE:
- a) Eine luftgefuellte Blase will sich als Tauch-Helfer am Spieler
- anmelden und ist zustaendig, solange sich noch Luft in ihr befindet:
- int luft = 5; // globale Variable z.B. fuer Luftinhalt von 5 Atemzuegen
+ARGUMENTE
+=========
- // Registrierung im Spielerobjekt
- if ( TP->RegisterHelperObject(ME, HELPER_TYPE_AQUATIC,
- "DivingCallback") == HELPER_SUCCESS ) {
- tell_object(TP, "Du kannst jetzt mit Hilfe der Luftblase unter Wasser "
- "atmen.\n");
+ object helper
+ Das Objekt, das bei einem Lebewesen als Hilfsobjekt registriert
+ werden soll. Das Objekt muss sich dazu nicht im Inventar des
+ Lebewesens befinden.
+ int type
+ Helfertyp, einer der in /sys/living/helpers.h definierten Typen:
+ - HELPER_TYPE_AERIAL fuer die Flug-/Segelunterstuetzung
+ - HELPER_TYPE_AQUATIC fuer Tauchunterstuetzung
+ string|closure callback
+ Closure oder Funktionsname als String; dies ist die Funktion, die im
+ Objekt helper gerufen wird, um abzufragen, ob es sich aktuell fuer
+ zustaendig erklaert oder nicht.
+
+
+BESCHREIBUNG
+============
+
+ Das Objekt "helper" wird als Hilfsobjekt fuer bestimmte Aktivitaeten wie
+ zum Beispiel Fliegen oder Tauchen registriert.
+
+
+
+ Die als Callback uebergebene Funktion wird bei der Abfrage der
+ P_*_HELPERS-Properties (siehe unten) aufgerufen und deren
+ Rueckgabewert in der Property vermerkt.
+
+
+
+ Der Rueckgabewert der Callback-Methode muss im Wertebereich
+ 0..10000 liegen, wobei ein Wert von 0 bedeutet, dass das Hilfsobjekt
+ sich gerade nicht zustaendig fuehlt. Bei den Werten >0 ist es dem
+ abfragenden Objekt ueberlassen, wie es diese Daten bewertet.
+
+ Die Funktion muss existieren und public sein, d.h. von aussen gerufen
+ werden koennen.
+
+
+
+ Die Funktion bekommt das Spielerobjekt und das abfragende Objekt als
+ Parameter uebergeben.
+
+
+HINWEIS
+=======
+
+ Es ist ein Unterschied, ob sich ein Objekt via UnregisterHelperObject()
+ als Helfer austraegt, oder ob der Aufruf der Callback-Funktion eine
+ 0 zurueckgibt. Im letzteren Fall ist das Objekt nach wie vor
+ registriert und kann trotzdem vom abfragenden Objekt als
+ funktionsfaehig angesehen werden.
+
+
+RUECKGABEWERTE
+==============
+
+ 1 Objekt wurde erfolgreich registriert (HELPER_SUCCESS)
+ -1 angegebenes Hilfsobjekt existiert nicht (HELPER_NO_CALLBACK_OBJECT)
+ -2 angegebenes Hilfsobjekt ist bereits fuer diese Art der
+ Unterstuetzung registriert (HELPER_ALREADY_LISTED)
+
+
+BEISPIELE
+=========
+
+ a) Eine luftgefuellte Blase will sich als Tauch-Helfer am Spieler
+ anmelden und ist zustaendig, solange sich noch Luft in ihr befindet:
+
+ int luft = 5; // globale Variable z.B. fuer Luftinhalt von 5 Atemzuegen
+
+ // Registrierung im Spielerobjekt
+ if ( TP->RegisterHelperObject(ME, HELPER_TYPE_AQUATIC,
+ "DivingCallback") == HELPER_SUCCESS ) {
+ tell_object(TP, "Du kannst jetzt mit Hilfe der Luftblase unter Wasser "
+ "atmen.\n");
+ }
+
+ // hier koennen natuerlich auch noch komplexere Dinge ablaufen, z.B.
+ // wenn ein Wert zurueckgegeben werden soll, der nicht nur 0 oder 1 ist.
+ public int DivingCallback(object player, object caller) {
+ return (environment(ME)==player && luft>0);
+ }
+
+ b) Ein Spieler befindet sich in einem Raum mit einem steilen Abhang, den
+ man hinunterspringen kann. Dies geht aber nur dann gefahrlos, wenn es
+ Hilfsobjekte gibt, die den (Segel)flug erlauben:
+
+ // cmd_springen() sei die Funktion, die bei der Eingabe des Befehls durch
+ // den Spieler aufgerufen wird.
+ static int cmd_springen(string str) {
+ [...]
+ // Property abfragen
+ mapping helpers = TP->QueryProp(P_AERIAL_HELPERS);
+ // Liste der Werte fuer die einzelnen Unterstuetzungsobjekte ermitteln
+ int *values = m_values(helpers,0);
+ // Spieler schonmal runterbewegen, die Folgen seines Handelns spuert
+ // er dann, wenn er unten angekommen ist.
+ TP->move(zielraum, M_GO|M_SILENT);
+ // "helpers" ist immer ein Mapping, das pruefen wir nicht extra.
+ // Wenn die Liste der Objekte noch mindestens ein Element enthaelt,
+ // nachdem alle unzustaendigen Hilfsobjekte (Rueckgabewert der
+ // Callback-Funktion == 0) rausgerechnet wurden, existiert mindestens
+ // ein geeignetes Hilfsobjekt.
+ if ( sizeof(values-({0})) ) {
+ tell_object(TP, "Sanft segelst Du den Hang hinab.\n");
}
-
- // hier koennen natuerlich auch noch komplexere Dinge ablaufen, z.B.
- // wenn ein Wert zurueckgegeben werden soll, der nicht nur 0 oder 1 ist.
- public int DivingCallback(object player, object caller) {
- return (environment(ME)==player && luft>0);
+ else {
+ tell_object(TP, BS("Todesmutig springst Du den Hang hinab und "
+ "schlaegst hart unten auf. Du haettest vielleicht daran denken "
+ "sollen, Dir geeignete Hilfsmittel fuer so eine Aktion zu "
+ "besorgen.");
+ TP->Defend(800, ({DT_BLUDGEON}), ([SP_NO_ACTIVE_DEFENSE:1]), ME);
}
+ return 1;
+ }
- b) Ein Spieler befindet sich in einem Raum mit einem steilen Abhang, den
- man hinunterspringen kann. Dies geht aber nur dann gefahrlos, wenn es
- Hilfsobjekte gibt, die den (Segel)flug erlauben:
- // cmd_springen() sei die Funktion, die bei der Eingabe des Befehls durch
- // den Spieler aufgerufen wird.
- static int cmd_springen(string str) {
- [...]
- // Property abfragen
- mapping helpers = TP->QueryProp(P_AERIAL_HELPERS);
- // Liste der Werte fuer die einzelnen Unterstuetzungsobjekte ermitteln
- int *values = m_values(helpers,0);
- // Spieler schonmal runterbewegen, die Folgen seines Handelns spuert
- // er dann, wenn er unten angekommen ist.
- TP->move(zielraum, M_GO|M_SILENT);
- // "helpers" ist immer ein Mapping, das pruefen wir nicht extra.
- // Wenn die Liste der Objekte noch mindestens ein Element enthaelt,
- // nachdem alle unzustaendigen Hilfsobjekte (Rueckgabewert der
- // Callback-Funktion == 0) rausgerechnet wurden, existiert mindestens
- // ein geeignetes Hilfsobjekt.
- if ( sizeof(values-({0})) ) {
- tell_object(TP, "Sanft segelst Du den Hang hinab.\n");
- }
- else {
- tell_object(TP, BS("Todesmutig springst Du den Hang hinab und "
- "schlaegst hart unten auf. Du haettest vielleicht daran denken "
- "sollen, Dir geeignete Hilfsmittel fuer so eine Aktion zu "
- "besorgen.");
- TP->Defend(800, ({DT_BLUDGEON}), ([SP_NO_ACTIVE_DEFENSE:1]), ME);
- }
- return 1;
- }
+SIEHE AUCH
+==========
-SIEHE AUCH:
- Funktionen: UnregisterHelperObject()
- Properties: P_HELPER_OBJECTS, P_AERIAL_HELPERS, P_AQUATIC_HELPERS
- Sonstiges: /sys/living/helpers.h
+ Funktionen: UnregisterHelperObject()
+ Properties: P_HELPER_OBJECTS, P_AERIAL_HELPERS, P_AQUATIC_HELPERS
+ Sonstiges: /sys/living/helpers.h
05.02.2015 Arathorn
-