Skip to content

DE_Home

Jump to bottom
ak-li edited this page Mar 29, 2022 · 24 revisions

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

  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. Quellcode Block
    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.

    • Absätze, Qellcode
      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 zwei wichtige Vorteile.
      • Es ist Syntax Highlighting realisierbar, indem nach den ersten Tilden der Dialekt angegeben wird. z.B.: ~~~sh
      • Die Einrückungen innerhalb von Listen sind für Code-Blöcke und Text bei Verwendung der Tilden gleich. Wenn nur Leerzeicheneinrückung für beide Funktionen vorgenommen wird, 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.

    • Text

      Code_Block

      • Text

        Code_Block_2

    So sieht der md-Code aus:

        * Text

      ~~~
      Code_Block
      ~~~

      * Text

        ~~~
        Code_Block_2
        ~~~

MD-Code für Inline Elemente

  1. fett und hervorgehoben
    Nur zur Verwendung in technischem Kontext für Text, 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 einfachem Asterisk und Backtick *` unmittelbar vor und in umgedrehter Reihenfolge 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.

Sonstiger MD-Code

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

Stand 2022-03-29, Autor: ak-li

Clone this wiki locally