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 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/interface_window-system_splash_current.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:

  1. 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.)

  2. Zoomen Sie bis zur maximalen Vergrößerung (halten Sie dazu NumpadPlus oder Strg-MMB oder ähnliches)

  3. Zoomen Sie acht Stufen heraus (NumpadMinus – acht mal)

  4. 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 can be embedded from Blender’s self-hosted PeerTube instance which can be found at video.blender.org. To embed a video using the following directive:

.. peertube:: ID

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

The ID for https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c is 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

To get a new video uploaded, contact a Documentation Project Administrator or include the uploaded video in your Patch description.

Hinweise zur Verwendung

  • Avoid adding videos that rely on voice or words, as this is difficult to translate.

  • Do not embed video tutorials as a means of explaining a feature, the writing itself should explain it adequately. (Though you may include a link to the video at the bottom of the page under the heading Tutorials).

Hilfreiche Konstrukte

  • |BLENDER_VERSION| – Wird zur aktuellen Blender-Version aufgelöst, aktuell: 3.4.

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

Context Sensitive Manual Access

It is possible to link to a specific part of the manual from in Blender by opening the context menu (right click) of a property or operator and selecting Online Manual. In order for this to work, this needs to be accounted for in the documentation. To link a property or operator to a specific part of the manual you need to add an external reference link tag whose ID matches Blender’s RNA tag. The easiest way to find out what the tag for a property is to open the context menu of the property/operator and select Online Python Reference to extract the tag from the URL. Some examples of how this looks in the RST document are given below:

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid / obstacle regions (second order obstacles)...

   .. _bpy.types.FluidDomainSettings.fractions_distance:

   Obstacle Distance
      Determines how far apart fluid and obstacles are...

For an operator:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Weiterführende Literatur

Um mehr über reStructuredText zu lernen:

Sphinx RST Primer

Gute grundlegende Einführung.

Docutils reStructuredText Reference

Verweist auf die Entwickler- und die Benutzerdokumentation.