An dtdocs beitragen

Diese Seite zeigt den Stil Guide für dtdocs und Informationen, wie du zu diesem Projekt beisteuern kannst.

Es wird in das Benutzerhandbuch eingefügt, damit du sehen kannst, wie die Seite zusammengestellt wird und wie es geschrieben wird. Bitte gehe zu GitHub, um die Quelle für diese Seite zu sehen.

Die Struktur der Anleitung und der Inhalt wurden ausgewogen ausgewählt nach den folgenden Kriterien:

  1. Die Anleitung soll umfassend sein – sie sollte alle in darktable enthaltenen Funktionalitäten beschreiben
  2. Es muss eine konsistente und logische Struktur haben und jedes Teil der Funktionalität soll seinen eigenen logischen Platz in dieser Struktur haben
  3. Es soll so lange wie nötig, aber so kurz wie möglich sein – Kürze ist ein Muss
  4. Es soll objektiv sein
  5. Funktionalitäten sollen einmal erklärt werden und nur einmal (mit der Ausnahme die grundlegenden Richtlinien des Arbeitsablaufes in der Übersicht eines Abschnittes)
  6. Bilder sollen nur dort eingefügt werden, wo das nötig ist, um die Verständlichkeit der Schlüssel-Prinzipien zu verbessern und sie sollte keinen Text haben, ohne es sei unausweichlich

Wir sind grundsätzlich nicht interessiert an:

  1. Das Handbuch zu restrukturieren
  2. Markup Sprachen zu wechseln
  3. Detaillierte Tutorials zum Arbeitsablauf (obwohl wir interessiert daran sind, solche in Blogs entweder auf dartable.org oder pixls.us zu publizieren

Wir sind interessiert an

  1. Rechtschreibungs- und Grammatik-Korrekturen
  2. Klärungen des Textes
  3. Dokumentationen zu neuen Möglichkeiten

Wir sind immer extrem daran interessiert zu hören über welche Abschnitte der Anleitung keinen Sinn ergeben, und warum, sodass wir die Dokumentation verbesser können.

Generell, falls du eine größere Änderung machen möchtest, dann eröffne ein anliegen und diskutiere es zuerst mit jenen, die es warten. Das ist vor allem, um zu verhindern Arbeiten zu machen, die nicht akzeptiert werden.

🔗Format

Diese Webseite wird in sauberem Markdown geschrieben, mit der Nutzung von einigen Erweiterungen. Es ist ursprünglich so gestaltet, um mit Hugo SSG zu arbeiten, aber vorgesehen, dass es übertragbar genug, dass es leicht mit einer anderen Anwendung zusammengestellt werden könnte, sollte das nötig sein.

Dateien sollte mit UTF-8 zusammengestellt werden und keine Spalten-Struktur 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: Sub Section 1 Title
id: subsection1
weight: 10
---
title
Dieser sollte den bearbeiteten titel deiner Seite enthalten. Um einen Doppelpunkt in einem 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

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

  • 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 außer den obersten Kapitel-Namen (gilt für die Version in Englisch)

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

  • Die Führungssprache ist Englisch

  • 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

🔗Definitionslisten

Die Standard-Methode, um Informationen über darktable-Modul-Einstellungen zu präsentieren, 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 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, 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.

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
Mit der Ausnahme von Icons werden Bilder als standesmäßig als Block-Elemente eingebunden. Du kannst das aufheben mit dem Term #inline nach dem Bilder-Namen. Das kann kombiniert werden mit der Breite wie folgt.
![squirrel](./contributing/squirrel.png#w25#inline) ergibt die Ausgabe 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