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/sphinx/man/lfun/RegisterHelperObject b/doc/sphinx/man/lfun/RegisterHelperObject
new file mode 100644
index 0000000..af33a5c
--- /dev/null
+++ b/doc/sphinx/man/lfun/RegisterHelperObject
@@ -0,0 +1,145 @@
+
+RegisterHelperObject()
+**********************
+
+
+FUNKTION
+========
+
+ int RegisterHelperObject(object helper, int type,
+ string|closure callback);
+
+
+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.
+
+
+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");
+ }
+ 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
+==========
+
+ Funktionen: UnregisterHelperObject()
+ Properties: P_HELPER_OBJECTS, P_AERIAL_HELPERS, P_AQUATIC_HELPERS
+ Sonstiges: /sys/living/helpers.h
+
+05.02.2015 Arathorn