Modul:Dok/Doku

Zur Navigation springen Zur Suche springen

Dies ist die Dokumentationsseite für Modul:Dok

Modul für Vorlagendokumentation

Diesen Modul nicht direkt aufrufen, sondern über die Vorlage {{Dokumentation}} · {{Dokumentation}}

Dieser Modul ist zur Verwendung in Vorlagen gedacht und soll die Dokumentation von Vorlagen so weit wie möglich automatisieren.

Innerhalb der Vorlage wird der erzeugende Wikitext angezeigt (mit gewissen Einschränkungen, die in XML-Notation geschriebene Tags und dadurch erzeugte Strip Markers betreffen), sodass man den Inhalt der Vorlage analysieren kann, ohne die Bearbeiten-Seite aufrufen zu müssen.

Die eigentliche Dokumentation wird von einer Unterseite der Vorlage eingebunden, die standardmäßig doc genannt wird, dieser Wert kann mit dem Paramter doc geändert werden. Wenn ich nachfolgend von der Dokumentationsseite rede, ist diese Unterseite gemeint. Wird keine Dokumentationsseite gewünscht oder gebraucht, kann das Einblenden der Links zu Anlegen der Dokumentationsseite mit der Angabe doc=none unterdrückt werden, es wird dann nur der reine Vorlageninhalt angezeigt.

Die Vorlagendokumentation kommt ohne zusätzliche Vorlagen, Module oder sonstige Wiki-Elemente aus. Einzige Ausnahme sind zwei Icons im PNG-Format, die vorhanden sein sollten: und , wie diese konkrekt aussehen sollen, bleibt dir überlassen.

In die Dokumentationsseite können Anwendungsbeispiele der Vorlage eingebunden werden, die sich beim Ändern der Vorlage automatisch aktualisieren. Auf der Vorlagenseite werden diese Beispiele angezeigt, sodass die Vorlage zugleich die Auswirkungen anzeigt. Ich empfehle, die Vorlage so zu gestalten, dass beim Fehlen von Eingabeparametern eine sinnvolle Ausgabe erzeugt wird.

Die Dokumentationsseite besteht aus mehreren Abschnitten. Zunächst wird die Wirkungsweise der Vorlage erklärt, anschließend wird eine Übersichtstabelle mit den Parametern generiert sowie eine Kopiervorlage mit einer Auflistung aller Parameter. Danach folgen Anwendungsbeispiele, der Wikicode der Vorlage sowie Links zur Vorlagenverwendung und -unterseiten.

Das Anlegen einer Preloadseite für die Dokumentation erleichtert die Erstellung der Dokumentationsseite, ist aber nicht zwingend erforderlich.

Einbindung in die Vorlage

Das Einbinden des nachfolgenden Codes erzeugt eine automatisierte Vorlagendokumentation.

In die Vorlage folgenden Code einfügen:

{{Dokumentation}}
mit mehr Parametern:
{{Dokumentation|doc=none|preload=|cat=|show=1}}

Es können Parameter ergänzt werden.
Parameterliste
x
NameBeschreibungStandardStatus
vorlageName der Vorlageaufrufende Seiteoptional
preloadName des Vorlagenmusters für die Neuerstellung der DokumentationsseiteDocumentation/preload-docoptional
docName der Unterseite, die die Dokumentation enthältdocoptional
doc=none wenn keine Dokumentationsunterseite gewünscht/gebraucht wird
catKategorie, in die die Vorlage eingeordnet wirdVorlagenoptional
alternativ: kat, kategorie (in dieser Reihenfolge)
nocatwenn keine automatische Kategorisierung erfolgen sollfalseoptional
alternativ: nokat
showwenn die Vorlage nicht verborgen wird, show=1falseoptional
alternativ: zeigen=1

Einbindung in die Dokumentationsunterseite

In die passend benannte Unterseite der Dokumentation (Parameter doc) folgenden Code einfügen:

{{#invoke:Dok|dokuseite}}
<onlyinclude>
{{#invoke:Dok|doku
|text=erzeugt eine sinnvolle Vorlage
|count=3
|rubrik=
|p1=|t1=|d1=|m1=1
|... je nachdem wie viele Parameter (count)
|aw1= ... Anwendungsbeispiel 1
|aw2= ... Anwendungsbeispiel 2 (derzeit bis zu 10 Stück möglich)
|... weitere Parameter lt. Parameterliste
}}</onlyinclude>
Parameterliste
x
NameBeschreibungStandardStatus
counthöchster verwendeter Index n für Parameter0optional
es dürfen Lücken in der Numerierung vorkommen
vorlageName der Vorlageaufrufende Rootseiteoptional
textBeschreibungstextsinnfreier Leertextoptional
trennzeichenTrennzeichen für Vorlagenaufruf z.B. *; oder ,optional
noexpandIndikatorfalseoptional
mit einem beliebigen Inhalt versehen, wenn der Vorlageninhalt nicht als Wikitext angezeigt werden soll
norenderIndikator, wenn die Vorlage nicht ausgeführt werden wollfalseoptional
beide Indikatoren setzen würde wenig Sinn ergeben, ist aber möglich
ompnur mit Parameter, omp=1 kein Aufruf ohne Parameterleeroptional
rubrikVorlagengruppeAlleListenoptional
es wird eine (parameterlose) Vorlage mit diesem Namen in die Dokumentation eingefügt (sofern sie existiert), diese kann z.B. eine automatische Kategorisierung sowie eine Liste aller Vorlagen in dieser Gruppe enthalten
aw1Anwendungsbeispiel 1; aw1=name=bumsti, familienname=muster, plz=4711leeroptional
wird ausgeführt als {{vorlage|name=bumsti|familienname=muster|plz=4711}}
das Trennzeichen wird in das magische Zeichen | umgewandelt und die Vorlage entsprechend dieser Eingabe aufgerufen, dadurch ist weitgehende Flexibiliät möglich; aw1, aw2, ... , aw10 derzeit implementiert; | innerhalb von Parametern müssen als ! dargestellt werden;
im Raw-Format: „|“ als „!“, „{{“ als „{“ und „}}“ als „}“
pnParameter n, n kann eine beliebige ganze Zahl seinoptional
tnBeschreibung des Parameters n, alternativ: descnBeschreibung fehltoptional
dnVoreinstellung des Parameters n, alternativ: defnleeroptional
mnParameter n erforderlich: mn=1, alternativ: mdtnoptionaloptional
fnFortsetzungszeile zur Parameterbeschreibung, alternativ: fortnleeroptional
gn2. Fortsetzungszeile zur Parameterbeschreibung, alternativ: gortnleeroptional
expandnmit expandn/noexpandn kann expand erwungen/unterdrückt werdenleeroptional
rendernmit rendern/norendern kann render erwungen/unterdrückt werdenleeroptional
rawnParameterinhalt als komplette Vorlage übernehmenleeroptional
Doppelklammern müssen einfach geschrieben werden
das Pipe-Zeichen | muss durch Rufzeichen ersetzt werden, sonst wird die Vorlage zu früh ausgeführt
klappbarIndikator wenn Vorlageninhalt eingeklappt können werden sollfalseoptional
tabwidthGesamtbreite der Parametertabelle70emoptional
parmwidthBreite der Namensspalte10emoptional
descwidthBreite der Beschreibungsspalte30emoptional
defwidthBreite der Spalte mit der Voreinstellung20emoptional
mandwidthBreite der Statusspalte (optional/erforderlich)5emoptional

Vorschlag für die Preload-Seite

Der Name der Vorlagenseite (die durch die Vereinfachung per Lua beinahe schon überflüssig geworden ist) für die Dokumentationsunterseite kann per Parameter gewählt werden und lautet standardmäßig Vorlage:Documentation/preload-doc. Nachfolgend ein Vorschlag für eine mögliche Vorbelegung.

Vorlage für die Vorlagendokumentations-Unterseite Vorlage:Documentation/preload-doc <includeonly><onlyinclude> {{#invoke:Dok|dokuseite}} <only<includeonly/>include>{{#invoke:Dok|doku <!-- |vorlage={{subst:BASEPAGENAME}} sollte automatisch eruiert werden--> |p1=1|t1=|d1=|m1=|f1= |p2=2|t2=|d2=|m2=|f2= |count= |omp=<!-- add when should not rendered without params --> |text=creates <!-- add description here --> |aw1=<!-- add parameterlist seperated by , oder ; change the with trennzeichen=* --> |rubrik= <!-- add the group name = name of template that creates group list --> |tabwidth= |descwidth= |namewidth= |defwidth= |mandwidth= |norender= |noexpand=}} </only<noinclude></noinclude>include></onlyinclude></includeonly> <includeonly><onlyinclude>[[Category:Dokumentation]]</onlyinclude></includeonly> {{#invoke:Dok|showme}}