Module:User:Manuela/Dok/doc
CodeDiscussionEditHistoryLinksLink count Subpages:DocumentationTestsResultsSandboxLive code All modules
This is the documentation page for Module:User:Manuela/Dok
Modul für Vorlagendokumentation
[edit]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
[edit]Das Einbinden des nachfolgenden Codes erzeugt eine automatisierte Vorlagendokumentation.
{{#invoke:Dok|doc}}
mit mehr Parametern:
{{#invoke:Dok|doc|doc=none|preload=|cat=|show=1}}
- Parameterliste
Name | Beschreibung | Standard | Status | |
---|---|---|---|---|
vorlage | Name der Vorlage | aufrufende Seite | optional | |
preload | Name des Vorlagenmusters für die Neuerstellung der Dokumentationsseite | Documentation/preload-doc | optional | |
doc | Name der Unterseite, die die Dokumentation enthält | doc | optional | |
doc=none wenn keine Dokumentationsunterseite gewünscht/gebraucht wird | ||||
cat | Kategorie, in die die Vorlage eingeordnet wird | Vorlagen | optional | |
alternativ: kat, kategorie (in dieser Reihenfolge) | ||||
nocat | wenn keine automatische Kategorisierung erfolgen soll | false | optional | |
alternativ: nokat | ||||
show | wenn die Vorlage nicht verborgen wird, show=1 | false | optional | |
alternativ: zeigen=1 |
Einbindung in die Dokumentationsunterseite
[edit]In die passend benannte Unterseite der Dokumentation (Parameter doc
) folgenden Code einfügen:
{{#invoke:Dok|dokuseite}} <onlyinclude> {{#invoke:User:Manuela/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
Name | Beschreibung | Standard | Status | |
---|---|---|---|---|
count | höchster verwendeter Index n für Parameter, es dürfen Lücken in der Numerierung vorkommen | 0 | optional | |
vorlage | Name der Vorlage | aufrufende Rootseite | optional | |
text | Beschreibungstext | sinnfreier Leertext | optional | |
trennzeichen | Trennzeichen für Vorlagenaufruf z.B. * | ; oder , | optional | |
noexpand | Indikator | false | optional | |
mit einem beliebigen Inhalt versehen, wenn der Vorlageninhalt nicht als Wikitext angezeigt werden soll | ||||
norender | Indikator, wenn die Vorlage nicht ausgeführt werden woll | false | optional | |
beide Indikatoren setzen würde wenig Sinn ergeben, ist aber möglich | ||||
omp | nur mit Parameter, omp=1 kein Aufruf ohne Parameter | leer | optional | |
rubrik | Vorlagengruppe | AlleListen | optional | |
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 | ||||
aw1 | Anwendungsbeispiel 1; aw1=name=bumsti, familienname=muster, plz=4711 | leer | optional | |
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 „}“ | ||||
pn | Parameter n, n kann eine beliebige ganze Zahl sein | optional | ||
tn | Beschreibung des Parameters n, alternativ: descn | Beschreibung fehlt | optional | |
dn | Voreinstellung des Parameters n, alternativ: defn | leer | optional | |
mn | Parameter n erforderlich: mn=1, alternativ: mdtn | optional | optional | |
fn | Fortsetzungszeile zur Parameterbeschreibung, alternativ: fortn | leer | optional | |
gn | 2. Fortsetzungszeile zur Parameterbeschreibung, alternativ: gortn | leer | optional | |
expandn | mit expandn/noexpandn kann expand erwungen/unterdrückt werden | leer | optional | |
rendern | mit rendern/norendern kann render erwungen/unterdrückt werden | leer | optional | |
rawn | Parameterinhalt als komplette Vorlage übernehmen | leer | optional | |
Doppelklammern müssen einfach geschrieben werden | ||||
das Pipe-Zeichen | muss durch Rufzeichen ersetzt werden, sonst wird die Vorlage zu früh ausgeführt | ||||
klappbar | Indikator wenn Vorlageninhalt eingeklappt können werden soll | false | optional | |
tabwidth | Gesamtbreite der Parametertabelle | 80% | optional | |
parmwidth | Breite der Namensspalte | 14% | optional | |
descwidth | Breite der Beschreibungsspalte | 50% | optional | |
defwidth | Breite der Spalte mit der Voreinstellung | 25% | optional | |
mandwidth | Breite der Statusspalte (optional/erforderlich) | 16% | optional |
Vorschlag für die Preload-Seite
[edit]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 [[Template: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:User:Manuela/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=
|text=erzeugt
|aw1=parameter wie in der Liste angeführt getrennt durch , oder ;
|rubrik=AlleListen
|tabwidth=
|descwidth=
|namewidth=
|defwidth=
|mandwidth=
|norender=
|noexpand=}}
</only<noinclude></noinclude>include></onlyinclude></includeonly>
<includeonly><onlyinclude>[[Category:Dokumentation]]</onlyinclude></includeonly>
{{#invoke:Dok|showme}}