Abschnitte
Abschnitte werden durch einen Titel und eine Nummerierung gekennzeichnet. Der Titeltext wird dabei im Kommentar mit „Unterstrichen“ oder mit „Unterstrichen" und passenden „Überstrichen“ versehen.
Eigenschaften
- Ein Unterstrich/Überstrich ist ein einzelnes Zeichen, das in der ersten Spalte beginnt und eine Zeile bildet, die mindestens bis zum rechten Rand des Titeltextes reicht. Bei Verwendung von Überstrichen müssen Länge und Zeichen mit den Unterstrichen übereinstimmen.
- Das Format von Titeltexten, die nur mit Unterstrichen oder die mit Unterstrichen und Überstrichen versehen werden, unterscheidet sich, auch wenn die gleichen Zeichen verwendet werden.
- Ein Unterstrich/Überstrich-Zeichen kann jedes nicht-alphanumerische 7-Bit-ASCII-Zeichen sein. Die folgenden sind Zeichen sind gültige Unterstrich/Überstrich-Zeichen für Abschnittstitel:
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
Folgende Zeichen werden empfohlen:
„=“, „-“, „*“ - Die Anzahl an Ebenen von Abschnittstiteln ist auf fünf Ebenen beschränkt.
- Das Unterstrich/Überstrich-Zeichen bestimmt nicht das Format des Titels. Dieses ergibt sich aus der Reihenfolge, in der die unterstrichenen bzw. unter- und überstrichenen Titel angetroffen werden. Der erste angetroffene Stil bildet den äußersten Titel, der zweite Stil ist ein Untertitel, der dritte ein Untertitel und so weiter. Titel, die mit einfachen Bindestrichen („-“) unterstrichen sind, werden unabhängig von der Position immer als Titel erster Ebene in grau und fett dargestellt.
Section Title | Section Title | Beide Codeausführungen führen zu folgender Darstellung im Bibliotheksverwalter:
|
- Es müssen nicht alle Formate für Abschnittstitel verwendet werden, und es muss auch kein spezifischer Stil für Abschnittstitel verwendet werden. Ein Kommentar muss jedoch in der Verwendung von Abschnittsüberschriften konsistent sein: Sobald eine Hierarchie von Titelstilen erstellt ist, müssen Abschnitte diese Hierarchie verwenden.
- Jedem Abschnittstitel wird automatisch ein Hyperlink-Ziel zugewiesen, auf das verwiesen werden kann. Der Referenzname des Hyperlinks entspricht dem Text der Abschnittsüberschrift (siehe Implizite Hyperlink-Ziele).
Beispiel
Das folgende Beispiel zeigt die Verwendung von Abschnitten und Überschriften in einem reStructuredText-Kommentar. Eine Leerzeile unter einem Titel ist optional. Alle Textblöcke bis zum nächsten Titel der gleichen oder höheren Ebene sind in einem Abschnitt (oder Unterabschnitt etc.) enthalten.
(Im Beispielprojekt: B_DocuElements\Comment structure\FB_Libdoc_Sections)
(*
Section Title
-------------
This document consists of two main sections and several subsections. All text blocks up to the next title of the same or higher level
are included in a section (or subsection, etc.).
================
1. Section Title
================
Sections are identified through their titles, which are marked up with adornment:
"underlines" below the title text, or underlines and matching "overlines" above the title.
-----------------
1.1 Section Title
-----------------
A document must be consistent in its use of section titles: once a hierarchy of title styles is established,
sections must use that hierarchy.
Rather than imposing a fixed number and order of section title adornment styles,
the order enforced will be the order as encountered.
The first style encountered will be an outermost title, the second style will be a subtitle,
the third will be a subsubtitle, and so on.
1.2.1 Section Title
===================
Underline-only adornment styles are distinct
from overline-and-underline styles that use the same character.
1.2.1.1 Section Title
*********************
An underline/overline is a single repeated punctuation character that begins in column 1
and forms a line extending at least as far as the right edge of the title text.
1.2.1.2 Section Title
*********************
1.2.2 Section Title
===================
-----------------
1.2 Section Title
-----------------
=================
2. Section Title
=================
-----------------
2.1 Section Title
-----------------
*)
|
