Vorlage:Dokumentation

Aus Baumbach-Archiv
Zur Navigation springen Zur Suche springen
[Bearbeiten] Dokumentation

Die Trennung von Programmcode und Dokumentation macht den Quelltext einer Vorlage übersichtlicher und entlastet vor allem den Parser.

Die Beschreibung der Funktion und Syntax der Vorlage ist aber für die Verwendung durch Dritte dringend zu empfehlen!

Anlegen einer Vorlage

Kurzfassung

  1. neue Vorlagenseite leer zur Bearbeitung/Anlage öffnen
  2. initial mit dem Inhalt der Vorlage:Vorlage befüllen: {{subst:Vorlage}} und speichern
  3. erneut öffnen und ersetzen des Platzhalters (am Anfang) mit dem eigentlichen Vorlagen-Wikitext, sowie
  4. anpassen bzw. löschen der zusätzlichen Kategorie für die Vorlage (am Ende) und speichern
  5. öffnen der noch zu erstellenden Dokumentationsseite über den Link [Bearbeiten] Dokumentation
  6. initial mit dem Inhalt der Vorlage:Vorlagendokutext befüllen: {{subst:Vorlagendokutext}} und speichern
  7. erneut öffnen und füllen der Dokumentationskapitel mit dem vorlagenspezifischen Text bzw. nicht zutreffend (z. B. bei nicht eingesetzten Parametern) und speichern
  8. kontrollieren des Aussehens auf der Vorlagenseite

Ausführlich

Die neue Vorlage

Man beginnt mit der eigentlichen Vorlage, indem zunächst ein Textbaustein geladen und gespeichert wird:

{{subst:Vorlage}}

Er enthält die Standard-Struktur für die Vorlage:

  • den Platz für den eigentlichen Vorlagen-Wikitext
  • die Einbindung (Anzeige) der Vorlagen-Dokumentation aus der noch zu schreibenden Doku-Seite (siehe im nächsten Punkt) bei Ansicht (nicht Verwendung) der Vorlagenseite selbst
  • die Standard-Kategorisierung der Vorlage (Kategorie:Vorlage)
  • den Platzhalter für eine (oder mehrere) mögliche weitere Vorlagenkategorien (sofern notwendig, ansonsten zu löschen)

Nach dem Speichern wird die Vorlage zur Bearbeitung erneut geöffnet und der Platzhaltertext ( Hier kommt der eigentliche Wikitext der Vorlage hin ) durch den reinen Vorlagentext ohne Dokumentationsanmerkungen ersetzt.

Die Dokumentationsseite

Die Dokumentation der Vorlage ist auf eine eigene Seite ausgelagert, um den Wiki-Parser bei der Verwendung der Vorlage zu entlasten.

Sie ist nach der Abarbeitung des obigen ersten Punktes auf der Vorlagenseite mit dem Namen

Vorlage:Vorlagenname/Doku

am Text

[Bearbeiten] Dokumentation

verlinkt, kann also aus der gerade geschaffenen Vorlagenseite zur Erstellung oder Bearbeitung aufgerufen werden.

Auch diese Seite wird initial mit einem Textbaustein gefüllt und gespeichert.

{{subst:Vorlagendokutext}}

Er enthält die Standard-Struktur für die Vorlagendokumentation:

  • den auf der Dokumentationsseite anzuzeigenden Hinweis, dass es sich um die Dokuseite handelt mit Backlink auf die Vorlage selbst (importiert aus der Vorlage:Dokumentation/Dokuseite)
  • die Überschrift, die dynamisch ermittelt wird
  • der Dokumentationsstruktur
    • Zweck
    • Parameter (Positionsparameter bzw. benannte Parameter)
    • der Aufruftext als Kopiervorlage
    • Verwendungsbeispiel/e (Aufrufvariante/n und deren Anzeige)

Hier können nicht zutreffende Kapitel (z. B. Parameter) geleert werden bzw. nicht zutreffend vermerkt werden.

Bei den Beispielen sind, im Aufruf und Anzeige, die jeweiligen Zeilen für die Parameterübergabe entsprechend zu ersetzen.

Schließlich wird mit dem initialen Text die Dokumentationsseite auch gleich in die Kategorie:Vorlagendokumentation eingestellt.

Beispiel

In diesem fiktiven Beispiel soll die Vorlage den Namen ABC bekommen.

Vorlage

Name: Vorlage:ABC

<includeonly>...Programmcode der Vorlage...</includeonly><noinclude>
{{Dokumentation}}
</noinclude>

Dokumentation

Name: Vorlage:ABC/Doku

<noinclude>{{Dokumentation/Dokuseite}}</noinclude>
Diese Vorlage dient dazu ...
== Parameter ==
1. ...
== Beispiel ==
=== Aufruf ===
<code><nowiki>{{ABC|...}}</nowiki></code>
=== Anzeige ===
{{ABC|...}}