Benutzerin:ɞɞ/Vorlagendokumentation

Allgemeine Überlegungen

Eine Vorlage wird dann angelegt, wenn immer wiederkehrende Vorgänge im Wiki durchgeführt werden sollen. In einer Vorlage stecken eine Menge Überlegungen, die dazu neigen, nach kurzer Zeit wieder vergessen zu werden. Und dann steht man da und weiß nicht mehr, was man sich eigentlich dabei gedacht hat.

Dies soll durch eine Vorlagendokumentation verhindert werden, die einerseits einfach zu erstellen, andererseits übersichtlich, klar und leicht zu durchschauen ist.

Die Vorlagendokumentation besteht ihrerseits aus einer Reihe von Vorlagen, die in die zu dokumentierende Vorlage eingebunden werden.

Vorlage Documentation

Das Einbinden der Vorlage {{Documentation}} in eine Vorlage bewirkt, dass die Unterseite

{{Benutzer:ɞɞ/SUBJECTPAGENAME}}/doc

eingebunden wird. Diese Unterseite soll eine Beschreibung der Wirkungsweise der Vorlage enthalten, alle verwendeten Parameter auflisten, einige aussagekräftige Anwendungsbeispiele enthalten und den Wikicode der Vorlage anzeigen.

Der Aufbau einer Dokumentationsunterseite soll einem wiederkehrenden Schema folgen, das hier beschrieben wird. Die Unterseite {{Documentation/layout}} enthält einen Link zur Dokumentation {{Benutzer:ɞɞ/SUBJECTPAGENAME}}/doc, sodass diese Seite leicht bearbeitet werden kann.

Ist die Unterseite

{{Benutzer:ɞɞ/SUBJECTPAGENAME}}/doc

noch nicht vorhanden, wird ein diesbezüglicher Hinweis mit Links eingebunden, die das Anlegen der Dokumentationsseite vereinfachen. Ein Link legt die Dokumentationsunterseite ohne Inhalt an, das ist dann nützlich, wenn man bereits eine kopierfertige Dokumentation hat, aus einem anderen Wiki z.B. oder von einer ähnlichen Vorlage. Der Link mit der Inputbox legt eine Seite mit der Preload-Datei^[1]

{{Documentation/preload-doc}} an. Diese habe ich so gestaltet, dass sie möglichst viele Arbeitsschritte abnimmt. Die Struktur ist vordefiniert, eine Tabelle der Parameter enthalten sowie die automatische Anzeige des Wikicodes der Vorlage.

Da die Tabelle einige Formatierungsvorlagen enthält, sind für die vollständige und „schöne“ Anzeige der Dokumentation weitere Vorlagen erforderlich, die dazu dienen, um die Formatierung zu verbessern und die Bearbeitung zu vereinfachen.

Aufbau der Dokumentationsseite `{{Benutzer:ɞɞ/SUBJECTPAGENAME}}/doc`

Vor der Beschreibung

Dieser Teil wird bei Tansclusion nicht in andere Seiten eingebunden und soll die Bearbeitung der Vorlage und ihrer Dokumentation vereinfachen.

{{Bearbeiten}}
{{Documentation/Dokuseite}}

{{Bearbeiten}} erzeugt ein Kästchen mit Links zum Bearbeiten und Leeren des Caches in der eingebundenen Seite. Außerdem erkennt die Vorlage, ob sie in eine Vorlagendokumentation eingebunden ist. Wenn ja, erzeugt sie zusätzlich Links zum Bearbeiten der Vorlage und Seiteninformation der Vorlage.

{{Documentation/Dokuseite}} erzeugt folgenden Hinweis

Diese Seite ist eine Dokumentations-Unterseite der Seite Benutzerin:ɞɞ.

Beschreibung der Wirkungsweise der Vorlage

Dieser Teil wird in die Vorlage eingebunden und enthält eine möglichst einfache und verständliche Beschreibung der Wirkungsweise der Vorlage. Falls die Vorlage Teil einer Anzahl ähnlicher bzw. inhaltlich zusammenhängender Vorlagen ist, soll eine Vorlagenliste eingebunden werden, die Links zu allen vergleichbaren und zusammenhängenden Vorlagen sowie einen Link auf die Liste aller Vorlagenlisten (nicht hier in diesem Wiki) enthält.

Die Vorlagenliste kategorisiert jede einbindende Vorlage automatisch in die betreffende Kategorie ein, dadurch aktualisiert sich die Liste automatisch.

Verwendung

Als erstes werden alle verfügbaren Parameter aufgezählt, das ist zum Kopieren in die Zwischenablage gedacht. Da die Zahl der Parameter immer größer wurde, habe ich mehrere Vorlagenanzeigen entwickelt, die eine unterschiedliche Anzahl von Paramtern darstellen können. Unbenannte Parameter klammere ich mit Angabe der Nummer ein.

Beispiel: {{2x|(1=)|keinParameter=}}

Anschließend folgen einige möglichst aussagekräftige unterschiedliche Anwendungsbeispiele, wobei jedes Beispiel von einer dicken blauen Linie umrahmt wird, um es abzugrenzen. Mittels der Vorlage {{Xpds}}, der den Modul Xpd verwendet, wird der expandierte Wikicode umgeben von gepunkteten Linien angezeigt. Die Wirkungsweise der Vorlage wird nochmals mit einer gepunkteten Linie abgegrenzt.

ergibt als Wikitext expandiert

[[:Vorlage:2x]]

gerendert

Hauptseite Hauptseite

Die Rahmenlinien erzeuge ich mittels der Vorlage {{Div-dotted}} und {{Div-dotted|width=100%|style=solid|cborder=blue}}.

Parameterliste

In Tabellenform eine Liste aller Parameter mit Namen, Beschreibung, Voreinstellung.

Für diese Tabelle habe ich eine neue Vorlage entwickelt, {{PT-tab}}, die das Erstellen und Verwalten der Parametertabelle deutlich vereinfacht und übersichtlicher gestaltet.

Hier ein Beispiel:

x
Name	Beschreibung	Standard	Status
1	was tut Parameter 1	leer	optional
2	was tut Parameter 2	default 2
3	Parameter 3 erforderlich		erforderlich

Wikicode der Vorlage

Als letzter Punkt folgt der Wikicode der Vorlage, wobei die Vorlage {{ShowMe}} verwendet wird. Diese verwendet die Funktion {{Benutzer:ɞɞ/msgnw:}}^[2], um den Seiteninhalt anzuzeigen. Der Nachteil dieser Funktion ist, dass Überschriften nicht korrekt angezeigt werden. {{ShowMe}} kann auch verwendet werden, um eine „Blitzdokumentation“ des Seiteninhalts ohne Einbindung der Vorlage {{Documentation}} zu erzeugen.

Vorlage Documentation und ihre Unterseiten

Liste per Special:PrefixIndex

Documentation

Die Vorlagendokumentation {{Documentation}} wird direkt in die Vorlage eingebunden und bindet ihrerseits folgende Unterseiten ein:

enthält bei Einbindung in eine Vorlage einen Link auf diese Seite, damit kann ich die Vorlagendokumentation von jeder Vorlage aus mit einem Mausklick erreichen

Vorlagendokumentation

{{Documentation/nodoc}} wird dann eingebunden, wenn die Dokumentationsunterseite nicht vorhanden ist.

Du hast die Vorlagendokumentation mit dem Befehl {{Documentation}} eingebunden

Die Dokumentationsunterseite {{Vorlagendokumentation/doc}} ist nicht vorhanden.

Damit die Dokumentation wie vorgesehen funktioniert, ist es erforderlich, dass du für deine Vorlage {{Vorlagendokumentation}} die Unterseite {{Vorlagendokumentation/doc}} anlegst, das kannst du mit der Box unterhalb dieses Text durchführen, es wird eine vorausgefüllte Seite basierend auf der Seite {{Documentation/preload-doc}} erzeugt. Eine leere Seite kannst du mit dem Link anlegen.

Eine Liste der bereits vorhandenen Unterseiten:

Formatierungs- und Bearbeitungsvorlagen

{{Bearbeiten}}: erzeugt eine Linkleiste für Darstellen, Bearbeiten, Seiteninformation, Cache löschen
{{Verborgen}}: erzeugt einen Hinweis darauf, dass die Vorlage nur auf eingebundenen Seiten sichtbar ist, dies wird durch das Tag <includeonly></includeonly> erreicht.
{{ShowMe}}: zeigt den Wikitext einer Seite per {{msgnw:}}^[3] an
{{ShowSub}}: zeigt alle Unterseiten bzw. Verwendungen einer Vorlage an
{{Klappbox}}: Text in einer einklappbaren Box
{{PT-tab}}: Tabelle für Parameterliste in einer Vorlage
{{PT-row}}: Tabellenzeile für die Parameterbeschreibung der Vorlagendokumentation
{{Clear}}
{{CreateNewPage}}
{{Tl}}
{{Tlxxx}}
{{Documentation/preload-doc}}: Preloadseite für die Vorlagendokumentation

Wikicode dieser Seite

^{WikiText der Seite Benutzerin:ɞɞ/ɞɞ/Vorlagendokumentation}

[[:Benutzerin:ɞɞ/ɞɞ/Vorlagendokumentation]]

[1] Preload-Datei

[2] {{Benutzer:ɞɞ/msgnw:}}

[3] {{msgnw:}}

[1]

[2]

[3]