Vorlage:Beispiel/Dokumentation

Verwendungszweck

Diese Vorlage dient dazu, (Code-)Beispiele in eine einheitliche Form zu bringen. Bei Bedarf kann die Vorlage geändert werden, so dass sich alle Beispiele mit einem Handgriff in ihrer Form ändern lassen.

Der Erläuterungstext sollte sich nur auf das Beispiel selbst beziehen. Allgemeine Erläuterungen zum Thema bitte im Fließtext außerhalb der Beispiel-Box unterbringen. In der bisherigen SELFHTML-Ausgabe 8.x bezieht sich der Abschnitt „Erläuterung:“ oftmals nicht direkt auf das Beispiel, sondern allgemein auf das behandelte Thema und sollte in angemessener Weise in den Fließtext übernommen werden.

Bei Beispielen, für die eine „So sieht's aus“-Ansicht verfügbar sein soll, kann der optionale Parameter zeige=… eingefügt werden. Derzeit sollte als Parameterwert ein Dummy-Wert eingetragen werden (zeige=dummy). Das Erstellen des eigentlichen Anzeige-Beispiels ist, um Missbrauch zu verhindern, den Beispiele-Administratoren vorbehalten.

Anwendung

Diese Vorlage ist modular aufgebaut. Zu ihr gehören weitere Vorlagen, mit der sich in beliebiger Reihenfolge Beispiel-Text- und Erläuterungsmodule zusammenfügen lassen.

{{Beispiel|
Module
}}

Verfügbare Module sind:

• {{BeispielCode|...}} für Code aller Art
• {{BeispielWiki|...}} für alles was sich mit Wiki-Syntax erstellen lässt
• {{BeispielText|...}} für Erläuterungstext

Es gibt zwei optionale Parameter:

• titel=... für eine Ergänzung der Überschrift
• zeige=... für den Verweis auf ein anklickbares "So sieht's aus"

Beispiele für die Parameter

mit erweiterter Überschrift

{{Beispiel|titel=mit erweiterter Überschrift|
{{BeispielCode|...}}
}}

Beispiel mit erweiterter Überschrift

...

anklickbar

Um ein Beispiel anklickbar zu gestalten ist die Berechtigung Beispiele-Administratoren notwendig. Wer diese Berechtigung nicht hat, und (s)ein Beispiel anklickbar gestaltet haben möchte, sollte zeige=dummy setzen – bitte nicht vorgreifend einen Beispiel:-Dateinamen selbständig vergeben. Derzeit ist vorgesehen, dass sich dann die Beispiele-Administratoren manuell um die Anklickbarkeit kümmern. Siehe auch Hilfe:Beispiele‎.

{{Beispiel|zeige=Beispiel:Beispiel.txt|
{{BeispielCode|...}}
}}

Beispiel {{#BeispielUrl:Beispiel:Beispiel.txt}}

...

mit erweiterter Überschrift, anklickbar

{{Beispiel|
titel = mit erweiterter Überschrift|
zeige = Beispiel:Beispiel.txt|


{{BeispielCode|...}}
}}

Beispiel mit erweiterter Überschrift {{#BeispielUrl:Beispiel:Beispiel.txt}}

...

Beispiele für die Module

Code-Modul

Der anzuzeigende Code sollte entweder in <pre>, <nowiki> oder <source> eingefasst werden.

<pre>

Es kann nur einfacher Text eingegeben werden. Alle HTML-eigenen Zeichen können normal geschrieben werden. Wenn ein </pre> Bestandteil des anzuzeigenden Codes ist, so ist es als </pre> zu notieren.

{{Beispiel|titel = mit <pre>|
{{BeispielCode|

<pre>
<!-- Quelltext -->
  <p class="foo">bar baz</p>
  <pre> ... &lt;/pre>
</pre>

}}
}}

Beispiel mit <pre>

<!-- Quelltext -->
  <p class="foo">bar baz</p>
  <pre> ... </pre>

<nowiki>

Im Gegensatz zu <pre> kann man <nowiki> problemlos verlassen, um Wiki-Formatierungen einzubauen.

{{Beispiel|titel = mit <nowiki>|
{{BeispielCode|

<nowiki><!-- Quelltext -->
  <p class="foo">bar baz </nowiki>'''und ein fett hervorgehobener Teil'''<nowiki></p>
</nowiki>

}}
}}

Beispiel mit <nowiki>

<!-- Quelltext --> <p class="foo">bar baz und ein fett hervorgehobener Teil</p>

<source>

Mit diesem Element kann man Code automatisch mit Syntaxhervorhebung anreichern lassen. Verwendbare Parameter:

• lang="??": Sprache des Codes. Eine Liste der Werte bekommt man bei Eingabe eines falschen Wertes angezeigt (Vorschau-Funktion verwenden!)
• line: schaltet die Zeilennummerierung ein.
• line start="??": Zeilennummerierung beginnt ab …
• highlight="??": welche Zeilen sollen hervorgehoben werden. Zählung beginnt immer mit 1, auch bei Verwendung von line start=.... Die Zeilennummern können kommagetrennt entweder einzeln oder als Bereich mit Bindestrich angegeben werden.

{{Beispiel|titel = mit <source>|
{{BeispielCode|

<source lang="html4strict"><!-- Quelltext -->
  <p class="foo">bar baz</p>
</source>

}}
}}

Beispiel mit <source>

Der Inhalt enthält ein Gleichheitszeichen, das den Parser durcheinanderbringt. Bitte ein 1= am Anfang einfügen: {{BeispielCode|1= ...}}
(Es kann aber auch sein, dass kein Inhalt vorhanden ist.)

Wiki-Modul

Es kann beliebige Wiki-Syntax verwendet werden. Allerdings sind zwei Besonderheiten zu beachten. Wenn der Inhalt ein Gleichheitszeichen (=) enthält, muss wie beim nachfolgenden Tabellen-Beispiel (wegen border=1) am Anfang ein 1= eingefügt werden. Ansonsten gibt es eine Warnmeldung. Problematisch ist auch das Pipe-Zeichen (|) für das eine Ersatzschreibweise verwendet werden muss: Hilfe:Vorlagen#Problem:_Senkrechter_Strich_in_Parametern.

{{Beispiel|
{{BeispielWiki|titel=mit Einrückung|
vorn
 ein-
  ge-
   rückt
}}
}}

Beispiel mit Einrückung

vorn

ein-
 ge-

rückt

{{Beispiel|titel=mit Liste|
{{BeispielWiki|
* auf-
* ge-
* zählt
}}
}}

Beispiel mit Liste

• auf-
• ge-
• zählt

{{Beispiel|titel=mit Tabelle|
{{BeispielWiki|1=
<table border="1"><tr>
  <td>Orangen</td>
  <td>Äpfel</td>
</tr><tr>
  <td>Brot</td>
  <td>Kuchen</td>
</tr><tr>
  <td>Butter</td>
  <td>Eiskrem</td>
</tr></table>
}}
}}

Beispiel mit Tabelle

Orangen	Äpfel
Brot	Kuchen
Butter	Eiskrem

{{Beispiel|titel=mit Tabelle in Pipe-Syntax|
{{BeispielWiki|1=
{{(!}} border="1"
{{!}}Orangen
{{!}}Äpfel
{{!-}}
{{!}}Brot
{{!}}Kuchen
{{!-}}
{{!}}Butter
{{!}}Eiskrem
{{!)}}
}}
}}

Beispiel mit Tabelle in Pipe-Syntax

Orangen	Äpfel
Brot	Kuchen
Butter	Eiskrem

Kommentar-Modul

Dient zur Erläuterung des Beispiels. Bezüglich Gleichheitszeichen (=) und Pipe-Symbol (|) gelten die selben Hinweise wie beim Wiki-Modul.

{{Beispiel|titel=mit Erklärung|
{{BeispielCode|...}}
{{BeispielText|Kommentar zum Code}}
}}

Beispiel mit Erklärung

...

Kommentar zum Code

Mehrfache Modulanwendung

Module können in beliebiger Reihenfolge und Anzahl eingefügt werden. Zwischen den Modulen kann eine Leerzeile eingefügt werden, mehr als eine zerreißt die Box.

{{Beispiel|titel=- mehrteilig|

{{BeispielCode|<pre><!-- erster Code-Teil --></pre>}}

{{BeispielText|Kommentar zum ersten Code-Teil}}

{{BeispielCode|<pre><!-- zweiter Code-Teil --></pre>}}

{{BeispielText|Kommentar zum zweiten Code-Teil}}

{{BeispielWiki|
* eine
* Liste
}}

{{BeispielText|Kommentar zur Liste}}

}}

Beispiel - mehrteilig

<!-- erster Code-Teil -->

Kommentar zum ersten Code-Teil

<!-- zweiter Code-Teil -->

Kommentar zum zweiten Code-Teil

• eine
• Liste

Kommentar zur Liste