Sections
Sections are identified by a title and numbering. The title text is marked with "underscores" or "underscores" and suitable "overlines" in the comment.
Properties
- An underscore/overline is a single character that starts in the first column and forms a line that extends at least to the right margin of the title text. If overlines are used, the length and characters must match the underscores.
- The format of title texts that only have underscores or underscores and overlines differs, even if the same characters are used.
- An underscore/overline character can be any non-alphanumeric 7-bit ASCII character. The following characters are valid underscore/overline characters for section titles:
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
The following characters are recommended:
“=”, “-”, “*” - The number of section title levels is limited to five.
- The underscore/overline character does not determine the format of the title. This results from the order in which the titles with underscore or underscore and overline are found. The first style encountered is the outermost title, the second style is a subtitle, the third a subtitle and so on. Titles that are underscored with simple hyphens ("-") are always displayed as first level titles in gray and bold, regardless of their position.
| | Both code executions lead to the following representation in the Library Manager:
|
- Not all section title formats have to be used, nor does a specific style have to be used for section titles. However, a comment must be consistent in the use of section headings: Once a hierarchy of title styles has been created, sections must use this hierarchy.
- Each section title is automatically assigned a hyperlink target, which can be referenced. The reference name of the hyperlink corresponds to the text of the section heading (see Implicit hyperlink targets).
Sample
The following sample shows the use of sections and headings in a reStructuredText comment. A blank line under a title is optional. All text blocks up to the next title of the same or higher level are included in a section (or subsection etc.).
(In sample project: 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
-----------------
*)
|
