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¶

See the overview on ReStructuredText for more information on how to style the various elements of the documentation and on how to add lists, tables, pictures and code blocks. The Sphinx reference provides more insight additional constructs.

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 View --> Add --> Mesh --> Monkey` – Menüs (3D View ‣ Add ‣ Mesh ‣ Monkey).

Codebeispiele¶

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 schön ist, sicherzustellen, dass alle Screenshots von ähnlicher Größe des sie umfließenden Textes sind, sollten Autoren Screenshots auf folgendem Weg erstellen:

Prepare the area you would like to capture making sure to use the default theme and setting. (In some cases you may not want to use the default settings e.g. if some options are hidden behind a checkbox.)
Zoom to the maximum zoom level (hold NumpadPlus or Ctrl-MMB or similar).
Zoom out eight zoom levels (NumpadMinus – eight times).
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

Use .png for images that have solid colors such as screenshots of the Blender interface, and .jpg for images with a high amount of color variance, such as sample renders and photographs.

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¶

Avoid specifying the resolution of the image, so that the theme can handle the images consistently and provide the best layout across different screen sizes.
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 von YouTube^™ und Vimeo^™ können eingebettet werden. Benutzen Sie dazu:

.. youtube:: ID

.. vimeo:: 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
Die ID für https://vimeo.com/15837189 ist 15837189

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.80.
: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 Glossary, Beispiel: Manifold (Mannigfaltig).

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>`__

Directory Layout¶

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 Anschnitt 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.