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/Set b/doc/sphinx/man/lfun/Set
new file mode 100644
index 0000000..d654027
--- /dev/null
+++ b/doc/sphinx/man/lfun/Set
@@ -0,0 +1,174 @@
+
+Set()
+*****
+
+
+FUNKTION
+========
+
+ public varargs mixed Set(string name, mixed Value, int Type, int extern);
+
+
+DEFINIERT IN
+============
+
+ /std/thing/properties.c
+ /sys/thing/properties.h (Prototyp)
+
+
+ARGUMENTE
+=========
+
+ name - Property, die manipuliert werden soll
+ Value - der zu setzende/aendernde Wert
+ Type - die Eigenschaft der Property, die manipuliert werden soll
+ extern - Interne Verwendung:
+ Wurde Set ueber SetProp von aussen gerufen.
+
+
+BESCHREIBUNG
+============
+
+ Eine der inneren Eigenschaften der Property 'name' wird veraendert.
+ 'Type' ist dabei einer der in /sys/thing/properties.h definierten
+ F_XXX - Werte:
+
+ F_VALUE (==0, default)
+ Setzt den Inhalt der Property auf 'Value'. Aehnlich "SetProp",
+ umgeht jedoch eine etwaige F_SET_METHOD oder _set_'name'()-Methode.
+ F_MODE
+ F_MODE_AS
+ F_MODE_AD
+ Aendert eines der internen Flags der Property. F_MODE negiert den
+ vorherigen Wert vom Flag 'Value', F_MODE_AS setzt und F_MODE_AD
+ loescht ihn.
+ Verfuegbare interne Flags:
+
+ SAVE
+
+ Property wird bei save_object() gespeichert
+
+ PROTECTED
+
+ Flag setzbar durch: beliebiges Objekt
+ Flag loeschbar durch: this_object(), ROOT, EM+
+ Inhalt der Property veraendern sowie Set- und Query-Methoden
+ setzen oder loeschen duerfen nur noch this_object(), ROOT, EM+
+ WARNUNG: Dieses Flag nicht leichtfertig bei Spielern setzen!
+
+ SECURED
+
+ Flag setzbar durch: this_object(), ROOT, EM+
+ Flag loeschbar durch: Niemanden!
+ Inhalt der Property veraendern sowie Set- und Query-Methoden
+ setzen oder loeschen duerfen nur noch this_object(), ROOT, EM+
+
+ NOSETMETHOD
+
+ Property nicht mehr ueber SetProp() aenderbar
+ (damit entfallen auch SET_METHOD, _set_'name')
+ F_SET_METHOD
+ Aendert den Eintrag fuer eine SetMethod - eine Closure, die anstatt
+ des Setzens der Property beim Aufruf von SetProp mit 'Value'
+ aufgerufen wird.
+ F_QUERY_METHOD
+ Aendert den Eintrag fuer eine QueryMethod - eine Closure, die anstatt
+ des Lesens der Property beim Aufruf von QueryProp aufgerufen wird.
+
+
+RUeCKGABEWERT
+=============
+
+ Das Ergebnis der Manipulation bzw. einer der definierten
+ Fehlercodes.
+
+
+BEMERKUNGEN
+===========
+
+ - Set() sollte nicht zum regulaeren Manipulieren des Inhalts einer
+ Property verwendet werden, da sowohl F_SET_METHOD als auch libinterne
+ _set_'name'()-Methoden umgangen werden und das Ergebnis fuer so
+ veraenderte Properties undefiniert ist.
+ - eine gesetzte F_SET/F_QUERY_METHOD hat bei SetProp/QueryProp Vorrang
+ vor einer _set/_query_method
+ -> _set/_query wird nach erfolgreichem Ruf von F_XXX_METHOD ignoriert
+ - F_SET/F_QUERY_METHOD sollte normalerweise Vorzug vor einer
+ _set_/_query_* gegeben werden.
+
+ SetMethods/QueryMethods:
+ - falls ihr Query/SetMethods an oeffentlichen Properties setzen
+ wollt, prueft bitte vorher, ob dort nicht schon eine (fremde) gesetzt
+ ist und brecht ggf. euer Set() ab, um nicht die Arbeit anderer
+ Mitmagier zu sabotieren (z.B. P_HANDS)
+ - Properties sollten mit Query- oder SetMethoden nur so lange wie
+ noetig belegt werden
+ -> manche Properties sollte man als Wert setzen, _auch wenn_ die
+ Spieler sie zuruecksetzen koennten (zB P_MSGIN/P_MSGOUT)
+ - auf keinen Fall den Wert speichern, ueberschreiben, rueckschreiben,
+ das fuehrt fast immer zu Problemen.
+ - Set/QueryMethoden sollten nicht als Trigger/Listener fuer ein
+ Ereignis (z.B. P_DIE_MSG fuer das Ereignis "Tod des Spielers")
+ missbraucht werden
+ -> es gibt sichere und saubere Moeglichkeiten (NotifyPlayerDeath),
+ und wenn nicht, wendet euch an den EM eures Vertrauens
+ - F_SET/F_QUERY_METHODs koennen 'protected' (empfohlen) oder 'static'
+ sein. _set_/_query_ duerfen momentan _nicht_ 'protected' sein, fuer
+ geht nur 'static' (in diesem Fall empfohlen).
+
+
+BEISPIELE
+=========
+
+ ### Aendern von Eigenschaften einer Property ###
+ // Setzen des SAVE-Flags (bei save_object() mitzuspeichern)
+ Set(P_XYZ, SAVE, F_MODE_AS);
+
+ // Loeschen des SAVE-Flags
+ Set(P_XYZ, SAVE, F_MODE_AD);
+
+
+
+ // Negieren des bisherigen SAVE-Flags
+ Set(P_XYZ, SAVE, F_MODE);
+ // Hinweis: das Setzen des Flags funktioniert mittels F_MODE nur dann,
+ // wenn sichergestellt ist, dass es vorher nicht gesetzt war. Die
+ // sichere Variante ist daher, F_MODE_AS zu verwenden.
+
+ // Sperren des SetProp/SET_METHOD-Zugriffs:
+ Set(P_XYZ, NOSETMETHOD, F_MODE_AS);
+
+ // Vorlaeufiger Zugriffsschutz fuer eine Property:
+ Set(P_XYZ, PROTECTED, F_MODE_AS);
+
+ // Permanenter Zugriffsschutz fuer eine Property:
+ Set(P_XYZ, SECURED, F_MODE_AS);
+
+ ### Setzen einer SetMethod/QueryMethod ###
+ // Setzen einer internen SetMethod
+ mixed foo(mixed val);
+ ...
+ Set(P_XYZ, #'foo, F_SET_METHOD);
+ ...
+
+ // Setzen einer QueryMethod bei einem anderen Objekt
+ mixed bar();
+ ...
+ other->Set(P_XYZ, #'bar, F_QUERY_METHOD);
+ ...
+
+ // Der Vollstaendigkeit halber sei das Aendern einer Property unter
+ // Umgehung von Set-Methoden angegeben. Es ist aber aus o.g. Gruenden
+ // zu empfehlen, diese Variante nicht zu verwenden.
+ Set(P_XYZ, "bla", F_VALUE);
+
+
+SIEHE AUCH
+==========
+
+ Aehnliches: SetProp(L), QueryProp(L), Query(L)
+ Generell: SetProperties(L), QueryProperties(L)
+ Konzept: properties, /std/thing/properties.c
+ Sonstiges: P_AUTOLOADOBJ
+
+6. Jan 2008 Arathorn