User:ɞɞ/Vorlagendokumentation

Allgemeine Überlegungen

Eine Vorlage wird dann angelegt, wenn immer wiederkehrende Vorgänge im Wiki durchgeführt werden sollen, z.B. das Anlegen der Dateiablageseiten für einen [[:Kategorie:Template:Abmonname|neuen Abrechnungsmonat]]. 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. Hier eine Liste der Unterseiten der Vorlagendokumentation:

• Documentation
• Documentation/Dokuseite
• Documentation/doc
• Documentation/layout
• Documentation/ruler
• Documentation/preload-doc
• Documentation/nodoc

Vorlage Documentation

Das Einbinden der Vorlage {{Documentation}} in eine Vorlage bewirkt, dass die Unterseite {{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 {{SUBJECTPAGENAME}}/doc, sodass diese Seite leicht bearbeitet werden kann.

Ist die Unterseite {{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 {{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. Template:Vorlagendokumentationsvorlagen

Aufbau der Dokumentationsseite {{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.

{{cat|dokumentation}}{{bearbeiten}}
{{documentation/Dokuseite}}

• {{cat|dokumentation}}: Einordnen in die Kategorie Dokumentation
• {{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

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 enthält.

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: {{ShowSub|nosub=|nouse=|(1=)}}

Anschließend folgen einige möglichst aussagekräftige unterschiedliche Anwendungsbeispiele, wobei jedes Beispiel von einer dicken blauen Linie umrahmt wird, um es abzugrenzen. Die Wirkungsweise der Vorlage wird nochmals mit einer gepunkteten Linie abgegrenzt.

{{ShowSub|nouse=1}}

ergibt

---

Unterseiten

• ɞɞ/Vorlagendokumentation
• ɞɞ/Vorlagendokumentationsvorlagen

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.

Hier ein Beispiel:

x

Name	Beschreibung		Standard	Status
1	Name der Unterseite		leer	optional
2	"neu" öffnet alle Links in einem neuen Fenster		leer	optional

Wikicode der Vorlage

Als letzter Punkt folgt der Wikicode der Vorlage, wobei die Vorlage {{ShowMe}} verwendet wird. Diese verwendet die Funktion {{msgnw:}}, 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

Documentation

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

{{Documentation/ruler}}

Template:Documentation/ruler

{{Documentation/layout}}

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

Documentation[ create · purge ]

(text: User:ɞɞ/Vorlagendokumentation/doc) —

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

Template:Documentation/nodoc

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:}} an
• {{ShowSub}}: zeigt alle Unterseiten bzw. Verwendungen einer Vorlage an
• {{Klappbox}}: Text in einer einklappbaren Box
• {{Border-radius}}
• {{Box-shadow}}
• {{Clear}}
• {{CreateNewPage}}
• {{Round corners}}
• {{Span-dotted}}
• {{Tl}}
• {{Tlx}}

Wikicode dieser Seite

^{WikiText der Seite Vorlagendokumentation}

=='"`UNIQ--h-13--QINU`"' Allgemeine Überlegungen ==

Eine Vorlage wird dann angelegt, wenn immer wiederkehrende Vorgänge im Wiki durchgeführt werden sollen, z.B. das Anlegen der [[:Vorlage:AlleBerichtsvorlagen|Dateiablageseiten]] für einen [[:Kategorie:{{Abmonname}}|neuen Abrechnungsmonat]]. 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. Hier eine Liste der Unterseiten der Vorlagendokumentation: *[[Vorlage:Documentation|Documentation]] *[[Vorlage:Documentation/Dokuseite|Documentation/Dokuseite]] *[[Vorlage:Documentation/doc|Documentation/doc]] *[[Vorlage:Documentation/layout|Documentation/layout]] *[[Vorlage:Documentation/ruler|Documentation/ruler]] *[[Vorlage:Documentation/preload-doc|Documentation/preload-doc]] *[[Vorlage:Documentation/nodoc|Documentation/nodoc]] =='"`UNIQ--h-14--QINU`"' Vorlage Documentation == Das Einbinden der Vorlage {{tl|Documentation}} in eine Vorlage bewirkt, dass die Unterseite <code><nowiki>{{SUBJECTPAGENAME}}/doc</nowiki></code> 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 {{tl|Documentation/layout}} enthält einen Link zur Dokumentation <code><nowiki>{{SUBJECTPAGENAME}}/doc</nowiki></code>, sodass diese Seite leicht bearbeitet werden kann. Ist die Unterseite <code><nowiki>{{SUBJECTPAGENAME}}/doc</nowiki></code> 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 [https://www.mediawiki.org/wiki/Manual:Creating_pages_with_preloaded_text Preload-Datei] {{tl|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. {{Vorlagendokumentationsvorlagen}} =='"`UNIQ--h-15--QINU`"' Aufbau der Dokumentationsseite <code><nowiki>{{SUBJECTPAGENAME}}/doc</nowiki></code> == ==='"`UNIQ--h-16--QINU`"' Vor der Beschreibung === Dieser Teil wird bei Tansclusion nicht in andere Seiten eingebunden und soll die Bearbeitung der Vorlage und ihrer Dokumentation vereinfachen. {{coco|lang=moin|kla=|em=20em|code=<nowiki>{{cat|dokumentation}}{{bearbeiten}} {{documentation/Dokuseite}}</nowiki>}} *{{tlx|cat|dokumentation}}: Einordnen in die [[:Kategorie:Dokumentation|Kategorie Dokumentation]] *{{tl|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. {{bearbeiten}} *{{tl|documentation/Dokuseite}} erzeugt folgenden Hinweis {{documentation/Dokuseite}} ==='"`UNIQ--h-17--QINU`"' 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 [[Vorlage:AlleListen|Liste aller Vorlagenlisten]] enthält. ==='"`UNIQ--h-18--QINU`"' 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: {{tlx|ShowSub|nosub&#61;|nouse&#61;|(1&#61;)}} Anschließend folgen einige möglichst aussagekräftige unterschiedliche Anwendungsbeispiele, wobei jedes Beispiel von einer dicken blauen Linie umrahmt wird, um es abzugrenzen. Die Wirkungsweise der Vorlage wird nochmals mit einer gepunkteten Linie abgegrenzt. {{Div-dotted|width=100%|style=solid|cborder=blue}}{{tlx|ShowSub|nouse&#61;1}} ergibt {{Div-dotted}} {{ShowSub|nouse=1}}</div></div> Die Rahmenlinien erzeuge ich mittels der Vorlage {{tl|Div-dotted}} und {{tlx|Div-dotted|width&#61;100%|style&#61;solid|cborder&#61;blue}}. ==='"`UNIQ--h-19--QINU`"' Parameterliste === In Tabellenform eine Liste aller Parameter mit Namen, Beschreibung, Voreinstellung. Hier ein Beispiel: <table style="width:80%;margin-left: 1em;border: 0px;border-collapse: collapse;text-align: left;padding: 0.5em 0 0 0;{{box-shadow}}"> <caption style="background-color: #666;{{Border-radius|1em 1em 0 0}} color: #666;font-family: serif;font-size: 0.4em; border: 1px solid #666;padding: 0.5em 0 0 0;>x</caption> <tr style="background-color: #666; color: #fff;font-size:1.2em;font-family: serif; border: 1px solid #666;padding: 0.5em 0 0 0;"> <th style="width:8%;padding-left:0.5em">Name</th> <th style="width:60%;" colspan="2">Beschreibung</th> <th style="width:25%">Standard</th> <th style="width:7%">Status</th></tr> {{Tr-gradient}}<td style="font-family: monospace;font-size:1.2em;padding-left:0.5em">1</td> <td colspan="2">Name der Unterseite</td><td><span class="mw-templatedata-doc-muted" style="color:#777; font-variant:small-caps">leer</span></td> <td style="padding-right:0.5em">optional</td></tr> {{Tr-gradient|bott=1}}<td style="font-family: monospace;font-size:1.2em;padding-left:0.5em">2</td> <td colspan="2">"neu" öffnet alle Links in einem neuen Fenster</td><td><span class="mw-templatedata-doc-muted" style="color:#777; font-variant:small-caps">leer</span></td> <td style="padding-right:0.5em">optional</td></tr> </table> ==='"`UNIQ--h-20--QINU`"' Wikicode der Vorlage === Als letzter Punkt folgt der Wikicode der Vorlage, wobei die Vorlage {{tl|ShowMe}} verwendet wird. Diese verwendet die Funktion [https://www.mediawiki.org/wiki/Help:Magic_words/de#Transclusion_modifiers <code><nowiki>{{msgnw:}}</nowiki></code>], um den Seiteninhalt anzuzeigen. Der Nachteil dieser Funktion ist, dass Überschriften nicht korrekt angezeigt werden. {{tl|ShowMe}} kann auch verwendet werden, um eine „Blitzdokumentation“ des Seiteninhalts ohne Einbindung der Vorlage {{tl|Documentation}} zu erzeugen. =='"`UNIQ--h-21--QINU`"' Vorlage Documentation und ihre Unterseiten == ==='"`UNIQ--h-22--QINU`"' Liste per Special:PrefixIndex === {{:Special:PrefixIndex/Vorlage:Documentation}} ==='"`UNIQ--h-23--QINU`"' Documentation === Die Vorlagendokumentation {{tl|Documentation}} wird direkt in die Vorlage eingebunden und bindet ihrerseits folgende Unterseiten ein: {{Div-dotted|width=100%|style=solid|cborder=blue}}{{tl|Documentation/ruler}} {{Div-dotted}} {{Documentation/ruler}}</div></div> {{Div-dotted|width=100%|style=solid|cborder=blue}}{{tl|Documentation/layout}} 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 {{Div-dotted}} {{Documentation/layout}}</div></div> {{Div-dotted|width=100%|style=solid|cborder=blue}} {{tl|Documentation/nodoc}} wird dann eingebunden, wenn die Dokumentationsunterseite nicht vorhanden ist. {{Div-dotted}}{{Documentation/nodoc}}</div></div> =='"`UNIQ--h-24--QINU`"' Formatierungs- und Bearbeitungsvorlagen == *{{tl|Bearbeiten}}: erzeugt eine Linkleiste für Darstellen, Bearbeiten, Seiteninformation, Cache löschen *{{tl|Verborgen}}: erzeugt einen Hinweis darauf, dass die Vorlage nur auf eingebundenen Seiten sichtbar ist, dies wird durch das Tag <code><nowiki><includeonly></includeonly></nowiki></code> erreicht. *{{tl|ShowMe}}: zeigt den Wikitext einer Seite per [https://www.mediawiki.org/wiki/Help:Magic_words#Transclusion_modifiers <code><nowiki>{{msgnw:}}</nowiki></code>] an *{{tl|ShowSub}}: zeigt alle Unterseiten bzw. Verwendungen einer Vorlage an *{{tl|Klappbox}}: Text in einer einklappbaren Box *{{tl|Border-radius}} *{{tl|Box-shadow}} *{{tl|Clear}} *{{tl|CreateNewPage}} *{{tl|Round corners}} *{{tl|Span-dotted}} *{{tl|Tl}} *{{tl|Tlx}} =='"`UNIQ--h-25--QINU`"' Wikicode dieser Seite ==

{{User:ɞɞ/ShowMe|Vorlagendokumentation}}