Wiki Style Example
Aus Mandriva Community Wiki
EinführungDiese Seite zeigt Syntaxbeispiele, die in diesem Wiki genutzt werden können. Sie zeigt ebenfalls die Stile, die genutzt werden sollen. Im vorherigen TWiki herrschte überhaupt keine Regelungen, wann welches "Markup" genutzt werden sollte, weshalb es nicht sehr vereinheitlicht aussah. Wenn du eine Datei oder ein Verzeichnis besprichst, solltest du immer das {{file|foo}} Markup nutzen, wie z. B. /etc/ssh/sshd_config or /usr/lib/X11. Wenn du ein Programm besprichst, benutze das {{prog|foo}} Markup, wie z. B. für urpmi oder sudo. Wenn du ein Programm wie rpmdrake besprichst und du willst die Wege in einem GUI-Menü zeigen, benutze das {{menu|foo->bar}} Markup, z. B. Datei->Speichern unter .... Wenn du ein Paket besprichst, benutze das {{pkg|foo}} Markup, wie z. B. für "installiere das Paket urpmi" oder "lade foo-1.0-1mdv2007.0.i586.rpm herunter". Beziehst du dich auf eine Versionsnummer (eines Mandriva-Produkts) benutze das {{version|foo}} Markup, z.B für Mandriva Linux 2007. Benutze diese markup nicht, wenn du dich auf die Version einer bestimmten Software, wie z. B. "OpenSSH 4.5p1" beziehst. Brauchst du einen schnellen Verweis auf ein Kommando, dann benutze das {{cmd|foo}} Markup, z. B. urpmi --auto-select. Auf diese Art musst du den Text nicht mit <pre></pre> tags unterbrechen. Für mehrzeilige Angaben wird jedoch der Einschub mit <pre> tags bevorzugt. Jede Seite benötigt einen Titel, für den das {{title|foo}} Markup genutzt wird. Willst du zu einem Bugzilla-Eintrag verlinken, hast du zwei Möglichkeiten. Du kannst mit [[bugz:12345|Ein fieser Bug]] einen Namen verlinken, z. B. Ein fieser Bug. Falls dich der Name nicht interessiert, kannst du stattdessen auch {{bug|12345}} verwenden, z. B. Wenn du eine Seite in eine andere Sprache übersetzt hast, benutze das {{olang|[[:fr:Maison|French]]}} Markup. Das Ergebnis sieht dann folgendermaßen aus: Andere Sprachen: French Dieses spezielle Markup sollte am Seitenende, aber noch vor den Kategorien stehen. Wenn du zeigst, was der Benutzer auf der Konsole eingeben soll und angezeigt bekommt, prüfe die richtige Anwendung der Zeichen "$" und "#" für die Art der Eingabe. $ uname -a Linux cerberus.annvix.ca 2.6.18.2-tmb-desktop-3mdv #1 Wed Nov 15 19:53:47 EST 2006 i686 AMD Athlon(tm) 64 X2 Dual Core Processor 4200+ GNU/Linux Bei der obenstehenden Eingabe wird das Kommando uname -a genutzt. Das Prefix "$" zeigt, dass der User es ausführen kann. Muss ein Befehl jedoch als root ausgeführt werden, sollte das Prefix "#" verwendet werden, wie als würde man die bash-Eingabezeile benutzen: $ sudo su - # ps ax Das beugt Unklarheiten vor, was eingegeben werden muss, und was die Kommandoausgabe ist. Weiterhin setzte immer eine Leerzeile um die <pre> tags. Grundsätzlich sollte jeder Paragraph oder "Unterbrechung" des Inhalt eine Leerzeile haben, unabhängig, ob es zwischen Überschriften oder nicht zusammengehörenden Auflistungen ist oder zwischen einzelnen Zeilen und <pre> Kennzeichnungen. Ein Beispiel: Überschrift 1Überschrift 2Etwas Text Überschrift 3wird folgendem vorgezogen: Überschrift 1Überschrift 2Etwas Text Überschrift 3Dies macht es den Bearbeitern leichter zu bildlich erfassen, woran sie arbeiten (Präsentation ist alles, sowohl die Anzeige der vollendeten/übersetzten Seite als auch des bearbeitete Textes.) Auf der übersetzten Seite mag kein Unterschied zu sehen sein, aber für die Bearbeitung macht es einen großen Unterschied. Bezüglich Überschriften, setze keine Links zu anderen Seiten in die Überschriften. Es mag verlockend sein, etwas wie == Benutzung von [[Development/Packaging/Tools/rpmctl|rpmctl]] == zu schreiben, aber bitte mache es nicht. Wenn du verlinken musst, nutze das erste Auftreten des entsprechenden Begriffes (in diesem Fall "rpmctl") im ersten Paragraphen für einen Link. Links in Überschriften machen die Überschriften nicht einheitlich, und das ist etwas, was im alten TWiki sehr oft passierte. Für weitere Einzelheiten schaue auf die Seite Policies/Wiki_Style#Style_and_Templates. Schließlich, wenn du dich auf Mandriva beziehst, benutze bitte immer "Mandriva" oder "Mandriva Linux" anstatt "mandriva" oder "mandriva linux" oder andere Variationen. Beziehst du dich auf andere Projekte oder Firmen, gebrauche bitte die Großschreibung für ihre Namen (z. B. "RedHat" statt "redhat", usw.). Auch wenn es verlockend ist, Kurzformen zu verwenden (z. B. "WM" statt Window Manager [Fenstermanager]), vermeide bitte die Abkürzung und schreibe die Begriffe aus. Es macht den Text leichter verständlich (besonders für neue Nutzer) und sieht professioneller aus (du siehst beispielsweise keine Abkürzungen in einem Buch). Ebenfalls schreibe die Überschriften groß (wie "How to Write Documentation" anstelle von "How to write docs"). Der Grund hinter all dem ist es, die Dinge einheitlich zu halten sowie es leicht lesen und bearbeiten zu können. Außerdem sieht es so klar und professionell wie möglich aus. Statt das die Dokumentation aussieht wie geschrieben von Menschen in großer Eile, Analphabeten oder einfach faulen Personen (oder allen dreien), können wir eine fantastische, erstklassische Dokumentation erstellen, die nicht nur für Mandriva-Entwickler und -Anwender hilfreich ist, sondern ebenfalls für Nutzer anderer Distributionen. Damit du die Syntax dieses Artikels besser sehen kannst, ist der Quelltext nachfolgend dargestellt:
{{title|Wiki Style-Beispiele}}
= Einführung =
Diese Seite zeigt Syntaxbeispiele, die in diesem Wiki genutzt werden können. Sie zeigt ebenfalls die Stile, die genutzt werden sollen. Im vorherigen TWiki herrschte überhaupt keine Regelungen, wann welches "Markup" genutzt werden sollte, weshalb es nicht sehr vereinheitlicht aussah.
Wenn du eine Datei oder ein Verzeichnis besprichst, solltest du immer das {{file|foo}} Markup nutzen, wie z. B. {{file|/etc/ssh/sshd_config}} or {{file|/usr/lib/X11}}.
Wenn du ein Programm besprichst, benutze das {{prog|foo}} Markup, wie z. B. für {{prog|urpmi}} oder {{prog|sudo}}.
Wenn du ein Programm wie {{prog|rpmdrake}} besprichst und du willst die Wege in einem GUI-Menü zeigen, benutze das {{menu|foo->bar}} Markup, z. B. {{menu|Datei->Speichern unter ...}}.
Wenn du ein Paket besprichst, benutze das {{pkg|foo}} Markup, wie z. B. für "installiere das Paket {{pkg|urpmi}}" oder "lade {{pkg|foo-1.0-1mdv2007.0.i586.rpm}} herunter".
Beziehst du dich auf eine Versionsnummer (eines Mandriva-Produkts) benutze das {{version|foo}} Markup, z.B für Mandriva Linux {{version|2007}}.
Benutze diese markup nicht, wenn du dich auf die Version einer bestimmten Software, wie z. B. "OpenSSH 4.5p1" beziehst.
Brauchst du einen schnellen Verweis auf ein Kommando, dann benutze das {{cmd|foo}} Markup, z. B. {{cmd|urpmi --auto-select}}. Auf diese Art musst du den Text nicht mit <pre></pre> tags unterbrechen. Für mehrzeilige Angaben wird jedoch der Einschub mit <pre> tags bevorzugt.
Jede Seite benötigt einen Titel, für den das {{title|foo}} Markup genutzt wird.
Willst du zu einem Bugzilla-Eintrag verlinken, hast du zwei Möglichkeiten. Du kannst mit [[bugz:12345|Ein fieser Bug]] einen Namen verlinken, z. B. [[bugz:12345|Ein fieser Bug]]. Falls dich der Name nicht interessiert, kannst du stattdessen auch {{bug|12345}} verwenden, z. B. {{bug|12345}}.
Wenn du eine Seite in eine andere Sprache übersetzt hast, benutze das {{olang|[[:fr:Maison|French]]}} Markup. Das Ergebnis sieht dann folgendermaßen aus:
{{olang|[[:fr:Maison|French]]}}
Dieses spezielle Markup sollte am Seitenende, aber noch vor den Kategorien stehen.
Wenn du zeigst, was der Benutzer auf der Konsole eingeben soll und angezeigt bekommt, prüfe die richtige Anwendung der Zeichen "$" und "#" für die Art der Eingabe.
< pre>
$ uname -a
Linux cerberus.annvix.ca 2.6.18.2-tmb-desktop-3mdv #1 Wed Nov 15 19:53:47 EST 2006 i686 AMD Athlon(tm) 64 X2 Dual Core Processor 4200+ GNU/Linux
< /pre>
Bei der obenstehenden Eingabe wird das Kommando {{cmd|uname -a}} genutzt. Das Prefix "$" zeigt, dass der User es ausführen kann. Muss ein Befehl jedoch als root ausgeführt werden, sollte das Prefix "#" verwendet werden, wie als würde man die {{prog|bash}}-Eingabezeile benutzen:
< pre>
$ sudo su -
# ps ax
< /pre>
Das beugt Unklarheiten vor, was eingegeben werden muss, und was die Kommandoausgabe ist. Weiterhin setzte immer eine Leerzeile um die <pre> tags. Grundsätzlich sollte jeder Paragraph oder "Unterbrechung" des Inhalt eine Leerzeile haben, unabhängig, ob es zwischen Überschriften oder nicht zusammengehörenden Auflistungen ist oder zwischen einzelnen Zeilen und <pre> Kennzeichnungen. Ein Beispiel:
= Überschrift 1 =
== Überschrift 2 ==
Etwas Text
=== Überschrift 3 ===
wird folgendem vorgezogen:
= Überschrift 1=
== Überschrift 2 ==
Etwas Text
=== Überschrift 3 ===
Dies macht es den Bearbeitern leichter zu bildlich erfassen, woran sie arbeiten (Präsentation ist alles, sowohl die Anzeige der vollendeten/übersetzten Seite als auch des bearbeitete Textes.) Auf der übersetzten Seite mag kein Unterschied zu sehen sein, aber für die Bearbeitung macht es einen großen Unterschied.
Bezüglich Überschriften, setze keine Links zu anderen Seiten in die Überschriften. Es mag verlockend sein, etwas wie == Benutzung von [[Development/Packaging/Tools/rpmctl|rpmctl]] == zu schreiben, aber bitte mache es nicht. Wenn du verlinken musst, nutze das erste Auftreten des entsprechenden Begriffes (in diesem Fall "rpmctl") im ersten Paragraphen für einen Link. Links in Überschriften machen die Überschriften nicht einheitlich, und das ist etwas, was im alten TWiki sehr oft passierte.
Für weitere Einzelheiten schaue auf die Seite [[Policies/Wiki_Style#Style_and_Templates]].
Schließlich, wenn du dich auf Mandriva beziehst, benutze bitte immer "Mandriva" oder "Mandriva Linux" anstatt "mandriva" oder "mandriva linux" oder andere Variationen. Beziehst du dich auf andere Projekte oder Firmen, gebrauche bitte die Großschreibung für ihre Namen (z. B. "RedHat" statt "redhat", usw.). Auch wenn es verlockend ist, Kurzformen zu verwenden (z. B. "WM" statt Window Manager [Fenstermanager]), vermeide bitte die Abkürzung und schreibe die Begriffe aus. Es macht den Text leichter verständlich (besonders für neue Nutzer) und sieht professioneller aus (du siehst beispielsweise keine Abkürzungen in einem Buch). Ebenfalls schreibe die Überschriften groß (wie "How to Write Documentation" anstelle von "How to write docs").
Der Grund hinter all dem ist es, die Dinge einheitlich zu halten sowie es leicht lesen und bearbeiten zu können. Außerdem sieht es so klar und professionell wie möglich aus. Statt das die Dokumentation aussieht wie geschrieben von Menschen in großer Eile, Analphabeten oder einfach faulen Personen (oder allen dreien), können wir eine fantastische, erstklassische Dokumentation erstellen, die nicht nur für Mandriva-Entwickler und -Anwender hilfreich ist, sondern ebenfalls für Nutzer anderer Distributionen.
Damit du die Syntax dieses Artikels besser sehen kannst, ist der Quelltext nachfolgend dargestellt:
|
