Blank lines and indentation
The separation and nesting of text body elements is done in reStructuredText using the following design elements:
Blank lines
- Blank lines are used in a reStructuredText to separate paragraphs and other text body elements (see Samples).
- Several consecutive blank lines are equivalent to a single blank line.
(Exception: in a Codeblock all blank lines are retained. - Blank lines can be omitted if a markup or indentation makes the separation of text body elements unambiguous.
- The first line in the comment is treated as if it were preceded by a blank line. The last line in the comment is treated as if it were followed by a blank line.
Paragraph and line breaks
- New paragraphs are indicated by blank lines (see Samples).
- Within paragraphs the text is displayed continuously and automatically wrapped when the window width of the Library Manager is reached. Simple line breaks in the comment do not cause line breaks in the display. To implement line breaks, line-oriented text blocks (line blocks) are used.
Indentation
- Indentations are used to identify nested contents (see Samples).
- Each line of text whose indentation is smaller than that of the current level ends the current level of indentation.
- Spaces or tabs can be used for indentation. Since all indentations are significant, the degree of indentation must be consistent.
Samples
Text block (paragraph)
If a paragraph or an other construct consists of more than one line of text, the lines must be left aligned.
This is a paragraph. The lines of
this paragraph are aligned at the left.
This paragraph has problems. The
lines are not left-aligned.
|
See also: Text block (paragraph)
Indented text block (block quote)
The indentation is the only marker for block quotes (indented text block).
- A blank line between a text block (paragraph or block quote) and a subsequent indented text block (block quote) is optional. The indentation of the following text block causes a break at the end of the previous text block. If a blank line is inserted in the comment, the line break occurs and the blank line remains in the display.
- A blank line is automatically displayed between an indented text block (block quote) and a subsequent text block that is not indented (paragraph or block quote), regardless of whether a blank line is inserted in the comment or not. The current level of indentation is ended.
- A blank line must be inserted in the comment between two text blocks (block quotes) on the same indentation level to separate the text blocks from each other.
This is a top-level paragraph.
This paragraph belongs to a first-level block quote.
This is the second paragraph of the first-level block quote.
This paragraph belongs to a second-level block quote.
Another top-level paragraph.
This paragraph belongs to a second-level block quote.
This paragraph belongs to a first-level block quote. The
second-level block quote above is inside this first-level
block quote.
|
See also: Indented text block (block quote)
Line-oriented text block (line block)
A line break can be implemented with a line block. Individual lines can be indented by indenting.
| Each new line begins with
| a vertical bar ("|").
| Line breaks and initial indents
| are preserved.
| Continuation lines are wrapped
portions of long lines; they begin
with spaces in place of vertical bars.
|
See also: Line-oriented text block (line block)
Simple and complex markup
Several constructs start with a markup. The body of the construct must then be indented relative to the markup.
For constructs with simple markup (unordered and ordered lists, footnotes, citations, hyperlink targets, directives and comments), the degree of indentation of the body is determined by the position of the first line of text starting on the same line as the markup.
- This is the first line of a bullet list
item's paragraph. All lines must align
relative to the first line. [1]_
This indented paragraph is interpreted
as a block quote.
Because it is not sufficiently indented,
this paragraph does not belong to the list
item.
.. [1] Here's a footnote. The second line is aligned
with the beginning of the footnote label. The ".."
marker is what determines the indentation.
|
For constructs with more complex markup, the indentation of the first line after the markup usually determines the left edge of the text body. If the markup is very long, it may be useful to start with the text body in the next line. The line after the markup must be indented by at least one space (minimum indentation).
:Field: This field has a short field name, so aligning the field
body with the first line is feasible.
:This field has a long field name: It would
be very difficult to align the field body with the left edge
of the first line.
:This field also has a long field name:
It would be very difficult to align the field body with the left edge
of the first line. It may even be preferable not to begin the
body on the same line as the marker.
|
See also: