Leitfaden zur Texthervorhebung¶

Diese Seite behandelt die Schreibkonventionen und die Benutzung der Hervorhebungssyntax von reStructuredText (RST).

Konventionen¶

Einrückung jeweils drei Leerzeichen.
Zeilen sollten weniger als 120 Zeichen lang sein.
Benutzen Sie Kursivschrift für Beschriftungen von Schaltflächen und Menüs.

Weitere lockere Konventionen:

Vermeiden Sie Unicode-Zeichen.
Vermeiden Sie stark umbrochenen Text (d.h. Sätze sollten ihre eigenen Zeilen haben).

Überschriften¶

#################
  Document Part
#################

****************
Document Chapter
****************

Document Section
================

Document Subsection
-------------------

Document Subsubsection
^^^^^^^^^^^^^^^^^^^^^^

Document Paragraph
""""""""""""""""""

Bemerkung

Parts-Überschriften sollten nur für Inhaltsverzeichnis- oder Index-Seiten verwendet werden.

Bemerkung

Jede .rst-Datei sollte nur eine Kapitelüberschrift (*) haben.

Texthervorhebung¶

Besuchen Sie die Übersicht über ReStructured Text für weitere Informationen zur Schreibweise der verschiedenen Elemente der Dokumentation und wie man Listen, Tabellen, Bilder und Codeblöcke hinzufügt. Die Sphinx-Referenz liefert mehr Einblicke in zusätzliche Konstrukte.

Es folgen hilfreiche Textauszeichnungen zur Texthervorhebung:

*italic*
**bold**
``literal``

Schnittstellen-Elemente¶

:kbd:`LMB` – Tastatur- und Maus-Kürzel (Darstellung des Beispiels: LMB ).
*Mirror* – Beschriftungen der Benutzeroberfläche (Mirror).
:menuselection:`3D Viewport --> Add --> Mesh --> Monkey` – Menüs.

Code-Beispiele¶

Syntaxhervorhebung wird unterstützt, sofern die Sprache angegeben ist und Zeilennummern können optional mit der :linenos:-Option dargestellt werden:

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Bilder¶

Um Bilder zu platzieren werden Figuren benutzt:

.. figure:: /images/render_cycles_nodes_types_shaders_node.png

   Image caption.

Für die Kontinuität und weil es gut wäre, sicherzustellen, dass alle Screenshots von ähnlicher Größe sind, wenn sie von Text umflossen werden, sollten Autoren Screenshots auf folgendem Weg erstellen:

Bereiten Sie den von Ihnen gewünschten zu erfassenden Bereich vor, indem Sie das Standard-Thema und -Einstellungen benutzen. (In einigen Fällen können Sie von den Standard-Einstellungen abweichen, wenn z. B. Einstellungen hinter einer Checkbox versteckt sind.)
Zoomen Sie bis zur maximalen Vergrößerung (halten Sie dazu NumpadPlus oder Strg-MMB oder ähnliches)
Zoomen Sie acht Stufen heraus (NumpadMinus – acht mal)
In manchen Fällen werden Sie einen kleinen Rand um das zu Erfassende lassen wollen. Dieser sollte etwa 30 Pixel dick sein, aber das muss nicht exakt sein.

Dies kann auf die meisten Teile der Benutzeroberfläche angewendet werden, aber funktioniert vielleicht nicht für alle Fälle.

Dateien¶

Keine Großbuchstaben, keine Leerzeichen

Nur Kleinbuchstaben und Unterstriche zwischen den Wörtern.

Hilfreich Sortieren

Ordnen Sie die Namen durch spezifische Kennungen am Ende.

Dateiformat

Benutzen Sie .png für Bilder mit festen Farben, wie z. B. in Screenshots der Oberfläche von Blender, und .jpg für Bilder mit hoher Farbstreuung, wie z. B. gerenderten Bildern und Photographien.

Benutzen Sie keine animierten .gif-Dateien, denn sie sind schwierig aktuell zu halten, können ablenkend sein und haben meistens hohe Dateigröße. Benutzen Sie im Bedarfsfall ein Video (siehe Videos unten).

Speicherort

Legen Sie die Bilder in den manual/images-Ordner ab. Benutzen Sie keine Unterordner.

Benennung

Bei der Benennung von Dateien benutzen Sie Unterstriche um Kapitel und Abschnitte zu trennen und Minuszeichen zwischen mehreren Wörtern eines Abschnittes. Namen von Bilddateien sollten so aussehen Kapitel_Abschnitt_Unter-Abschnitt_id.png, z.B:

interface_splash_current.png
interface_undo-redo_last.png
interface_undo-redo_repeat-history-menu.png

Benutzen Sie keine Sonder- oder Leerzeichen!

Hinweise zur Verwendung¶

Vermeiden Sie die Angabe der Bildauflösung, damit das Thema die Bilder konsistent behandeln kann und das beste Layout für unterschiedliche Bildschirmgrößen zur Verfügung stellen kann.
Bei der Beschreibung eines Panels oder Abschnittes der Bedienoberfläche ist es besser ein einzelnes Bild zu verwenden, dass alle relevanten Bereiche zeigt (, als mehrere Bilder für jedes Icon oder jeden Knopf). Dieses wird am Anfang des zu schreibenden Kapitels platziert und danach werden die Funktionen in der Reihenfolge ihres Erscheinens beschrieben.

Bemerkung

Es ist wichtig, dass das Handbuch langfristig gepflegt werden kann. Da sich Benutzeroberfläche und die Werkzeugoptionen ändern sollte es vermieden werden, viele Bilder zu haben (wenn es nicht unbedingt notwendig ist); ansonsten wird daraus ein zu hoher Wartungsaufwand.

Videos¶

Videos from YouTube^™ can be embedded using:

.. youtube:: ID

Die ID ist in der URL des Videos zu finden, z.B.:

Die ID für https://www.youtube.com/watch?v=Ge2Kwy5EGE0 ist Ge2Kwy5EGE0

Hinweise zur Verwendung¶

Fügen Sie keine auf Stimme basierenden Videos hinzu, da dies schwierig zu übersetzen ist.
Betten Sie keine Video-Anleitungen ein um eine Funktion zu erklären, das Geschriebene selbst sollte sie vollwertig erklären (jedoch können Sie ein Link auf das Video am Ende der Seite unter der Überschrift Tutorials einfügen).

Hilfreiche Konstrukte¶

|BLENDER_VERSION| – Wird zur aktuellen Blender-Version aufgelöst, aktuell: 2.83.
:abbr:`SSAO (Screen Space Ambient Occlusion)` – Abkürzungen zeigen dem Leser den kompletten Text als Tool-Tipp, Beispiel: SSAO.
:term:`Manifold` – Verlinkt zu einem Eintrag im Glossar.

Querverweise und Verlinkung¶

Sie können andere Dokumente im Handbuch verlinken mit:

:doc:`The Title </section/path/to/file>`

Um ein bestimmtes Kapitel in einem anderen Dokument (oder demselben) zu verlinken gibt es explizite Sprungziele:

.. _sample-label:

[section or image to reference]

Some text :ref:`Optional Title <sample-label>`

Verweise auf eine Überschrift innerhalb einer Datei:

Titles are Targets
==================

Body text.

Implicit references, like `Titles are Targets`_

Verweise auf externe Seiten:

`Blender Website <https://www.blender.org>`__

Ordnerstruktur¶

Kapitel sollten generell wie folgt strukturiert sein:

Ordnername/
- index.rst (Enthält Links auf interne Dateien)
- introduction.rst
- Kapitel_1.rst
- Kapitel_2.rst

Zum Beispiel:

rendering/
- index.rst
- cycles/
  - index.rst
  - introduction.rst
  - materials/
    - index.rst
    - introduction.rst
    - volumes.rst

Der Plan ist es, dass ein Ordner den gesamten Inhalt eines Abschnittes enthält. Jeder Abschnitt sollte idealerweise eine index.rst (enthält das Inhaltsverzeichnis des Abschnittes) und eine introduction.rst mit (einer Einführung zu) dem Inhalt aufweisen.

Inhaltsverzeichnis¶

Standardmäßig sollte ein Inhaltsverzeichnis zwei Tiefenebenen darstellen:

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

Weiterführende Literatur¶

Um mehr über reStructuredText zu lernen:

Sphinx RST Fibel: Gute grundlegende Einführung.
Docutils reStructuredText Referenz: Verweist auf die Entwickler- und die Benutzerdokumentation.