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/SearchPath.rst b/doc/sphinx/lfun/SearchPath.rst
new file mode 100644
index 0000000..34ce6c1
--- /dev/null
+++ b/doc/sphinx/lfun/SearchPath.rst
@@ -0,0 +1,109 @@
+SearchPath()
+============
+
+FUNKTION
+--------
+::
+
+ public int SearchPath(string from, string to, int para,
+ closure callback)
+
+DEFINIERT IN
+------------
+::
+
+ /p/daemon/pathd.c
+ <sys/path.d>
+
+ARGUMENTE
+---------
+::
+
+ from - Der Startpunkt
+ to - Der Endpunkt
+ para - Die Parawelt in der gesucht wird (Normalwelt: 0)
+ callback - Closure, die am Ende der Pfadsuche gerufen wird
+
+BESCHREIBUNG
+------------
+::
+
+ Diese Funktion berechnet - sofern moeglich - den kuerzesten Pfad zwischen
+ <from> und <to> in der (Para-)Welt <para>.
+
+
+
+ Die Pfadsuche wird anhand von Daten ueber von Spielern gelaufene Wege
+ durchgefuehrt. D.h. Gebiete, die von Spielern nicht (in letzter Zeit mal)
+ betreten werden, sind auch dem Pfaddaemon nicht bekannt. Auch kann es
+ Gebiete geben, wo zwar gebietsintern Pfade bekannt sind, aber keine Wege
+ in den Rest vom MG.
+
+ Da diese Suche im Allgemeinen SEHR aufwendig sein kann, wird sie meistens
+ nicht sofort fertig, sondern dauert eine Weile. Wenn sie fertig ist, wird
+ die Closure <callback> aufgerufen und ihr die Argumente <from>, <to>,
+ <parawelt>, <kosten>, <path> und <cmds> uebergeben. Die Bedeutung
+ dieser Argumente ist unten erklaert.
+
+ Eine Suche nach einem Pfad in einer Parawelt fuehrt durch Raeume der
+ gewuenschen Parawelt und durch Raeume der Normalwelt.
+
+RUeCKGABEWERT
+-------------
+::
+
+ 1 - Suche wurde gestartet
+ 2 - Pfad gefunden (und callback gerufen)
+ -1 - es laeuft schon ein Suchauftrage fuer die UID des anfragenden
+ Objektes
+ -2 - es laufen bereits zuviele Suchanfragen
+ -3 - <from> und/oder <to> sind nicht bekannt
+
+
+
+ An <callback> uebergebene Argumente am Ende der Pfadsuche:
+ <from> - Startpunkt des Weges (string)
+ <to> - Zielpunkt des Weges (string)
+ <para> - Parawelt des Weges (int)
+ <costs>- Kosten des Wege. (int) Je hoeher, desto
+ laenger/unguenstiger. 0, wenn kein Pfad gefunden
+ <path> - Array mit Raumnamen, die durchlaufen werden (string*)
+ 0, wenn kein Pfad gefunden
+ <cmds> - Array mit Kommandos zum Ablaufen des Weges (string*)
+ 0, wenn kein Pfad gefunden
+
+BEMERKUNGEN
+-----------
+::
+
+ Es ist natuerlich nicht dazu gedacht, Spielern fertige Routen zwischen
+ Orten zu geben - bzw. nur in Ausnahmefaellen.
+ Pfadabfrgen werden geloggt.
+
+ Die Angabe <costs> sagt grob etwas ueber die Laenge und vor allem ueber die
+ "Qualitaet" des Pfades aus. Die steigt bei Paraweltwechseln, wenig
+ abgelaufenen Verbindungen zwischen Raeumen oder wenn eine Verbindung kein
+ normaler Ausgang ist.
+
+ Die Closure <callback> sollte nicht zuviele Ticks verbrauchen.
+
+BEISPIEL
+--------
+::
+
+ #include <pathd.h>
+ void suchergebnis(string from, string to, int para, int costs, string*
+ path, string* cmds) {
+ tell_object(find_player("zesstra"), sprintf(
+ "Ergebnis Pfadsuche von %s nach %s in Para %d fuer %d:\n %O\n %O\n",
+ from, to, para, costs, path, cmds));
+ };
+
+ ...
+ mixed res=PATHD->SearchPath("/gilden/abenteurer",
+ "/d/ebene/dancer/lucky/room/pova_la3",
+ 0, #'suchergebnis);
+
+
+22.12.2015, Zesstra
+