Vorlage:Transclude-Doku/doc

Dieses Transclude wird von Transcludes verwendet, um ihre Dokumentation von der Implementierung getrennt zu halten. Dies ist sinnvoll, da Transcludes meist erheblich komplizierter sind als "normale" Seiten im MediaWiki.

Die Abspaltung von Implementierung und Dokumentation hat auch zur Folge, dass das empfindliche Transclude gesperrt und damit vor Bearbeitung geschützt werden kann, die Doku aber dennoch bearbeitbar bleibt.

Grundlagen zur Nutzung

Ein Transclude A kann dieses Transclude wie folgt benutzen:

$Implementierungstext<noinclude>{{Transclude-Doku}}</noinclude>

Meist will man dabei noch den $Implementierungstext in <includeonly>...</includeonly> einbetten (mehr dazu weiter unten).

Auf der Seite Vorlage:A des Transclude A wird dann von diesem Transclude ein Kasten eingeblendet, in dem der Inhalt der Seite Vorlage:A/doc eingebunden wird. Auf diese Weise wird die Dokumentation dennoch nah an der Implementierung dargestellt.

best practises

Häufig stellen Transcludes Banner dar, die Informationen enthalten, die natürlich nicht für das Transclude selbst gelten (wenn Vorlage:A einen "momentan in Arbeit" Banner erzeugt, heisst das noch lange nicht, dass Vorlage:A selbst in Arbeit ist). Manchmal ist die Darstellung eines Transcludes auf seiner eigenen Seite auch einfach verwirrend. In diesen Fällen wird man wie oben angedeutet den eigentlichen Implementierungsteil des Transcludes in <includeonly>...</includeonly> einbetten (siehe Hilfe:MediaWiki Transcludes für dieses Feature).

Von einem Transclude gelangt man über den Speziallink "Links auf diese Seite" (links im Navigationskasten) zu einer Liste aller einbettenden Seiten (diese tragen dort die Info "Vorlageneinbindung", um sie von tatsächlich verlinkenden Seiten zu unterscheiden). Mit einem weiteren Klick sieht man dan also, wie das Transclude beispielhaft genutzt werden könnte. Geschickter ist es allerdings, für diesen Zweck eine Unterseite anzulegen, also etwa Vorlage:A/Demo. Gegebenfalls ist auch eine Seite wie Vorlage:A/Testcases sinnvoll (die Wikipedia nutzt dies gern). Auch eine eigene Sandbox Vorlage:A/Sandbox kann sinnvoll sein. In all diesen Fällen sollte auf diese Seiten auf der Dokumentationsseite Vorlage:A/doc hingewiesen werden.

Warnungen (caveats)

In einem Beispielcode kommt es gelegentlich vor, dass man <nowiki> und <noinclude> benutzen möchte. Dies kann dann beim Transkludieren zu unerwünschten Effekten führen (siehe auch diesen Bug). Man kann dies umgehen, indem man für die spitzen Klammern innerhalb des <nowiki> HTML Entitäten (also &lt; und &gt;) benutzt. Die Dokumentationsseite sollte nach dem Bearbeiten stets mit der Transclude-Seite, wo die Doku transkludiert wird, verglichen werden!

sonstiges

Dieses Transclude benötigt sich selbst nicht, da sein Inhalt ja bereits genau das Gewünschte leistet.