Wir haben den Branch "WIP". Bitte nur darin am Handbuch arbeiten.

Wir würden uns freuen, wenn du bei der Übersetzung in eine Sprache deiner Wahl helfen könntest.

Eine Übersicht und den Status der MarkDown Dokumente innerhalb des siduction Handbuchs enthält die Wiki-Seite DE_Status-der-Handbuchseiten. Wenn eine neue Seite erstellt wird, bitte ein Issue anlegen und die Statusseite erweitern.

Um Handbuchseiten online zu bearbeiten einfach in der Statusseite die Dateinamen auswählen oder in den Ordner https://github.com/siduction/sidu-manual/tree/WIP/data/de wechseln und dort die Datei auswählen.

Um auf dem lokalen Rechner zu arbeiten einfach das Git-Repository des siduction Handbuchs klonen oder einen Pull Request durchführen. Damit das Ergebnis lokal annähernd vergleichbar dargestellt wird, verwenden wir Firefox mit dem Markdown Viewer Webext PlugIn. Die dabei verwendeten Einstellungen stehen in der Datei /development/css_FF_Plugin_Markdown-Viewer-Webext.
Die Einstellungen des Plugin lauten:
markdown "github"
code style "default"

In Bezug auf Markdown halten wir uns an die GitHub Flavored Markdown Spec und die nachfolgend genannten Spezifikationen.

Die Dateinamen des neuen Handbuches beginnen mit einer vierstelligen Ziffer gefolgt von einem Bindestrich.
Die ersten zwei Ziffern ordnen die Datei der Hauptgruppe zu, z.B. "03XX-" für die Hauptgruppe "Installation".
Ziffer drei und vier reiht die Datei innerhalb der Hauptgruppe ein.
Lücken in der Ziffernfolge sind für die Erzeugung der .html-Dateien und des PDF unschädlich und für eventuell zukünftig hinzukommende Dateien sinnvoll.

Gleichnamige Dateien ohne vorangestellte vierstellige Ziffer dienen der Verbesserung und Aktualisierung bereits veröffentlichter Kapitel.
Andere Dateien ohne vorangestellte vierstellige Ziffer betreffen Kapitel, die in Zukunft in das Handbuch eingehen.

1. Titel
   Jede .md-Datei benötigt in der ersten Zeile einen Titel in der Notation % Mein Titel. Der Text des Titels darf ruhig von der ersten im Dokument verwendeten Überschrift abweichen. Er ist für die Erstellung der .html-Dateien notwendig und wird im Webbrowser in der Titelzeile oder dem Tab angezeigt.

2. Überschriften

   • Überschriftenklassen:

     • #
       Nur für Hauptgruppen und nur einmal in der ersten Datei der Hauptgruppe verwenden.
       Hauptgruppen sind z.B.: "Installation", "Systemadministration" oder "Netzwerk".
     • ## und ###
       Standard in den .md-Dateien.
     • ####
       Selten bis nicht anzutreffen in .md-Dateien.
       Diese Überschriften integriert pandoc (LaTex) als fett ausgezeichneten Text in die erste Zeile des folgenden Absatzes. Das führt besonders bei folgenden Listen oder Tabellen zu unerwarteten und unerwünschten Effekten. Meistens ist eine Zeile mit fettem Text sinnvoller.

   • Sonderzeichen
     Erlaubt sind das Leerzeichen, der Punkt und der Bindestrich bzw. das Minuszeichen.
     Verboten sind diese, und noch viele weitere Zeichen, weil eine Verlinkung auf Überschriften mit diesen Zeichen nicht möglich ist:

     , ; : ! ? ^ " ´ ` ' „ “ § $ % & / \  
     ( ) { } [ ] + * ~ # | < > » « &#8482 &gth;
     

   • Überschriften einzigartig, prägnant und kurz
     Überschriften, auf die eventuell verlinkt wird, müssen einzigartig sein.
     Überschriften sollen kurz sein.

   • Sparsam mit Überschriften umgehen
     Bitte Überschriften sparsam einsetzen.
     Eine Überschrift, dann ein Absatz mit zwei oder drei Zeilen und wieder eine Überschrift ist Unsinn.

3. Link zu Überschriften
   Soll auf Handbuch interne Seiten verlinkt werden, muss der Link immer den Dateinamen und einen Anker enthalten.

   • Richtige Schreibweise des Link
     Nach dem Dateinamen folgt immer die Raute "#" und die Zielüberschrift (Sprungadresse bzw. Anker).
     Es gilt vollständige Kleinschreibung und Leerzeichen sind durch "-" zu ersetzen.
     Das folgende Beispiel bezieht sich auf die Überschrift "### Copyright Rechts- und Lizenzhinweise" im .md-Dokument "0000-welcome_de.md".

     [Siehe Copyright](0000-welcome_de.md#copyright-rechts--und-lizenzhinweise)
     

4. Überschriftenlisten
   Die Dateien headinglinks-de-by-file und headinglinks-de-by-text unterstützen dich beim Verlinken auf Handbuch internen Seiten.

5. Warnungen
   Bei besonders wichtigen Hinweisen die Zeilen quoten: "> "
   Das erzeugt in MD ein Zitat (einen Einzug mit grauem, senkrechten Balken und ausgegrauter Schrift), in PDF- und .html-Dokumenten ein farblich hinterlegtes Blockelement mit Padding.

   • Zeilenumbruch innerhalb der Warnungen:
     Die Zeilen müssen mit zwei Leerzeichen enden!
     Beispiel:

     Achtung:
     Damit gehen alle Daten verloren!

     So sieht der Qulltext aus:

     > **Achtung**  
     > Damit gehen alle Daten verloren!
     

6. Footer in den neuen Dateien
   Die letzte Zeile der .md-Dateien enthält den Bearbeitungshinweis in HTML-Notation:

   <div id="rev">Zuletzt bearbeitet: 2021-05-04</div>
   

   Er wird in .md-Dateien (nur lokal im FF) und .html-Dateien rechtsbündig, verkleinert und ausgegraut dargestellt.

7. Codeblock
   Innerhalb dieses Bereiches findet kein parsen durch MarkDown statt. Die zusätzlichen Textauszeichnungen *, **, ` und ~~ haben keine Wirkung auf den Text und werden, ebenso wie codierte Zeichen &gth;, literal dargestellt.

   • Anfang und Ende des Codeblocks
     Vor und nach dem Block jeweils eine Leerzeile einfügen. Die erste und die letzte Zeile besteht aus drei Tilden "~~~". Dies hat gegenüber der Einrückung um vier Leerzeichen den großen Vorteil, dass der Quelltext gut lesbar bleibt.
   • Kein Syntax Highlighting
     Wir verwenden kein Syntax Highlighting, da die Darstellung der Codeblöcke und des Inlinecodes farblich an die Erfordernisse von Menschen mit Farbsehschwäche angepasst wurde.
   • Zeilenumbruch in Codeblöcken
     Im PDF-Handbuch werden innerhalb von Codeblöcken die Zeilen bei mehr als 60 Zeichen, und bei Codeblöcken innerhalb von Listen bei mehr als 55 Zeichen, umgebrochen. Wann immer es möglich und sinnvoll ist, sollten die Zeilen innerhalb von Codeblöcken nicht länger sein, damit eine optisch gute Darstellung im PDF erreicht wird.
   • Codeblöcke in Listen
     Bei der Verwendung von Tilden für Code-Blöcke innerhalb von Listen bleibt der md-Code gut lesbar. Würde man stattdessen Einrückungen für die Code-Blöcke benutzen, geht spätestens ab der zweiten Ebene die Übersicht und damit die Lesbarkeit komplett verloren.
     Im unteren Beispiel (mit Tilden) sind die Einrückungen für beide Ebenen und Funktionen identisch. Quellcode und Bildschirmanzeige gleichen sich bis auf die am Bildschirm nicht sichtbaren Tilden.

   Musterliste:

   • Listenpunkt
     Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
     eirmod tempor invidunt ut labore et dolore magna aliquyam

     Code_Block  
     

     • Unterpunkt
       Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
       eirmod tempor invidunt ut labore et dolore magna aliquyam

       Code_Block_2  
       

   So sieht der md-Code aus:

       * Listenpunkt
         Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
         eirmod tempor invidunt ut labore et dolore magna aliquyam
   
         ~~~
         Code_Block
         ~~~
   
         * Unterpunkt
           Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
           eirmod tempor invidunt ut labore et dolore magna aliquyam
   
           ~~~
           Code_Block_2
           ~~~
   

1. fett und hervorgehoben
   Nur zur Verwendung für Text in technischem Kontext, der in dieser Form direkt in ein Terminal eingegeben werden kann, oder eine Ausgabe des Terminals darstellt.
   Innerhalb des hervorgehobenen Bereiches findet kein Parsen durch MarkDown statt. Die zusätzlichen Textauszeichnungen *, **, ` und ~~ haben keine Wirkung auf den Text und werden, ebenso wie codierte Zeichen &gth;, literal dargestellt.
   Die Darstellung wird mit doppeltem Asterisk und Backtick **` unmittelbar vor und in umgedrehter Reihenfolge unmittelbar hinter dem zu markierenden Text erzeugt.

   • Inline-Code, analog zu Quellcodeblöcken
     zum Beispiel nmcli dev wifi show
   • Bezeichnung von Tasten
     zum Beispiel ALT+CTRL+F2 oder Enter
     Bitte keine Leerzeichen vor und hinter dem "+".

2. hervorgehoben
   In Anlehnung an 1. bei Verwendung in technischem Kontext.
   Die Codierung erfolgt mit einem Backtick ` unmittelbar vor und unmittelbar hinter dem zu markierenden Text.

   • Alle Dateinamen, Programmnamen (sind ja auch Dateien) und Pfade
     zum Beispiel /home/user/filename, Inkscape
   • Befehlsoptionen und deren Werte
     zum Beispiel dev wifi show; vergleiche unter 1. den vollständigen Befehl
   • Variablen
     zum Beispiel IFS

3. fett
   bei Verwendung in technischem Kontext:

   • Benutzernamen, Gruppennamen
     zum Beispiel root oder user1 oder www-data.developer
   • Dateisystemtypen
     zum Beispiel ext4

   bei Verwendung in textlichem Kontext:

   • starke Betonung von Textstellen (Bitte sparsam verwenden.)
   • gelegentlich Ersatz für Überschriften 4. Ordnung (####)

4. kursiv und Anführungszeichen
   Alle zuvor genannten Elemente, wenn diese im Kontext als Zitat erscheinen.
   Zum Beispiel folgt auf einen Codeblock mit Befehlen Text mit Erklärungen. Der im Text zitierte Befehl und seine Optionen werden entsprechend formatiert.
   Bitte Kodierungsreihenfolge beachten: *"Beispiel"* ergibt "Beispiel", "*schlechtes Beispiel*" ergibt "schlechtes Beispiel". (Das "l" läuft in das schließende Anführungszeichen.)

5. kursiv
   bei Verwendung in textlichem Kontext:
   dezente Betonung von Textstellen (Bitte sparsam verwenden.)

6. kursiv und hervorgehoben
   zur Zeit nicht verwendet

Alles weitere, zum Beispiel Tabellen, Listen, Link oder Graphiken richtet sich nach GitHub Flavored Markdown Spec, allerdings mit einer Ausnahme.
Keine horizontalen Linen verwenden.

Stand 2022-04-25, Autor: davydych / ak-li