Stil & Konventionen

Der folgende Abschnitt beschreibt den Stil und die Konventionen, die in der Dokumentation verwendet werden.

🔗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

Einige Notizen zur obigen Struktur:

  • _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: Unterabschnitt 1 Titel
id: unterabschnitt1
weight: 10
include_toc: true
---
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, anhand derer Hugo die Seite identifiziert. 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)
include_toc
Optional, aktiviert oder deaktiviert das auskappbare Inhaltsverzeichnis. Sollte bei langen, komplexen Seiten verwendet werden.

🔗Inhalt

🔗Generelle Anhaltspunkte für den Stil

  • Alle Inhalte sollen in klarem Markdown ohne Abkürzungen geschrieben werden und HTML soll auf ein absolutes Minimum begrenzt werden, falls HTML überhaupt benutzt wird

  • 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 primär verwendete Sprache ist US-Englisch (dies ist die Sprache die in der Anwendung verwendet wird). Vermeiden Sie nach Möglichkeit Redewendungen und bildhafte Formulierungen, da die englische Version der Dokumentation auch von Personen gelesen wird, 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

🔗Technische Information der Dunkelkammer-Module

Für jedes der Dunkelkammermodule gibt es einen speziellen (ausklappbaren) Block technischer Informationen am Anfang der Seite:

{{< details summary="Technische Informationen" class="technical-info">}}

Beschreibung
:Bildet den Tonwertumfang einer Aufnahme nicht-destruktiv in den Dynamikbereich der Anzeige ab. Analog zu „klassischem“ Film durch Kompression von dunklen Schatten und hellen Lichtern.

Kategorie
:Korrekturen und Effekte.

Input
:linear oder nichtlinear, RGB, szenenbezogen.

Bearbeitung
:nichtlinear, RGB.

Output
:nichtlinear, RGB, anzeigebezogen.

{{< /details>}}

Dies sollte die als Tooltip zur Verfügung stehenden Informationen widerspiegeln, die erscheinen wenn die Maus über einem Dunkelkammermodul schwebt.

🔗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 Großbuchstaben (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

Die Standard-Methode, um Informationen über darktable-Modul-Einstellungen zu dokumentieren, ist der Gebrauch von Definitions-Listen.

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 durch eine Schaltflächen mit einem Symbol aktiviert werden kann
Wenn eine Einstellmöglichkeit durch einen Klick auf ein Symbol aktiviert wird, dann erstelle einen Screenshot des Symbols im Standard darktable Theme (darktable elegant Grau) und setze den Screenshot vor dem Namen der Einstellmöglochkeit ein.
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 im gesamten Dokument verwendet an allen Stellen, wo eine benannte Funktionalität definiert wird. 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](./styles-conventions/contributing.png#icon) gibt den folgenden Output: squirrel icon
image width
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](./styles-conventions/squirrel.png#w25) outputs
squirrel
![squirrel](./styles-conventions/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](./styles-conventions/squirrel.png#w25#inline) outputs squirrel
default
By default images are presented as block elements with 100% width. So ![squirrel](./styles-conventions/squirrel.png#w100) and ![squirrel](./styles-conventions/squirrel.png) are equivalent and both output the following:
squirrel

translations