You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
404 lines
11 KiB
404 lines
11 KiB
A ReStructuredText Primer |
|
========================= |
|
|
|
:Author: Richard Jones |
|
:Version: $Revision: 5801 $ |
|
:Copyright: This document has been placed in the public domain. |
|
|
|
.. contents:: |
|
|
|
|
|
The text below contains links that look like "(quickref__)". These |
|
are relative links that point to the `Quick reStructuredText`_ user |
|
reference. If these links don't work, please refer to the `master |
|
quick reference`_ document. |
|
|
|
__ |
|
.. _Quick reStructuredText: quickref.html |
|
.. _master quick reference: |
|
http://docutils.sourceforge.net/docs/user/rst/quickref.html |
|
|
|
.. Note:: This document is an informal introduction to |
|
reStructuredText. The `What Next?`_ section below has links to |
|
further resources, including a formal reference. |
|
|
|
|
|
Structure |
|
--------- |
|
|
|
From the outset, let me say that "Structured Text" is probably a bit |
|
of a misnomer. It's more like "Relaxed Text" that uses certain |
|
consistent patterns. These patterns are interpreted by a HTML |
|
converter to produce "Very Structured Text" that can be used by a web |
|
browser. |
|
|
|
The most basic pattern recognised is a **paragraph** (quickref__). |
|
That's a chunk of text that is separated by blank lines (one is |
|
enough). Paragraphs must have the same indentation -- that is, line |
|
up at their left edge. Paragraphs that start indented will result in |
|
indented quote paragraphs. For example:: |
|
|
|
This is a paragraph. It's quite |
|
short. |
|
|
|
This paragraph will result in an indented block of |
|
text, typically used for quoting other text. |
|
|
|
This is another one. |
|
|
|
Results in: |
|
|
|
This is a paragraph. It's quite |
|
short. |
|
|
|
This paragraph will result in an indented block of |
|
text, typically used for quoting other text. |
|
|
|
This is another one. |
|
|
|
__ quickref.html#paragraphs |
|
|
|
|
|
Text styles |
|
----------- |
|
|
|
(quickref__) |
|
|
|
__ quickref.html#inline-markup |
|
|
|
Inside paragraphs and other bodies of text, you may additionally mark |
|
text for *italics* with "``*italics*``" or **bold** with |
|
"``**bold**``". This is called "inline markup". |
|
|
|
If you want something to appear as a fixed-space literal, use |
|
"````double back-quotes````". Note that no further fiddling is done |
|
inside the double back-quotes -- so asterisks "``*``" etc. are left |
|
alone. |
|
|
|
If you find that you want to use one of the "special" characters in |
|
text, it will generally be OK -- reStructuredText is pretty smart. |
|
For example, this lone asterisk * is handled just fine, as is the |
|
asterisk in this equation: 5*6=30. If you actually |
|
want text \*surrounded by asterisks* to **not** be italicised, then |
|
you need to indicate that the asterisk is not special. You do this by |
|
placing a backslash just before it, like so "``\*``" (quickref__), or |
|
by enclosing it in double back-quotes (inline literals), like this:: |
|
|
|
``*`` |
|
|
|
__ quickref.html#escaping |
|
|
|
.. Tip:: Think of inline markup as a form of (parentheses) and use it |
|
the same way: immediately before and after the text being marked |
|
up. Inline markup by itself (surrounded by whitespace) or in the |
|
middle of a word won't be recognized. See the `markup spec`__ for |
|
full details. |
|
|
|
__ ../../ref/rst/restructuredtext.html#inline-markup |
|
|
|
|
|
Lists |
|
----- |
|
|
|
Lists of items come in three main flavours: **enumerated**, |
|
**bulleted** and **definitions**. In all list cases, you may have as |
|
many paragraphs, sublists, etc. as you want, as long as the left-hand |
|
side of the paragraph or whatever aligns with the first line of text |
|
in the list item. |
|
|
|
Lists must always start a new paragraph -- that is, they must appear |
|
after a blank line. |
|
|
|
**enumerated** lists (numbers, letters or roman numerals; quickref__) |
|
__ quickref.html#enumerated-lists |
|
|
|
Start a line off with a number or letter followed by a period ".", |
|
right bracket ")" or surrounded by brackets "( )" -- whatever you're |
|
comfortable with. All of the following forms are recognised:: |
|
|
|
1. numbers |
|
|
|
A. upper-case letters |
|
and it goes over many lines |
|
|
|
with two paragraphs and all! |
|
|
|
a. lower-case letters |
|
|
|
3. with a sub-list starting at a different number |
|
4. make sure the numbers are in the correct sequence though! |
|
|
|
I. upper-case roman numerals |
|
|
|
i. lower-case roman numerals |
|
|
|
(1) numbers again |
|
|
|
1) and again |
|
|
|
Results in (note: the different enumerated list styles are not |
|
always supported by every web browser, so you may not get the full |
|
effect here): |
|
|
|
1. numbers |
|
|
|
A. upper-case letters |
|
and it goes over many lines |
|
|
|
with two paragraphs and all! |
|
|
|
a. lower-case letters |
|
|
|
3. with a sub-list starting at a different number |
|
4. make sure the numbers are in the correct sequence though! |
|
|
|
I. upper-case roman numerals |
|
|
|
i. lower-case roman numerals |
|
|
|
(1) numbers again |
|
|
|
1) and again |
|
|
|
**bulleted** lists (quickref__) |
|
__ quickref.html#bullet-lists |
|
|
|
Just like enumerated lists, start the line off with a bullet point |
|
character - either "-", "+" or "*":: |
|
|
|
* a bullet point using "*" |
|
|
|
- a sub-list using "-" |
|
|
|
+ yet another sub-list |
|
|
|
- another item |
|
|
|
Results in: |
|
|
|
* a bullet point using "*" |
|
|
|
- a sub-list using "-" |
|
|
|
+ yet another sub-list |
|
|
|
- another item |
|
|
|
**definition** lists (quickref__) |
|
__ quickref.html#definition-lists |
|
|
|
Unlike the other two, the definition lists consist of a term, and |
|
the definition of that term. The format of a definition list is:: |
|
|
|
what |
|
Definition lists associate a term with a definition. |
|
|
|
*how* |
|
The term is a one-line phrase, and the definition is one or more |
|
paragraphs or body elements, indented relative to the term. |
|
Blank lines are not allowed between term and definition. |
|
|
|
Results in: |
|
|
|
what |
|
Definition lists associate a term with a definition. |
|
|
|
*how* |
|
The term is a one-line phrase, and the definition is one or more |
|
paragraphs or body elements, indented relative to the term. |
|
Blank lines are not allowed between term and definition. |
|
|
|
|
|
Preformatting (code samples) |
|
---------------------------- |
|
(quickref__) |
|
|
|
__ quickref.html#literal-blocks |
|
|
|
To just include a chunk of preformatted, never-to-be-fiddled-with |
|
text, finish the prior paragraph with "``::``". The preformatted |
|
block is finished when the text falls back to the same indentation |
|
level as a paragraph prior to the preformatted block. For example:: |
|
|
|
An example:: |
|
|
|
Whitespace, newlines, blank lines, and all kinds of markup |
|
(like *this* or \this) is preserved by literal blocks. |
|
Lookie here, I've dropped an indentation level |
|
(but not far enough) |
|
|
|
no more example |
|
|
|
Results in: |
|
|
|
An example:: |
|
|
|
Whitespace, newlines, blank lines, and all kinds of markup |
|
(like *this* or \this) is preserved by literal blocks. |
|
Lookie here, I've dropped an indentation level |
|
(but not far enough) |
|
|
|
no more example |
|
|
|
Note that if a paragraph consists only of "``::``", then it's removed |
|
from the output:: |
|
|
|
:: |
|
|
|
This is preformatted text, and the |
|
last "::" paragraph is removed |
|
|
|
Results in: |
|
|
|
:: |
|
|
|
This is preformatted text, and the |
|
last "::" paragraph is removed |
|
|
|
|
|
Sections |
|
-------- |
|
|
|
(quickref__) |
|
|
|
__ quickref.html#section-structure |
|
|
|
To break longer text up into sections, you use **section headers**. |
|
These are a single line of text (one or more words) with adornment: an |
|
underline alone, or an underline and an overline together, in dashes |
|
"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the |
|
non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you |
|
feel comfortable with. An underline-only adornment is distinct from |
|
an overline-and-underline adornment using the same character. The |
|
underline/overline must be at least as long as the title text. Be |
|
consistent, since all sections marked with the same adornment style |
|
are deemed to be at the same level:: |
|
|
|
Chapter 1 Title |
|
=============== |
|
|
|
Section 1.1 Title |
|
----------------- |
|
|
|
Subsection 1.1.1 Title |
|
~~~~~~~~~~~~~~~~~~~~~~ |
|
|
|
Section 1.2 Title |
|
----------------- |
|
|
|
Chapter 2 Title |
|
=============== |
|
|
|
This results in the following structure, illustrated by simplified |
|
pseudo-XML:: |
|
|
|
<section> |
|
<title> |
|
Chapter 1 Title |
|
<section> |
|
<title> |
|
Section 1.1 Title |
|
<section> |
|
<title> |
|
Subsection 1.1.1 Title |
|
<section> |
|
<title> |
|
Section 1.2 Title |
|
<section> |
|
<title> |
|
Chapter 2 Title |
|
|
|
(Pseudo-XML uses indentation for nesting and has no end-tags. It's |
|
not possible to show actual processed output, as in the other |
|
examples, because sections cannot exist inside block quotes. For a |
|
concrete example, compare the section structure of this document's |
|
source text and processed output.) |
|
|
|
Note that section headers are available as link targets, just using |
|
their name. To link to the Lists_ heading, I write "``Lists_``". If |
|
the heading has a space in it like `text styles`_, we need to quote |
|
the heading "```text styles`_``". |
|
|
|
|
|
Document Title / Subtitle |
|
````````````````````````` |
|
|
|
The title of the whole document is distinct from section titles and |
|
may be formatted somewhat differently (e.g. the HTML writer by default |
|
shows it as a centered heading). |
|
|
|
To indicate the document title in reStructuredText, use a unique adornment |
|
style at the beginning of the document. To indicate the document subtitle, |
|
use another unique adornment style immediately after the document title. For |
|
example:: |
|
|
|
================ |
|
Document Title |
|
================ |
|
---------- |
|
Subtitle |
|
---------- |
|
|
|
Section Title |
|
============= |
|
|
|
... |
|
|
|
Note that "Document Title" and "Section Title" above both use equals |
|
signs, but are distict and unrelated styles. The text of |
|
overline-and-underlined titles (but not underlined-only) may be inset |
|
for aesthetics. |
|
|
|
|
|
Images |
|
------ |
|
|
|
(quickref__) |
|
|
|
__ quickref.html#directives |
|
|
|
To include an image in your document, you use the the ``image`` directive__. |
|
For example:: |
|
|
|
.. image:: images/biohazard.png |
|
|
|
results in: |
|
|
|
.. image:: images/biohazard.png |
|
|
|
The ``images/biohazard.png`` part indicates the filename of the image |
|
you wish to appear in the document. There's no restriction placed on |
|
the image (format, size etc). If the image is to appear in HTML and |
|
you wish to supply additional information, you may:: |
|
|
|
.. image:: images/biohazard.png |
|
:height: 100 |
|
:width: 200 |
|
:scale: 50 |
|
:alt: alternate text |
|
|
|
See the full `image directive documentation`__ for more info. |
|
|
|
__ ../../ref/rst/directives.html |
|
__ ../../ref/rst/directives.html#images |
|
|
|
|
|
What Next? |
|
---------- |
|
|
|
This primer introduces the most common features of reStructuredText, |
|
but there are a lot more to explore. The `Quick reStructuredText`_ |
|
user reference is a good place to go next. For complete details, the |
|
`reStructuredText Markup Specification`_ is the place to go [#]_. |
|
|
|
Users who have questions or need assistance with Docutils or |
|
reStructuredText should post a message to the Docutils-users_ mailing |
|
list. |
|
|
|
.. [#] If that relative link doesn't work, try the master document: |
|
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. |
|
|
|
.. _reStructuredText Markup Specification: |
|
../../ref/rst/restructuredtext.html |
|
.. _Docutils-users: ../mailing-lists.html#docutils-users |
|
.. _Docutils project web site: http://docutils.sourceforge.net/
|
|
|