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/sefun/notify_fail b/doc/sefun/notify_fail
index 1970367..85b700a 100644
--- a/doc/sefun/notify_fail
+++ b/doc/sefun/notify_fail
@@ -1,85 +1,107 @@
-FUNKTION:
- #include <notify_fail.h>
- varargs void notify_fail(string str, int prio)
- varargs void notify_fail(closure cl, int prio)
+notify_fail()
+*************
-ARGUMENTE:
- str Meldung die an den Spieler anstatt des 'Wie bitte' ausgegeben
- werden soll
- cl Closure, die bei Fehlschlag ausgefuehrt werden soll
- prio Prioritaet dieses Objekts bei diesem Setzen der Meldung
-BESCHREIBUNG:
- Merkt sich den angegebenen str und gibt ihn im Falle einer inkorrekten
- Eingabe des Spielers anstatt eines 'Wie bitte' aus.
+FUNKTION
+========
- Gedacht ist notify_fail, um dem Spieler eine bessere Hilfestellung
- bei Kommandos / Eingaben zu geben, um ihn u.U. auf die richtige
- Syntax hinzuweisen.
+ #include <notify_fail.h>
- Wird notify_fail mehrfach (durch verschiedene Objekte o.ae.) auf-
- gerufen, wird der letzte erfolgreiche Aufruf gewertet. Eine Meldung wird
- dann tatsaechlich gesetzt, wenn die Prioritaet dieses Objekts gleich
- gross oder groesser ist als die Prioritaet des Objekts, was das bisher
- gueltige notify_fail() gesetzt hat. Folgende Prioritaeten sind
- vordefiniert und werden automatisch ermittelt:
- NF_NL_OWN 100 // eigenes Objekt (soul) ueberschreibt kaum was
- NF_NL_THING 100000
- NF_NL_ROOM 1000000 // Raeume ueberschreiben sonstigen Krams
- NF_NL_LIVING 10000000 // Lebewesen ueberschreiben auch Raeume
- 2 weitere vordefinierte koennen von Magier angegeben werden:
- NF_NL_NONE -1 // wird von allem ueberschrieben
- NF_NL_MAX __INT_MAX__ // hoechste Prioritaet, ueberschreibt alles
+ varargs void notify_fail(string str, int prio)
+ varargs void notify_fail(closure cl, int prio)
- Wird eine Closure als Argument gegeben, wird sie im Fehlerfall
- (also erst wenn ein Kommando endgueltig fehlgeschlagen hat)
- ausgefuehrt und hat die Fehlermeldung als Resultat
- zurueckzugeben. Die Closure erhaelt als Argument den
- originalen Befehlsgeber; in der Regel dies ist this_player(),
- was aber vom MODIFY_CMD hook geaendert werden kann.
- notify_fail() erkennt verschachtelte Kommandos (siehe Efun
- command()), und ein notify_fail() in einem Unterkommando
- hat keinen Einfluss auf das uebergeordnete Kommando.
+ARGUMENTE
+=========
-BEMERKUNGEN:
- - solange man sich nicht absolut sicher ist, dass ein bestimmtes Objekt
- mit dem Kommando gemeint ist (Identifikation ueber id()), sollte man
- - notify_fail(str); return 0;
- nutzen anstatt mit
- - write(str) return 1;
- die Kommandoauswertung abzubrechen (und anderen Objekten die Chance
- zu nehmen das Kommando zu erfuellen)
- - Kommandos werden uebrigens oft erst vom betretenen Raum, dann von den
- Objekten abgearbeitet (je nachdem wann diese dazukamen)
- - die Prioritaet wird momentan nicht gespeichert, sie ist nur beim Setzen
- relevant. Will spaeter ein anderes Objekt eine Meldung setzen, wird
- fuer das eigene Objekt die Standardprioritaet ermittelt, auch wenn man
- eine andere hier uebergeben hat
- - Die NF_NL_* sind in /sys/notify_fail.h defniert.
+ str Meldung die an den Spieler anstatt des 'Wie bitte' ausgegeben
+ werden soll
+ cl Closure, die bei Fehlschlag ausgefuehrt werden soll
+ prio Prioritaet dieses Objekts bei diesem Setzen der Meldung
-BEISPIELE:
- Ein Raum erwartet die korrekte Eingabe von 'iss suppe':
- int iss_cmd(string str){
- // zu Anfang der Funktion das notify_fail definieren
- notify_fail("Moechtest Du vielleicht von der Suppe essen?\n");
+BESCHREIBUNG
+============
- // Spieler hat nur 'iss' ohne Parameter eingegeben oder einen anderen
- // Parameter angegeben ... Abbruch!
- // Falls kein weiteres Objekt das Kommando erfuellt oder das
- // notify_fail() mit einer eigenen Meldung ueberschreibt, wird obige
- // Meldung an den Spieler ausgegeben.
+ Merkt sich den angegebenen str und gibt ihn im Falle einer inkorrekten
+ Eingabe des Spielers anstatt eines 'Wie bitte' aus.
- if(!str || str!="suppe") return 0;
- // ab hier ist die Eingabe dann wirklich 'suppe' und die Funktion
- // kann beliebig fortgefuehrt werden
- ...
- return 1;
+ Gedacht ist notify_fail, um dem Spieler eine bessere Hilfestellung
+ bei Kommandos / Eingaben zu geben, um ihn u.U. auf die richtige
+ Syntax hinzuweisen.
-SIEHE AUCH:
- add_action(E), AddCmd(L), AddAction(L),
- query_verb(E), query_notify_fail(E)
+ Wird notify_fail mehrfach (durch verschiedene Objekte o.ae.) auf-
+ gerufen, wird der letzte erfolgreiche Aufruf gewertet. Eine Meldung wird
+ dann tatsaechlich gesetzt, wenn die Prioritaet dieses Objekts gleich
+ gross oder groesser ist als die Prioritaet des Objekts, was das bisher
+ gueltige notify_fail() gesetzt hat. Folgende Prioritaeten sind
+ vordefiniert und werden automatisch ermittelt:
+ NF_NL_OWN 100 // eigenes Objekt (soul) ueberschreibt kaum was
+ NF_NL_THING 100000
+ NF_NL_ROOM 1000000 // Raeume ueberschreiben sonstigen Krams
+ NF_NL_LIVING 10000000 // Lebewesen ueberschreiben auch Raeume
+ 2 weitere vordefinierte koennen von Magier angegeben werden:
+ NF_NL_NONE -1 // wird von allem ueberschrieben
+ NF_NL_MAX __INT_MAX__ // hoechste Prioritaet, ueberschreibt alles
+
+ Wird eine Closure als Argument gegeben, wird sie im Fehlerfall
+ (also erst wenn ein Kommando endgueltig fehlgeschlagen hat)
+ ausgefuehrt und hat die Fehlermeldung als Resultat
+ zurueckzugeben. Die Closure erhaelt als Argument den
+ originalen Befehlsgeber; in der Regel dies ist this_player(),
+ was aber vom MODIFY_CMD hook geaendert werden kann.
+
+ notify_fail() erkennt verschachtelte Kommandos (siehe Efun
+ command()), und ein notify_fail() in einem Unterkommando
+ hat keinen Einfluss auf das uebergeordnete Kommando.
+
+
+BEMERKUNGEN
+===========
+
+ - solange man sich nicht absolut sicher ist, dass ein bestimmtes Objekt
+ mit dem Kommando gemeint ist (Identifikation ueber id()), sollte man
+ - notify_fail(str); return 0;
+ nutzen anstatt mit
+ - write(str) return 1;
+ die Kommandoauswertung abzubrechen (und anderen Objekten die Chance
+ zu nehmen das Kommando zu erfuellen)
+ - Kommandos werden uebrigens oft erst vom betretenen Raum, dann von den
+ Objekten abgearbeitet (je nachdem wann diese dazukamen)
+ - die Prioritaet wird momentan nicht gespeichert, sie ist nur beim Setzen
+ relevant. Will spaeter ein anderes Objekt eine Meldung setzen, wird
+ fuer das eigene Objekt die Standardprioritaet ermittelt, auch wenn man
+ eine andere hier uebergeben hat
+ - Die NF_NL_* sind in /sys/notify_fail.h defniert.
+
+
+BEISPIELE
+=========
+
+ Ein Raum erwartet die korrekte Eingabe von 'iss suppe':
+
+ int iss_cmd(string str){
+ // zu Anfang der Funktion das notify_fail definieren
+ notify_fail("Moechtest Du vielleicht von der Suppe essen?\n");
+
+ // Spieler hat nur 'iss' ohne Parameter eingegeben oder einen anderen
+ // Parameter angegeben ... Abbruch!
+ // Falls kein weiteres Objekt das Kommando erfuellt oder das
+ // notify_fail() mit einer eigenen Meldung ueberschreibt, wird obige
+ // Meldung an den Spieler ausgegeben.
+
+ if(!str || str!="suppe") return 0;
+ // ab hier ist die Eingabe dann wirklich 'suppe' und die Funktion
+ // kann beliebig fortgefuehrt werden
+ ...
+ return 1;
+
+
+SIEHE AUCH
+==========
+
+ add_action(E), AddCmd(L), AddAction(L),
+ query_verb(E), query_notify_fail(E)
8.Aug 2007 Gloinson