|
|
| Zeile 1: |
Zeile 1: |
| Dieses Element ermöglicht die Generierung von Angaben über [[Hilfe:Vorlagen|Vorlagen]], mit denen sich gültige Einbindungen überprüfen lassen und automatische Dokumentationen und Anwendungshinweise erstellt werden können.
| | Siehe [https://de.wikipedia.org/wiki/Hilfe:TemplateData hier]. |
| | |
| == Grundprinzip ==
| |
| Die als ''TemplateData'' vereinbarten Informationen über den Zweck der Vorlage und vor allem die detaillierte Beschreibung der Parameter haben zwei Anwendungsbereiche:
| |
| * Erstellung einer standardisierten Dokumentationsseite oder eines wesentlichen Teils davon
| |
| * Auswertung und automatische Generierung von Eingabeformularen für die Parameter nebst automatisierter Gültigkeitsprüfung der Werte schon bei der Eingabe. Dafür gibt es zurzeit vier Anwendungen:
| |
| *# [[Hilfe:VisualEditor|VisualEditor]] – aktueller Anlass für die Entwicklung.
| |
| *# [[Wikipedia:Technik/Skin/Gadgets/Vorlagenmeister|Vorlagenmeister]] – früherer Ansatz, über eine [[Extensible Markup Language|XML]]-Spezifikation; mit einem Eingabeformular zum Einfügen in den Quelltext der Wikiseite. Falls keine (detailliertere) XML-Beschreibung für eine bestimmte Vorlage vorhanden ist, wird ersatzweise die TemplateData-Struktur zur Produktion eines Eingabeformulars und zur Gültigkeitsprüfung der Eingabedaten herangezogen.
| |
| *# [[Hilfe:Vorlagen/Wizard|Vorlagenassistent]] (Wizard) – Werkzeugleiste WikiEditor „2010“
| |
| *# [[Hilfe:VisualEditor/Wikitext#wikitextVE2017|VE-Quelltext]] – Werkzeugleiste „2017“
| |
| | |
| Das Grundprinzip wurde üblichen [[Software-Dokumentationswerkzeug]]en entnommen; ist etwa an die mit [[javadoc]] zu gewinnenden Informationen angelehnt.
| |
| | |
| Technisch werden die TemplateData in einem <code><templatedata>...</templatedata></code>-Element kodiert, das unter [[/JSON|JSON]] beschrieben wird. Der Inhalt wird von der Software automatisch in Form einer Tabelle dargestellt, durch die im Prinzip die hergebrachte Parameterdokumentation ersetzt werden kann. Voraussetzung ist die syntaktische und semantische Richtigkeit.
| |
| | |
| Diese werden mit der Vorlagendefinition in Verbindung gebracht. In der deutschsprachigen Wikipedia sollte dies immer auf der Dokumentationsseite ''/Doku'' geschehen und nicht direkt im Quelltext der Vorlagenprogrammierung.
| |
| * In der Versionsgeschichte der eigentlichen Programmierung sollen ausschließlich Änderungen an der wirksamen Programmierung erscheinen, niemals jedoch nachrangige Formulierungsverbesserungen an der Dokumentation; diese gehört deshalb auf die Unterseite /Doku.
| |
| Dabei wird das Element <code><templatedata>…</templatedata></code> immer in eine [[Vorlage:TemplateData]] eingeschlossen, die für eine Umrahmung und eine Verlinkung mit dieser Hilfeseite sorgt. Besser ist es, den JSON-Code in den Vorlagenparameter <code>JSON=</code> zu schreiben, was voraussetzt, dass keine die Vorlagensyntax störenden Zeichen enthalten sind.
| |
| | |
| Die Inhalte von TemplateData sind dafür vorgesehen, in universell nutzbarem Format einfache und kurze Texte bereitzustellen; etwa in [[Tooltip]]s oder automatisierten Dokumentationssystemen unabhängig vom Wikiprojekt. Elaborierte und komplexe Darstellungen müssen nach wie vor in gesondertem Wikitext aufbereitet werden.
| |
| | |
| == {{Anker|MW-Editor}} Formulargestützte Erstellung und Bearbeitung ==
| |
| Dieses von MediaWiki bereitgestellte Werkzeug ist nur bei der '''Ersterstellung''' einer TemplateData-Dokumentation verwendbar.
| |
| * Es schreibt bevorzugt in die Programmierungsseite.
| |
| * In der deutschsprachigen Wikipedia werden aber längere Dokumentationen nicht in die Programmierungsseite geschrieben, sondern in eine gesonderte [[Hilfe:Unterseiten|Unterseite]] <code>/Doku</code>, damit in der [[Hilfe:Versionen|Versionsgeschichte]] nur für die einbindenden Seiten wirksame Veränderungen der Programmierung erscheinen, und nicht jede Schreibfehlerberichtigung der Dokumentation den Neuaufbau von womöglich Tausender einbindender Seiten nach sich zieht.
| |
| * Weiterhin wird eine erweiterte Syntax und ein Vorlagenparameter benutzt; deshalb müssen spätere Änderungen in [[/JSON|JSON]] eingepflegt werden; oder aber es wird eine spezielle Vorlagensyntax benutzt: [[Vorlage:TemplateData/JSON]].
| |
| | |
| Siehe dazu [[/MediaWiki-Editor]].
| |
| | |
| == {{Anker|JSON-Struktur}} Struktur des TemplateData-Objekts ==
| |
| Siehe dazu [[/JSON]].
| |
| | |
| == Hilfsmittel und Hilfen ==
| |
| Die Verwendung von <code>TemplateData</code> in dieser Wikipedia wird protokolliert unter:
| |
| * [[Special:PagesWithProp/templatedata]]
| |
| * [[:Kategorie:Vorlage:mit TemplateData]] – Besser lesbar, navigierbar und würde keine Weiterleitungen aufzählen.
| |
| ** Die Kategorisierung zählt nur Verwendungen auf, die in [[Vorlage:TemplateData]] eingeschlossen sind. Die Aufzählung der Seiten mit der ''templatedata''-Eigenschaft auf der Spezialseite muss identisch sein mit den Seiten in der Kategorie.
| |
| | |
| === Generatoren ===
| |
| Alternativ zum [[/MediaWiki-Editor|eingebauten Vorlagendokumentations-Editor]]:
| |
| * liefert das [[Wikipedia:Technik/Skin/Benutzerskripte/Hinweise|Benutzerskript]] [[Benutzer:PerfektesChaos/js/jsonXMLutils|jsonXMLutils]] aus der Vorlagenprogrammierung oder aber der Kopiervorlage einer älteren Dokumentation oder dem Quelltext einer beliebigen Einbindung ein Grundgerüst.
| |
| ** Nebenbei formatiert es auch den JSON-Code und analysiert ihn auf bestimmte mutmaßliche inhaltliche Fehler.
| |
| ** Eine XML-Struktur für den [[Wikipedia:Technik/Skin/Gadgets/Vorlagenmeister|Vorlagenmeister]] kann aus jeder mit TemplateData ausgestatteten Vorlagendokumentation generiert werden.
| |
| * kann mit dem vorübergehendem Einfügen von <code><nowiki>{{</nowiki>subst:[[Vorlage:TemplateDataGenerator|TemplateDataGenerator]]}}</code> in die Dokumentationsseite ebenfalls ein Grundgerüst generiert werden.
| |
| * gibt es ein [[Wikipedia:Technik/Skin/Benutzerskripte/Hinweise|Benutzerskript]] in der französisch- und englischsprachigen Wikipedia mit einem alternativen Dialogmenü: [[:fr:User:Ltrlg/scripts/TemplateDataEditor.js]] bzw. [[:en:User:NicoV/TemplateDataEditor]]. Dieses befindet sich jedoch auf einem älteren Stand und unterstützt daher nicht alle Datentypen oder den „Vorgeschlagen“-Parameter (''suggested''), dafür aber den ''deprecated''- und den ''inherited''-Parameter.
| |
| | |
| Bei anhaltenden Problemen hilft die [[Wikipedia:Technik/Werkstatt|Technik-Werkstatt]] weiter.
| |
| | |
| == Internationalisierung ==
| |
| Für Vorlagen, die projektweit verwendet werden, kann das TemplateData-Objekt als Commons-Datensatz unter <code style="border:none;">Data:Templatedata/<Vorlagenname>.tab</code> (ohne die spitzen Klammern) abgelegt werden und dann wie folgt in die jeweiligen Sprachversionen eingebunden werden:
| |
| <pre>
| |
| {{#invoke:TNT|doc|Vorlagenname}}
| |
| </pre>
| |
| Dabei wird automatisch die passende Übersetzung ausgegeben. Noch nicht in eine Sprache übersetzte Vorlagen können entsprechend auch auf Commons bearbeitet werden.
| |
| | |
| So liegt die Dokumentation für [[Vorlage:Graph:Lines]] unter [[commons:Data:Templatedata/Graph:Lines.tab]] in verschiedenen Sprachen vor und wird über <code><nowiki>{{#invoke:TNT|doc|Graph:Lines}}</nowiki></code> hier eingebunden.
| |
| | |
| Genauso verfährt aber auch die hier verwendete [[Vorlage:TemplateData]] – darüber können ebenfalls global geteilte vielsprachige Definitionen weltweit zentral vorgehalten werden. Die Dokumentation zur [[Vorlage:Interwiki redirect]] stammt aus [[commons:Data:TemplateData/Soft redirect.tab]] und würde auch bei uns [{{fullurl:Vorlage:Interwiki redirect|uselang=it}} auf italienisch] angezeigt – wozu TNT nicht in der Lage ist.
| |
| | |
| == Sonstiges ==
| |
| Die TemplateData-Verwendung wurde im Frühsommer 2013 weltweit gestartet.
| |
| | |
| Zu technischen Details für Programmierer siehe [[Hilfe:TemplateData/JSON #Sonstiges]].
| |
| | |
| Wenn du Wünsche hast, dann kannst du es über [[Wikipedia:Technik/Phabricator|Phabricator]] mitteilen oder [[Wikipedia:Technik/Text/Edit/VisualEditor/Rückmeldungen|mitteilen lassen]]. Das gleiche gilt für Bugmeldungen.
| |
| | |
| == Weitere Informationen ==
| |
| {{MediaWiki|Extension:TemplateData|Technische Dokumentation (englisch)}}
| |
| * [[Hilfe:TemplateData/VisualEditor]] – Beschreibung des Zusammenspiels der Parametrisierung im TemplateData mit der Auswirkung auf die Ausgabe und Bearbeitungsfunktionen im VisualEditor.
| |
| * [[Vorlage:TemplateData]] – Kennzeichnung generierter Dokumentationsblöcke
| |
| {{Phabricator|Engage=templatedata|ICON=1|SUFFIX=Status mit Liste bekannter Bugs und Anfragen zur Funktionalitätserweitung|ENGL=1}}
| |
| <noinclude>
| |
| [[Kategorie:Vorlage:mit TemplateData|!]]
| |
| [[Kategorie:Hilfe:Vorlagen]]
| |
| [[Kategorie:Hilfe:Wikisyntax]]
| |
| [[Kategorie:Hilfe:MediaWiki-Erweiterung]]
| |
| </noinclude>
| |
