Artikel-Format
- Weitere Seiten:
Die Illustrationen zu den einzelnen Formaten sind Detailbilder aus einem Beispiel.
Absatzformate
Ein neuer Absatz beginnt, wenn eine Zeile mit einem neuen Absatzformat eingeleitet wird, oder nach einer Leerzeile. Ohne eine Formatangabe bekommt der Absatz das Format des vorherigen. Umgekehrt gilt damit natürlich, dass ein Absatzformat wie @ZT: nicht automatisch endet; danach ist wieder @L: (oder Ähnliches) zu setzen (siehe auch unseren Beispieltext). Eine Sonderbehandlung erfahren Listings (@LI:) und Tabellen (@TL:), dort bleiben die Zeilenwechsel so, wie sie sind.
Je nach Absatztyp laufen dann weitere Automatismen, beispielsweise werden die Verweise ([1], siehe Abbildung 1) im Lauftext eingefärbt, ebenso die Anfangstexte in Kasten- und Tabellentiteln (Listing 1, Tabelle 1).
Kopfbereich
@R: Rubrik: Programmieren, Know-how, Sysadmin usw., wird senkrecht gedruckt.
@SW: Schlagwort: Landet unterhalb der Rubrik am Seitenstreifen, wird ebenfalls senkrecht gedruckt.
@D: Dachzeile: Der sachliche Titel, der in kleinerer Schrift über dem Titel steht (ca. 5-10 Worte).
@T: Titel: Der Titel (die Schlagzeile) des Artikels (ca. 1-3 Worte).
@V: Vorspann: Der kurze Einleitungstext, der direkt unter dem Titel steht und in schwarzer Schrift auf grauem Hintergrund gedruckt wird (ca. 2-3 Sätze).
@A: Autor: Name des Autors, steht am Ende des Vorspanns.
Textbereich
@L: Lauftext: Der eigentliche Text (Fließtext). Falls Aufzählungen (die mit dem blauen Rechteck vor der Zeile) benötigt werden: einfach vor den Absatz ein Sternchen * setzen, daraus wird dann genau dieses Rechteck. Das Sternchen muss aber wirklich am Anfang des Absatzes stehen, also die Leerzeile davor nicht vergessen!
@ZT: Zwischentitel: Die Zwischenüberschriften, etwas größer als der Lauftext (ca. 2-5 Wörter). Zwischenüberschriften untergliedern den Text.
@LI: Listing: Wird in Courier-Schrift gedruckt, mit etwas Abstand zum umgebenden Lauftext. Innerhalb von Listings werden fast alle Zeichen unverändert übernommen. Siehe auch den Abschnitt zu Listings weiter unten.
@B: Bildunterschrift: Die BU sollte in einigen Sätzen beschreiben, was auf dem Bild zu sehen ist, und mit Abbildung 1: … beginnen.
@Bi: Bild: In der Regel der Dateiname, in dem die Grafik/das Bild liegt. Ist aber im Grunde eher ein Hinweis für den Layouter, welches Bild er nehmen soll, darf also auch eine Beschreibung enthalten.
@#: Echter Kommentar, wird ignoriert und landet nicht in der Ausgabedatei.
Kastenähnliche Elemente (News, normale Kästen und Zusammenfassungskästen, Tabellen und Infos) beginnen immer mit einem Titel, haben einen Lauftext und optional ein Ende-Tag.
Infos
@IT: Infos-Titel: Die beiden kastenähnlichen Gebilde am Ende des Textes, also zum einen Der Autor bzw. Die Autorin oder Die Autoren, zum anderen Infos.
@IL: Infos-Lauftext: Bei “Der Autor” einfach Ihr Text, wie Sie sich auch immer selbst beschreiben. Bei “Infos” (Literaturverweise) einzelne Absätze, wie üblich durch eine Leerzeile getrennt, die jeweils mit [1] usw. beginnen.
@IE: Infos-Ende: Optional
Kästen
@KT: Kasten-Titel: Inhalt des schwarzen Balkens über dem Kasten. Bei Listings sollte er mit Listing 1: … beginnen.
@KL: Kasten-Lauftext: Der Text innerhalb des Kastens. Listings oder Zwischentitel im Kasten werden mit den gewohnten Tags (@LI: und @ZT:) gekennzeichnet, aber @L: darf dort nicht vorkommen.
@KE: Kasten-Ende: Optional, zeigt das Ende des Kastens an.
Tabellen
@TT: Tabellen-Titel: Name der Tabelle, sollte mit Tabelle 1: … beginnen. Steht in dem schwarzen Balken über der Tabelle.
@TH: Tabellen-Header: Innerhalb der Tabelle können Spaltenüberschriften vorkommen, die dann blau und fett gedruckt werden. Diese Überschriften stehen in einer eigenen Zeile.
@TL: Tabellen-Lauftext: Der Inhalt der Tabelle. Wird als “tab-separated list” erwartet. Eine Tabellenzeile wird zwischendurch nicht umbrochen, die Spalten werden durch einfache Tab-Zeichen getrennt. Jedes Tab schaltet also eine Spalte weiter.
@TE: Tabellen-Ende: Optional.
Zeichenformate
Ein Zeichenformat beginnt und endet mit dem gleichen Tag – diese Tags sind also als Umschalter zu sehen.
<I> Italic: Kursiv, Schrägdruck. Wird kaum benötigt, außer innerhalb eines Code-Bereichs (<C> oder @LI:). Dort bedeutet kursiv, dass es sich um einen Platzhalter handelt. Sprich: Der Benutzer soll nicht wörtlich das eingeben, was dort steht, sondern das, was damit gemeint ist. Beispiel: <C>cd <I>Verzeichnis<I><C>, aber <C>cd /tmp<C>
<B> Fett: Wird kaum benötigt. Am ehesten noch in Kästen zur Untergliederung, wenn ein Zwischentitel unangemessen wäre.
<C> Code: Innerhalb eines Absatzes (@L:) stehn Code, Dateinamen etc. (siehe Code-Konventionen) im Druck mit den französischen Anführungszeichen (»my code«). Innerhalb dieses Codes werden die Zeichen nicht weiter geändert, es bleibt alles, wie es ist, Zeichenformate entfallen – mit einer Ausnahme: Kursiv ist erlaubt.
<+> Hochgestellt
<-> Tiefgestellt: Index
<U> URL: Wird automatisch blau eingefärbt und in eckigen Klammern eingeschlossen.
Sonderzeichen
Einige Zeichenkombinationen im Text (außer in Listings und Code):
—Geviertstrich: Langer Trennstrich. Wird vor allem bei Währungen verwendet: DM 5,—
— Halbgeviert: Gedankenstrich, zum Beispiel für Einschübe im Text. Falls nach diesem Zeichen kein Whitespace folgt (sondern Text), dann wird eine lange Option daraus (also –info).
** Geschütztes Leerzeichen: Wird nicht umbrochen, hält also die Wörter links und rechts davon zusammen. Beispiel: Red**Hat.
:* Interpunktionsraum: Trennlücke zwischen den Ziffern einer großen Zahl. Ist im Grunde ein halbes Leerzeichen. Beispiel: 25:*000.
“Anführungszeichen (“): Werden im Text durch die typografisch korrekten Anführungszeichen ersetzt. Im Code und in Listings bleiben aber die geraden Anführungszeichen erhalten.
Listings
Listings erfahren an einigen Stellen eine Sonderbehandlung. Die Zeilenumbrüche bleiben erhalten, auch die Anführungszeichen bleiben gerade und werden nicht zu typografischen Anführungszeichen (die gebogene, links unten und rechts oben angesiedelte Variante). Außerdem sind dort keine Zeichenformate <I>, <B> und so weiter möglich, da sonst ein HTML-Listing zur Qual würde.
Zwei Dinge sind trotzdem auch dort auszeichenbar: Kursiv ist für Platzhalter wichtig (wie bei Code im Lauftext) und die unerwünschten Zeilenumbrüche sollte ein Autor lieber durch den gebogenen Pfeil ersetzen. Dazu gibt es folgende Syntax, die wohl ausreichend “krank” ist, um in keinem normalen Listing vorzukommen:
<§§I> Zeichenformat kursiv, dient als Ein- und Ausschalter wie bei den anderen Zeichenformaten.
§§ Nur am Zeilenende: Wird dort durch den gebogenen Pfeil ersetzt. Der ist nötig, wenn eine überlange Listingzeile über die Druckzeile hinauslaufen würde. Entspricht damit dem Backslash am Zeilenende in vielen Programmiersprachen.
Ist ein Listing länger als zehn Zeilen, dann erhält es automatisch Zeilennummern. Die machen den Umbruch einfacher, weil die Zeilennummern klar machen, wo wirklich eine neue Zeile beginnen soll.
Konventionen
Code
Code-Schnipsel, Datei- und Verzeichnisnamen, Eingabe-Anweisungen, Variablen, Befehle, Menüs, Funktionen und Ähnliches unterscheiden sich vom normalen Text. Als formale Sprache sind sie nicht einfach “mitzulesen”, sondern haben ihre ganz besondere Bedeutung. Dieser Umstand wird durch eine spezielle Auszeichnung verdeutlicht.
Wenn Code in eigenen Absätzen steht, ist er durch Courier-Schrift gekennzeichnet: @LI:, in den Absätzen stehen um jedes Stückchen Code die Tags <C>code<C>. Diese mutieren dann zu den passenden französischen Anführungszeichen, so ähnlich wie »code«.
Platzhalter (Wildcards) im Code, also alles, was der Leser/Anwender selbst durch den konkreten Wert zu ersetzen hat, sind kursiv. Kommt vor allem bei Shell-Kommandos vor, also <C>vi <I>Dateiname<I><C>. Steht der Dateiname aber schon fest, dann lautet das Kommando <C>vi /etc/passwd<C>.
Je nach Text kann die konsequente Auszeichnung aber auch stören und ist eigentlich oft unnötig. (Merke: Der Leser ist nicht auf den Kopf gefallen.) Also: Statt fünfmal in einem Absatz auf <C>printf()<C> zu verweisen, genügt es oft, dies nur beim ersten Mal zu tun und dann die Printf-Funktion zu nehmen.
Menüs
In Menüs ist die Abtrennung der Untermenüs nicht ganz einfach. Bindestriche sind nicht eindeutig (sie können auch im Menü vorkommen), Schrägstriche verwirren erst recht (soll das jetzt ein Verzeichnis sein?). Also bleibt das Pipe-Symbol: <C>Datei | Öffnen<C> als Code ausgezeichnet.
Tasten
In Anleitungen ist es oft nötig, Tastenkombinationen zu beschreiben. Hier ist noch zwischen gleichzeitig zu drückenden Tasten und Folgen von Tastendrücken zu unterscheiden.
Jede einzelne Taste wird in eckigen Klammern gesetzt: zum Beispiel [Strg] für die Sondertaste, bei einzelnen Buchstaben nur [Q]. Und zwar großgeschrieben, so steht es ja auch auf der Taste. Ist explizit der Großbuchstabe gemeint, dann ist das durch [Shift]+[Q] zu verdeutlichen.
Sind Tasten gleichzeitig zu drücken, dann werden sie mit einem + verbunden: [Shift]+[Q] hatten wir ja schon als Beispiel. Sind sie nacheinander zu drücken, dann durch ein Komma trennen: [Esc], [W].
Welche Namen Sondertasten bekommen, hängt von der Zielgruppe ab: Dem Unix-Urgestein sollten wir kein [Umschalt] vorsetzen und der Anfänger und Windows-Umsteiger hat vielleicht mit [Shift] Probleme. Wenn die Tasten auf der deutschen Tastatur beschriftet sind, dann ist diese Abkürzung am besten.