Manpages als reStructuredText erstellt
Unsere Manpages wurden mit einem LPC-Tool in
reStructuredText konvertiert und liegen jetzt
in diesem Verzeichnis als Quelldaten.
Aus diesen reStructuredText sollen dann per
Script die ASCII-Manpages und per Sphinx HTML u.a.
erzeugt werden.
Change-Id: I75d659a7b3f9863aecb11dbeb0037e6cae227c36
diff --git a/doc/sphinx/lfun/AddToMenu.rst b/doc/sphinx/lfun/AddToMenu.rst
new file mode 100644
index 0000000..29824f6
--- /dev/null
+++ b/doc/sphinx/lfun/AddToMenu.rst
@@ -0,0 +1,281 @@
+AddToMenu()
+===========
+
+FUNKTION
+--------
+::
+
+ varargs string AddToMenu(string menuetext,
+ mixed ids,
+ mapping minfo,
+ mixed rate,
+ mixed msg,
+ mixed refresh,
+ mixed delay,
+ mixed d_msg);
+
+DEFINIERT IN
+------------
+::
+
+ /std/pub.c
+
+ARGUMENTE
+---------
+::
+
+ Die Erlaeuterung der Parameter beschraenkt sich im Folgenden
+ zunaechst auf die Grundfunktionalitaet bei Verwendung fester
+ Werte. Die Moeglichkeiten zur Realisierung dynamischen Verhaltens
+ sind in den Fussnoten zu den einzelnen Parametern beschrieben.
+
+ menuetext
+ Der Text steht als kurze Beschreibung im Menue.
+ ids
+ String oder Array von Strings, mit denen sich die Speise bzw. das
+ Getraenk beim Bestellen ansprechen laesst.
+ minfo
+ Mapping mit Eintraegen fuer:
+ P_HP LP-Heilung in Punkten [*]
+ P_SP KP-Heilung in Punkten [*]
+ P_FOOD Saettigungswirkung der Speise [*]
+ P_DRINK Saettigungswirkung des Getraenks [*]
+ P_ALCOHOL Alkoholgehalt des Getraenks [*]
+ P_VALUE Preis der Speise bzw. des Getraenks [*]
+ rate [*]
+ Heilrate in Punkten pro HeartBeat.
+ msg [**]
+ Meldung beim Essen:
+ Array mit 2 Strings: (1) fuer Empfaenger, (2) fuer Andere.
+ Verfuegbare Platzhalter sind weiter unten im Abschnitt "Beispiel"
+ dokumentiert.
+ refresh
+ Mapping mit Eintraegen fuer:
+ PR_USER (Kontingent fuer einzelnen Spieler) [*]
+ PR_ALL (Zusatzkontingent fuer alle) [*]
+ Alternativ: 0 fuer unbegrenzte Verfuegbarkeit
+ Einem Key muessen dabei zwei Werte zugeordnet werden:
+ Der Erste gibt die Hoehe des Kontingents an, der Zweite legt
+ fest, alle wieviel reset()s das Kontingent wieder aufgefuellt
+ wird.
+ Verwendung des Mappings erfordert Inkludieren von pub.h.
+ delay [*]
+ Zahl der Sekunden, um die verzoegert die Heilung eintritt,
+ z.B. weil das Essen erst zubereitet werden muss.
+ d_msg [**]
+ Meldung beim Bestellen, falls die Heilung verzoegert wird
+ Array mit 2 Strings: (1) fuer Empfaenger, (2) fuer Andere.
+
+
+
+ [*] Dieser Parameter kann statt eines festen Zahlenwerts mit
+ folgenden Werten gefuellt werden:
+
+ 1) Mapping <racemodifier> der Form:
+ ([ 0 : <standardwert> ,
+ <rasse_1> : <wert_1>,
+ ... ,
+ <rasse_n> : <wert_n> ]).
+ Die Eintraege in diesem Mapping werden gegen die Rasse des
+ bestellenden Spielers geprueft und entsprechend die
+ zugehoerigen Werte verwendet.
+ 2) string <func>: Aufruf erfolgt mittels
+ call_other(this_object(), func, empfaenger);
+ gerufen (aber: siehe Hinweise).
+ 3) closure <func>: Aufruf erfolgt mittels
+ funcall(func, empfaenger);
+ 4) Array der Form ({string <obj>, string <func>}) oder
+ ({object <obj>, string <func>})
+ Aufruf erfolgt mittels
+ call_other(obj, func, empfaenger);
+ (aber: siehe Hinweise). <obj> ist folglich als Objektpointer
+ oder dessen object_name() anzugeben. <func> wird mittels
+ function_exists() auf Existenz ueberprueft.
+
+ HINWEISE: im Falle von Lieferverzoegerung ("delay") und
+ Preis (P_VALUE) wird bei allen Funktionsaufrufen NICHT der
+ Empfaenger, sondern der Zahler uebergeben.
+ Im Falle der Kontingent-Liste ("refresh") kann nur die
+ verfuegbare Menge modifiziert werden, nicht die Zeit
+ bis zum Wieder-Auffuellen.
+
+ [**] Zur Erzeugung variabler Meldungen koennen folgende Werte
+ eingetragen werden:
+
+ 1) closure <func>: Aufruf erfolgt mittels
+ funcall(func, zahler, empfaenger, ident, minfo);
+ 2) string <func>: Aufruf erfolgt mittels
+ call_other(this_object(), func, zahler, empfaenger,
+ ident, minfo);
+ <func> bekommt Zahler und Empfaenger als Objektpointer,
+ ident als String und minfo als Mapping mit den
+ jeweiligen Heilwerten uebergeben. minfo entspricht hierbei
+ den Daten, die als dritter Parameter an AddToMenu()
+ uebergeben wurden.
+ HINWEIS: wenn in das minfo-Mapping keine int-Festwerte
+ eingetragen wurden, werden diese gemaess den Regeln unter [*]
+ geprueft; Funktionen/Closures werden ggf. ausgewertet und
+ deren Rueckgabewerte an die Funktion <func> uebergeben.
+ WICHTIG: Die Rueckgabewerte der Funktion werden nicht
+ ausgewertet. Jeder, der anstatt einer Meldung einen
+ Funktionsaufruf programmiert, muss fuer die Ausgabe der
+ Meldungen selbst sorgen.
+
+
+
+BESCHREIBUNG
+------------
+::
+
+ Mit dieser Funktion werden Speisen oder Getraenke in die Karte
+ von Kneipen und Restaurants eingefuegt.
+
+RUECKGABEWERT
+-------------
+::
+
+ Rueckgabewert ist ein String "menuentry%d", wobei %d eine Nummer
+ ist, die darueber Auskunft gibt, den wievielten Eintrag in die
+ interne Karte der Kneipe diese Speise bzw. dieses Getraenk
+ darstellt. Im Prinzip handelt es sich bei dem String um einen Key
+ fuer ein Mapping, in dem die Speisen bzw. Getraenke gespeichert
+ sind.
+
+BEMERKUNGEN
+-----------
+::
+
+ Die aelteren Funktionen 'AddDrink' bzw. 'AddFood' werden zwar mithilfe
+ dieser maechtigeren Funktion aus Gruenden der Abwaertskompatibilitaet
+ simuliert, sollen aber nicht mehr eingesetzt werden.
+
+
+
+ Die alten Platzhalter && etc. (s.u.) werden weiterhin unterstuetzt,
+ sollten aber fuer bessere Wartbarkeit nicht mehr verwendet werden.
+
+
+
+ Fuer das Testen der Kneipe gibt es in jeder Kneipe den Befehl
+ 'pubinit'. Hiermit lassen sich die Speisen und Getraenke durch-
+ checken. Steht in der Ausgabe bei einem Getraenk/Essen ein FAIL,
+ so wird die entsprechende Speise (oder Getraenk) NICHT an Spieler
+ verkauft. Ausnahmen fuer Speisen/Getraenke mit hoeheren maximalen
+ Werten sind durch Balance-EM zu genehmigen.
+
+BEISPIEL
+--------
+::
+
+ include <pub.h>
+
+ create()
+ {
+ AddToMenu("'Opa's Drachenkeule'",({"drachenkeule","keule"}),
+ ([P_HP:63,P_SP:63,P_FOOD:9,P_VALUE:528]), 5,
+ ({"Du isst die Keule mit einem schlechten Gewissen.",
+ "@WER1 isst die Keule mit einem schlechten Gewissen."}),
+ ([ PR_USER : 4; 1 , PR_ALL : 20; 3 ]), 9,
+ ({"Der unsichtbare Kneipier schneidet einem Rentner ein grosses "
+ "Stueck aus dessen Keule und bereitet sie Dir zu. Komisch, muss "
+ "wohl ein Tippfehler auf der Karte gewesen sein.",
+ "Der unsichtbare Kneipier schneidet einem hilflosen Opa ein "
+ "Stueck aus dessen Keule und braet diese fuer @WEN1."}) );
+ }
+
+ 1) Name der Speise (des Getraenks) auf der Karte (bei menue).
+
+ AddToMenu("'Opa's Drachenkeule'",
+
+ 2) ids mit denen sich bestellen laesst (z.B. "kaufe keule").
+
+ ({"drachen","drachenkeule","keule"}),
+
+ 3) Heilung fuer LP und KP, Saettigung (P_FOOD oder P_DRINK,
+ P_ALCOHOL nach Belieben setzen), Preis (P_VALUE).
+ HP und SP muessen nicht gleich sein. Speisen und Getraenke,
+ die nur eines von beiden heilen, sind auch moeglich.
+
+ ([P_HP:63,P_SP:63,P_FOOD:9,P_VALUE:528]),
+
+ 4) Heilung pro Heartbeat (in diesem Beispiel je 5 KP/LP).
+
+
+
+ 5,
+
+ 5) Meldungen fuer Spieler und Umstehende die bei Genuss ausgege-
+ ben werden (also NICHT der Bestell-Text).
+
+ ({"Du isst die Keule mit einem schlechten Gewissen.",
+ "@WER1 isst die Keule mit einem schlechten Gewissen."}),
+
+ Die Ausgabe-Strings werden vor der Ausgabe mit dem Empfaenger
+ als Objekt an replace_personal() uebergeben. Fuer die
+ moeglichen Platzhalter siehe dort.
+
+
+
+ 6) Die Speise ist in ihrer Anzahl begrenzt. Fuer jeden Spieler
+ sind 4 Keulen pro reset() da. Ausserdem gibt es noch einen
+ "Notvorrat" von 20 Keulen, der alle 3 reset()s aufgefuellt
+ wird. Aus diesem (so noch vorhanden) werden die Spieler
+ versorgt, wenn ihr "persoenlicher Vorrat" aufgebraucht ist.
+
+ ([ PR_USER : 4; 1 , PR_ALL : 20; 3 ]),
+
+
+
+ HINWEIS: bei Benutzung des Mappings muss <pub.h> inkludiert
+ werden!
+
+
+
+ Wenn man keine reset-abhaengigen Speisen haben moechte, traegt
+ man hier eine 0 ein.
+
+ 7) Die Zahl ist die Wartezeit in Sekunden, die der Wirt z.B. fuer
+ die Zubereitung und Auslieferung an den Spieler braucht.
+
+ 9,
+
+
+
+ 8) Letztendlich die Meldungen an Spieler und Umstehende, die bei Be-
+ stellung (hier 'kaufe keule') ausgegeben werden.
+
+ ({"Der unsichtbare Kneipier schneidet einem Rentner ein grosses "
+ "Stueck aus dessen Keule und bereitet sie Dir zu. Komisch, muss "
+ "wohl ein Tippfehler auf der Karte gewesen sein.",
+ "Der unsichtbare Kneipier schneidet einem hilflosen Opa ein "
+ "Stueck aus dessen Keule und braet diese fuer @WEN1."}));
+
+LISTE DER ALTEN PLATZHALTER (DEPRECATED):
+ && - pl->name(WER,2)
+ &1& - pl->name(WER,2)
+ &2& - pl->name(WESSEN,2)
+ &3& - pl->name(WEM,2)
+ &4& - pl->name(WEN,2)
+ &1# - capitalize(pl->name(WER,2))
+ &2# - capitalize(pl->name(WESSEN,2))
+ &3# - capitalize(pl->name(WEM,2))
+ &4# - capitalize(pl->name(WEN,2))
+ &! - pl->QueryPronoun(WER)
+ &5& - pl->QueryPronoun(WE);
+ &6& - pl->QueryPronoun(WESSEN)
+ &7& - pl->QueryPronoun(WEM)
+ &8& - pl->QueryPronoun(WEN)
+ &5# - capitalize(pl->QueryPronoun(WER))
+ &6# - capitalize(pl->QueryPronoun(WESSEN))
+ &7# - capitalize(pl->QueryPronoun(WEM))
+ &8# - capitalize(pl->QueryPronoun(WEN))
+
+SIEHE AUCH
+----------
+::
+
+ AddFood(), AddDrink(), /sys/pub.h
+ RemoveFromMenu(), replace_personal()
+
+Last modified: Sam, 01. Okt 2011, 23:40 by Arathorn
+