styles and conventions

The following details the writing style and documentation conventions used in this manual.

🔗Format

Diese Webseite wird in reinem Markdown mit einigen Erweiterungen geschrieben. Sie ist ursprünglich zur Verwendung mit Hugo SSG gestaltet worden. Eine Portablilität ist intendiert, sodass die Seite einfach mit einer anderen Anwendung prozessiert werden kann, falls notwendig.

Dateien sollten in UTF-8 gerendert werden und keine Spaltenumbrüche enthalten.

🔗Struktur

Als Folge wird die Struktur an einem Beispiel eines Hauptkapitels mit Unterkapiteln in der dtdocs Webseite gezeigt.

Beispiel-Kapitel
 _index.md
 Abschnitt1-mit-Unterabschnitten/
 Abschnitt1/
 Bild.png
 _index.md
 Unterabschnitt1.md
 Unterabschnitt2.md
 Abschnitt2.md
 Abschnitt3.md

A couple of notes on the above structure:

  • _index.md enthalten keinen Inhalt (sie enthalten nur Metadaten) und werden gebraucht um Abschnitts-Titel mit ToC Einträgen zu verbinden. Im obigen Beispiel definiert example-chapter/_index.md den titel des Beispiel-Kapitels und die Reihenfolge in welcher es im Haupt-Inhaltsverzeichnis erscheint. Gleichermaßen definiert example-chapter/section1-with-subsections/_index.md Metadaten für den ersten Abschnitt des Kapitels.

  • Media-Dateien sollten in einem Verzeichnis mit dem gleichen Namen, wie die Seite haben, auf die sie Bezug nehmen. In diesem Beispiel, example-chapter/section1-with-subsections/subsection1 enthält die Media, die zur Seite subsection1.md gehören.

🔗Metadaten

Metadaten von den Markdown Dateien sind am Kopf der Seite mit yaml präsentiert. Alle Metadaten sollen definiert werden – Die Abschnitte der Modul-Referenzen enthalten eine große Anzahl spezifischer Metadaten – aber das folgende definiert einige minimale Metadaten für die Beispiel-Seite example-chapter/section1-with-subsections/subsection1.md.

---
title: Sub Section 1 Title
id: subsection1
weight: 10
---
title
Dieser sollte den bearbeiteten Titel deiner Seite enthalten. Um einen Doppelpunkt in einen Titel zu integrieren, setze den Titel in Anführungszeichen.
id
Das ist die ID, die gebraucht wird, dass Hugo die Seite identifizieren kann. Sie sollte normalerweise den gleichen Namen haben wie die Datei (für Inhalt-Dateien) oder des Eltern-Verzeichnisses (für _index.md Dateien).
weight
Das ist ein optionales Metadatenfeld, das gebraucht wird, um die Reihenfolge im Inhaltsverzeichnis zu definieren. Falls das Feld weight nicht inbegriffen ist, werden die Seiten in alphabetischer Reihenfolge oder Standardreihenfolge zusammengestellt. Zum Beispiel, um die Abschnitte und Unterabschnitte des obigen Beispiels in umgekehrter Reihenfolge zu definieren, müssten die folgenden Metadaten gesetzt werden:
   example-chapter/
 section1-with-subsections/
 _index.md  # weight: 30 (place section1 page at the end of example-chapter)
 subsection1.md  # weight: 20 (place subsection1 page at the end of section1)
 subsection2.md  # weight: 10 (place subsection2 page at the start of section1)
 section2.md  # weight: 20 (place section2 in the middle of example-chapter)
 section3.md  # weight: 10 (place section3 at the start of example-chapter)

🔗Inhalt

🔗Generelle Anhaltspunkte für den Stil

  • All content should be authored in plain markdown without shortcodes and HTML should be kept to an absolute minimum, if used at all

  • Minimalismus ist ein absolutes Muss. Weniger Worte sind vorzuziehen

  • Markdown-Dateien sollen so kurz wie möglich sein

  • Folge den Namensgebungs- und Kapitelaustattungs-Normen aus GUI der Anwendung – namentlich sollen alle Kopfzeilen und Titel in Kleinbuchstaben sein ausser den obersten Kapitel-Namen Gleich nutze Kleinbuchstaben, bei der Referenzierung auf Modulnamen und Befehle.

  • Kopfzeilen in einer Datei sollten den Level drei (###) nicht übersteigen

  • Die Erstsprache und Sprache des Verfassens ist Englisch. Vermeide eine idiomatische Sprache, denn das Englisch der Dokumentation kann auch von Leuten gelesen werden, deren Muttersprache nicht Englisch ist.

  • Gehe davon aus, dass der Leser die Anwendung geöffnet hat, wenn er die Anleitung liest und setze nur dort Bilder ein, wo diese zur Erklärung einer komplexen Funktionalität beitragen

  • Nutze Bild-Textboxen, falls du ein Bild kommentieren musst (z.B. markiere Teile des Bildes mit einem Buchstaben oder einer Zahl und erkläre die Bedeutung in Text, der dem Bild folgt). Platziere keine Worte direkt im bild für Anmerkungen, da dies die genaue Lokalisierung schwierig macht. Siehe diese Seite als Beispiel.

  • Änderungen zum Inhalt sollten mit einem Pull Request oder einem ähnlichen Mechanismus vorgeschlagen werden

  • Deine Beiträge werden lektoriert – nimm es nicht persönlich

🔗Tastatur und Maus Kurzbefehle

  • Verweise auf Tastatur-Tasten mit dem Gebrauch von CamelCase (Ctrl, Shift, Alt, Esc, AltGr, CapsLock, PageUp, PageDown)

  • Referenziere einzelne Buchstaben-Tasten mit Kleinbuchstaben (das vermeidet Konfusionen zwischen zum Beispiel Ctrl+H und Ctrl+Shift+h). Anführungszeichen ergeben Klarheit (drücke “h” um eine Liste von aktiven Kurzbefehlen anzuzeigen).

  • Referenz-Mausaktionen in Kleinschreibung, mit mehreren Wörtern, die durch einen Bindestrich verbunden sind (scroll, click, single-click, double-click, right-click)

  • Verbinden Sie Kombinationen von Tasten/Aktionen mit einem Pluszeichen (Ctrl+Shift+h, Shift+double-click)

🔗Definitionslisten

The standard method of presenting information about darktable module controls is with the use of definition lists.

GUI Kontroll-Name
Eine Deklaration, von dem, was die Einstellung macht. Zum Beispiel “Setze die Belichtung in EV Einheiten”.

Du kannst so viele Paragrafen einschließen, wie du willst, aber versuche es auf 2 oder 3 zu limitieren.

active-icon eine Einstellmöglichkeit, die mit einem Icon angewählt werden kann
Wenn eine Einstellmöglichkeit mit einem Icon angewählt wird, dann nehme einen Screenshot des Icons im Standard darktable Theme (darktable elegant Grau), und setze es eine vor dem Namen der Einstellung
GUI Combobox Name
Comboboxes haben oft mehrere Optionen, die alle angezeigt werden müssen mit separaten Definitionen. Nutze eine Liste mit Aufzählungszeichen mit Kursiv für die Werte der Combobox.
  • der erste Wert: Was bedeutet der erste Wert
  • der zweite Wert: Was bedeutet der zweite Wert

Definitionslisten werden auch während des gesamten Dokumentes gebraucht, wo immer ein Stück Funktionalität definiert werden muss. Siehe zum Beispiel, darktable-cli.

🔗Notizen

Falls du eine wichtige Notiz für den Nutzer präsentieren willst, dann nutze das folgende Format:

Beachte: Das ist eine wichtige Notiz.

🔗Fixierte Fonts-Abstände und Codeblocks

Fixe Abstände für Fonts (mit dem ` Zeichen) sollten normalerweise nur für Codeblocks verwendet werden für Referenzen auf Dateinamen oder Kommandolinien-Parameter.

Interne Links müssen relativ zur jetzigen Datei sein und müssen auf eine gültige Markdown-Datei (.md) zielen. Starte Links entweder mit ./ um das jetzige Verzeichnis oder ../, um auf das übergeordnete Verzeichnis zu repräsentieren.

🔗Bilder

Bei Screenshots der aus darktable Anwendung nutze das Standard-Theme von darktable (darktable-elegant-Grau)

Mehrere Dateinamen-Endungen können dazu benutzt werden, wie Bilder dargestellt werden.

Icon
Um ein Bild als Icon einzusetzen, schließe #icon nach dem Bildnamen in den Link ein: Die Markdown ![squirrel icon](./contributing/contributing.png#icon) gibt den folgenden Output: squirrel icon
Bild Breite
You can set the image width to 25, 33, 50, 66, 75 or 100 per cent of the rendered page width by including #wxx after the image name in the link, where xx is the desired width. For example:
![squirrel](./contributing/squirrel.png#w25) outputs
squirrel
![squirrel](./contributing/squirrel.png#w75) outputs
squirrel
inline
With the exception of icons, images are included as block elements by default. You can override this by including #inline after the image name. This can be combined with the width setting as follows.
![squirrel](./contributing/squirrel.png#w25#inline) outputs squirrel
Standard
Standardmäßig werden Bilder als Block mit 100% Breite dargestellt. So ![squirrel](./contributing/squirrel.png#w100) und ![squirrel](./contributing/squirrel.png) sind äquivalent und geben beide das folgende aus:
squirrel

translations