Module:User:Manuela/Dok/doc

Modul für Vorlagendokumentation

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. Wird keine Dokumentationsseite gewünscht oder gebraucht, kann das Einblenden der Links zu Anlegen der Dokumentationsseite mit der Angabe doc=none unterdrückt werden, es wird dann nur der reine Vorlageninhalt angezeigt.

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:Dok|doc}}
mit mehr Parametern:
{{#invoke:Dok|doc|doc=none|preload=|cat=|show=1}}

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 Dokumentationsseite		Documentation/preload-doc	optional
doc	Name der Unterseite, die die Dokumentation enthält		doc	optional
	doc=none wenn keine Dokumentationsunterseite gewünscht/gebraucht wird
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:Dok|dokuseite}}
<onlyinclude>
{{#invoke:User:Manuela/Dok|doku
|text=erzeugt eine sinnvolle Vorlage
|count=3
|rubrik=
|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>

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
noexpand	Indikator		false	optional
	mit einem beliebigen Inhalt versehen, wenn der Vorlageninhalt nicht als Wikitext angezeigt werden soll
norender	Indikator, wenn die Vorlage nicht ausgeführt werden woll		false	optional
	beide Indikatoren setzen würde wenig Sinn ergeben, ist aber möglich
omp	nur mit Parameter, omp=1 kein Aufruf ohne Parameter		leer	optional
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
aw1	Anwendungsbeispiel 1; aw1=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; | innerhalb von Parametern müssen als ! dargestellt werden; im Raw-Format: „|“ als „!“, „{{“ als „{“ und „}}“ als „}“
pn	Parameter n, n kann eine beliebige ganze Zahl sein			optional
tn	Beschreibung des Parameters n, alternativ: descn		Beschreibung fehlt	optional
dn	Voreinstellung des Parameters n, alternativ: defn		leer	optional
mn	Parameter n erforderlich: mn=1, alternativ: mdtn		optional	optional
fn	Fortsetzungszeile zur Parameterbeschreibung, alternativ: fortn		leer	optional
gn	2. Fortsetzungszeile zur Parameterbeschreibung, alternativ: gortn		leer	optional
expandn	mit expandn/noexpandn kann expand erwungen/unterdrückt werden		leer	optional
rendern	mit rendern/norendern kann render erwungen/unterdrückt werden		leer	optional
rawn	Parameterinhalt als komplette Vorlage übernehmen		leer	optional
	Doppelklammern müssen einfach geschrieben werden
	das Pipe-Zeichen | muss durch Rufzeichen ersetzt werden, sonst wird die Vorlage zu früh ausgeführt
klappbar	Indikator wenn Vorlageninhalt eingeklappt können werden soll		false	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 [[Template: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:User:Manuela/Dok|dokuseite}} <only<includeonly/>include>{{#invoke:Dok|doku <!-- |vorlage={{subst:BASEPAGENAME}} sollte automatisch eruiert werden--> |p1=1|t1=|d1=|m1=|f1= |p2=2|t2=|d2=|m2=|f2= |count= |omp= |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}}