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/UseSpell.rst b/doc/sphinx/lfun/UseSpell.rst
new file mode 100644
index 0000000..e9a3e9a
--- /dev/null
+++ b/doc/sphinx/lfun/UseSpell.rst
@@ -0,0 +1,105 @@
+UseSpell()
+==========
+
+FUNKTION
+--------
+::
+
+ public varargs int UseSpell(string str, string spell)
+
+DEFINIERT IN
+------------
+::
+
+ /std/living/skills.c
+
+ARGUMENTE
+---------
+::
+
+ string str Spell-Optionen
+ string spell optionaler Spellname
+
+BESCHREIBUNG
+------------
+::
+
+ Benutzt einen Spell, dessen Spellname 'spell' ggf ueber query_verb()
+ ermittelt wird. Dieser Spell sollte (als kleingeschriebener
+ Skill/Spell) im Living vorliegen.
+
+
+
+ Die Argumente 'str' werden als SI_SKILLARG temporaer in das
+ Skillmapping eingetragen (also nur fuer diesen Aufruf gueltig).
+
+
+
+ Eine ausfuehrbare Spell-Funktion zum Spell wird in folgender
+ Reihenfolge bestimmt:
+ - eine gesetzte SI_CLOSURE nutzen
+ - "UseSpell" an einem gesetzten SI_SPELLBOOK nutzen
+ - "UseSpell" an der gesetzten P_GUILD nutzen
+ - [UseSpell der Gilde sucht iA ebenfalls nur den Spell am Spellbook]
+ - eine Closure mit Rueckgabewert 0 erstellen
+ Die so bestimmte Spell-Funktion wird dann als SI_CLOSURE im Spieler
+ gesetzt und ist bis zur Zerstoerung der entsprechenden Objekte gueltig.
+ Die Methode wird dann gerufen (der Spell also angewandt).
+
+ Standardmaessig gibt ein UseSpell() also 0 zurueck, es sei denn, eine
+ Funktion wurde fuer den Spell an einer der oben genannten Stellen
+ implementiert.
+
+ SI_INHERIT ist fuer Spells beim Aufruf wirkungslos (gilt aber bei
+ LearnSkill normal).
+
+ Ein Durchlauf von UseSpell durch den Spieler sieht in etwa so aus:
+ 1) Die Methode wird als Empfaenger fuer Kommandos bekannt gemacht.
+ Das passiert mit der Anweisung
+ 'add_action("UseSpell", "", 1);' in den Dateien player/base.c und
+ in living/npc.c.
+
+ 2) /std/living/skills::UseSpell wird durch Kommando oder Heartbeat
+ gerufen.
+
+
+
+ 3) UseSpell() ermittelt eine SI_CLOSURE oder delegiert diesen Aufruf
+ an die gueltige Gilde/das Spellbook weiter.
+
+
+
+ 4) Eine gueltige Closure wird ausgefuehrt. UseSpell() uebergibt dabei
+ die Spell/Skill-Informationen und SI_SKILLARG.
+
+
+
+ 4.1.) Im Normalfall einer Gilde/Spellbook landet der Aufruf ueber
+ /std/gilden_ob::UseSpell() in /std/spellbook::UseSpell() und
+ dieses ruft eine Spellfunktion im Spellbook auf.
+ Die Spellfunktion arbeitet mit den Spell-Informationen und
+ gibt ein ERFOLG, MISSERFOLG oder 0 dafuer zurueck, ob das
+ Spellbook Lernen/Fehlermeldung oder nichts machen soll.
+ Dementsprechend werden P_SP, P_ATTACK_BUSY und
+ P_NEXT_SPELL_TIME im Spellbook geaendert.
+
+ 5.) Der Aufruf der Closure kehrt zurueck und wird zurueckgegeben.
+ Damit ist der 0-Rueckgabewert der Spellfunktion im Spellbook
+ aequivalent einem nicht ausgefuehrten Kommando.
+
+SIEHE AUCH
+----------
+::
+
+ Skills Lernen: LearnSkill, ModifySkill, LimitAbility
+ * Nutzung: UseSkill
+ * Abfragen: QuerySkill, QuerySkillAbility
+ * Modifikation: ModifySkillAttribute, QuerySkillAttribute,
+ QuerySkillAttributeModifier, RemoveSkillAttributeModifier
+ * Properties: P_SKILL_ATTRIBUTES, P_SKILL_ATTRIBUTE_OFFSETS
+ * sonstig: spruchermuedung, skill_info_liste
+ * Properties: P_NEWSKILLS
+ Spellbook: UseSpell (spellbook), Learn, SpellSuccess
+
+5. Okt 2011 Gloinson
+