Module:User:ɞɞ/sandbox/Dok/doc

Modul für Vorlagendokumentation

Dokumentation bearbeiten

Dieser Modul ist zur Verwendung in Vorlagen gedacht und soll die Dokumentation von Vorlagen so weit wie möglich automatisieren.

Innerhalb der Vorlage wird der erzeugende Wikitext angezeigt (mit gewissen Einschränkungen, die in XML-Notation geschriebene Tags und dadurch erzeugte Strip Markers betreffen), sodass man den Inhalt der Vorlage analysieren kann, ohne die Bearbeiten-Seite aufrufen zu müssen.

Die eigentliche Dokumentation wird von einer Unterseite der Vorlage eingebunden, die standardmäßig doc genannt wird, dieser Wert kann mit dem Paramter doc geändert werden. Wenn ich nachfolgend von der Dokumentationsseite rede, ist diese Unterseite gemeint.

Die Vorlagendokumentation kommt ohne zusätzliche Vorlagen, Module oder sonstige Wiki-Elemente aus. Einzige Ausnahme sind zwei Icons im PNG-Format, die vorhanden sein sollten: und , wie diese konkrekt aussehen sollen, bleibt dir überlassen.

In die Dokumentationsseite können Anwendungsbeispiele der Vorlage eingebunden werden, die sich beim Ändern der Vorlage automatisch aktualisieren. Auf der Vorlagenseite werden diese Beispiele angezeigt, sodass die Vorlage zugleich die Auswirkungen anzeigt. Ich empfehle, die Vorlage so zu gestalten, dass beim Fehlen von Eingabeparametern eine sinnvolle Ausgabe erzeugt wird.

Die Dokumentationsseite besteht aus mehreren Abschnitten. Zunächst wird die Wirkungsweise der Vorlage erklärt, anschließend wird eine Übersichtstabelle mit den Parametern generiert sowie eine Kopiervorlage mit einer Auflistung aller Parameter. Danach folgen Anwendungsbeispiele, der Wikicode der Vorlage sowie Links zur Vorlagenverwendung und -unterseiten.

DAs Anlegen einer Preloadseite für die Dokumentation erleichtert die Erstellung der Dokumentationsseite, ist aber nicht zwingend erforderlich.

Einbindung in die Vorlage

Das Einbinden des nachfolgenden Codes erzeugt eine automatisierte Vorlagendokumentation.

In die Vorlage folgenden Code einfügen:

{{#invoke:User:ɞɞ/sandbox/Dok|doc}}

Es können Parameter ergänzt werden.

Parameterliste

x

Name	Beschreibung		Standard	Status
vorlage	Name der Vorlage		aufrufende Seite	optional
preload	Name des Vorlagenmusters für die Neuerstellung der		Documentation/preload-doc	optional
	Dokumentationsseite
doc	Name der Unterseite, die die Dokumentation enthält		doc	optional
cat	Kategorie, in die die Vorlage eingeordnet wird		Vorlagen	optional
	alternativ: kat, kategorie (in dieser Reihenfolge)
nocat	wenn keine automatische Kategorisierung erfolgen soll		false	optional
	alternativ: nokat
show	wenn die Vorlage nicht verborgen wird, show=1		false	optional
	alternativ: zeigen=1

Einbindung in die Dokumentationsunterseite

In die passend benannte Unterseite der Dokumentation (Parameter doc) folgenden Code einfügen:

{{#invoke:User:ɞɞ/sandbox/Dok|dokuseite}}
<onlyinclude>
{{#invoke:Dok|doku
|text=erzeugt eine sinnvolle Vorlage
|count=3
|p1=|t1=|d1=|m1=1
|... je nachdem wie viele Parameter (count)
|aw1= ... Anwendungsbeispiel 1
|aw2= ... Anwendungsbeispiel 2 (derzeit bis zu 10 Stück möglich)
|... weitere Parameter lt. Parameterliste
}}</onlyinclude>

Für jedes Anwendungsbeispiel kann mittels der Parameter render⧼n⧽ bzw. expand⧼n⧽ eingestellt werden, ob der Wikitext der Vorlage angezeigt und die Vorlage gerendert werden soll oder nicht.

Mittels des Parameters raw⧼n⧽ kann gesteuert werden, ob die Vorlage im „Raw“-Format ausgeführt werden soll. Wird raw⧼n⧽ mit einem beliebigen Wert belegt, so wird der Inhalt des Parameters aw⧼n⧽ so ausgeführt, wie er dort steht. Allerdings dürfen keine doppelten geschwungenen Klammern und Pipezeichen vorkommen, statt der doppelten Klammern müssen einfache angegeben werden, statt des Pipezeichens das Rufzeichen (meinen Recherchen zufolge ist das Wikizeichen {{!}} ebenfalls möglich). Ein Beispiel würde folgendermaßen aussehen: aw1={vorlage!parameter1=wert1!parameter2=wert2! ... } (oder aw1={vorlage{{!}}parameter1=wert1{{!}}parameter2=wert2{{!}} {weitere Vorlage{{!}}... } }). Wenn innerhalb der Vorlage mehrere Klammern aufeinander folgen, müssen sie durch Leerzeichen voneinander getrennt werden.

Parameterliste

x

Name	Beschreibung		Standard	Status
count	höchster verwendeter Index n für Parameter, es dürfen Lücken in der Numerierung vorkommen		0	optional
vorlage	Name der Vorlage		aufrufende Rootseite	optional
text	Beschreibungstext		sinnfreier Leertext	optional
trennzeichen	Trennzeichen für Vorlagenaufruf z.B. *		; oder ,	optional
expand	Indikator, ob der Vorlageninhalt nicht als Wikitext angezeigt werden soll		true	optional
	expand=no oder expand=false/nein/n unterdrückt die Anzeige
render	Indikator, ob die Vorlage ausgeführt werden woll		true	optional
	beide Indikatoren auf „nein“ setzen würde wenig Sinn ergeben, ist aber möglich
klappbar	Indikator wenn Vorlageninhalt eingeklappt können werden soll		true	optional
	mit klappbar⧼n⧽=ja/nein kann die Einstellung für das n-te Anwendungsbeispiel geändert werden
	geklappt=ja klappt das Ergebnis beim Laden der Seite ein, geklappt⧼n⧽ wie klappbar
rubrik	Vorlagengruppe		AlleListen	optional
	es wird eine (parameterlose) Vorlage mit diesem Namen in die Dokumentation eingefügt (sofern sie existiert), diese kann z.B. eine automatische Kategorisierung sowie eine Liste aller Vorlagen in dieser Gruppe enthalten
aw⧼n⧽	Anwendungsbeispiel: aw⧼n⧽=name=bumsti, familienname=muster, plz=4711		leer	optional
	wird ausgeführt als {{vorlage|name=bumsti|familienname=muster|plz=4711}}
	das Trennzeichen wird in das magische Zeichen | umgewandelt und die Vorlage entsprechend dieser Eingabe aufgerufen, dadurch ist weitgehende Flexibiliät möglich; aw1, aw2, ... , aw10 derzeit implementiert
p⧼n⧽	Parameter ⧼n⧽, n kann eine beliebige ganze Zahl sein			optional
t⧼n⧽	Beschreibung des Parameters ⧼n⧽, alternativ: desc⧼n⧽		Beschreibung fehlt	optional
d⧼n⧽	Voreinstellung des Parameters ⧼n⧽, alternativ: def⧼n⧽		leer	optional
m⧼n⧽	Parameter ⧼n⧽ erforderlich: m⧼n⧽=1, alternativ: mdt⧼n⧽		optional	optional
f⧼n⧽	Fortsetzungszeile zur Parameterbeschreibung, alternativ: fort⧼n⧽		leer	optional
g⧼n⧽	2. Fortsetzungszeile zur Parameterbeschreibung, alternativ: gort⧼n⧽		leer	optional
expand⧼n⧽	mit expand⧼n⧽ kann der oben stehende Parameter expand für das n-te Beispiel überschrieben werden		expand	optional
	expand0=f unterdrückt die Anzeige der Vorlagenanwenung ohne Parameter
render⧼n⧽	mit render⧼n⧽ kann der oben stehende Parameter render überschrieben werden		render	optional
	render0=f unterdrückt die Ausführung der Vorlagenanwenung ohne Parameter
raw⧼n⧽	Parameterinhalt als komplette Vorlage übernehmen		leer	optional
	geschwungene Klammern müssen maskiert werden; öffnend: \{, schließend:}/
	das Pipe-Zeichen | muss durch Rufzeichen ersetzt werden
aw0	Vorlage ohne Parameter expandieren/rendern: ja/nein		ja	optional
tabwidth	Gesamtbreite der Parametertabelle		80%	optional
parmwidth	Breite der Namensspalte		14%	optional
descwidth	Breite der Beschreibungsspalte		50%	optional
defwidth	Breite der Spalte mit der Voreinstellung		25%	optional
mandwidth	Breite der Statusspalte (optional/erforderlich)		16%	optional

Vorschlag für die Preload-Seite

Der Name der Vorlagenseite (die durch die Vereinfachung per Lua beinahe schon überflüssig geworden ist) für die Dokumentationsunterseite kann per Parameter gewählt werden und lautet standardmäßig Vorlage:Documentation/preload-doc. Nachfolgend ein Vorschlag für eine mögliche Vorbelegung.

Vorlage für die Vorlagendokumentations-Unterseite Vorlage:Documentation/preload-doc <includeonly><onlyinclude> {{#invoke:Dok|dokuseite}} <only<includeonly/>include>{{#invoke:Dok|doku |vorlage={{subst:BASEPAGENAME}} |p1=1|t1=|d1=|m1=|f1= |p2=2|t2=|d2=|m2=|f2= |count= |text=erzeugt |aw1=parameter wie in der Liste angeführt getrennt durch , oder ; |rubrik=AlleListen |tabwidth= |descwidth= |namewidth= |defwidth= |mandwidth= |norender= |noexpand=}} </only<noinclude></noinclude>include></onlyinclude></includeonly> <includeonly><onlyinclude>[[Category:Dokumentation]]</onlyinclude></includeonly> {{#invoke:Dok|showme}}