DE_Home

Willkommen zum sidu-manual wiki!

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.

Hinweise für Autoren

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.

Dateinamen

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.

MD-Code für Blockelemente

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.
Ü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.
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)
```
Überschriftenlisten
Die Dateien headinglinks-de-by-file und headinglinks-de-by-text unterstützen dich beim Verlinken auf Handbuch internen Seiten.
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!
```
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.
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
        ~~~
```

MD-Code für Inline Elemente

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 "+".
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
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 (####)
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.)
kursiv
bei Verwendung in textlichem Kontext:
dezente Betonung von Textstellen (Bitte sparsam verwenden.)
kursiv und hervorgehoben
zur Zeit nicht verwendet

Sonstiger MD-Code

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly