| author |
Steve Losh <steve@stevelosh.com> |
| date |
Wed, 10 Oct 2012 16:25:34 -0400 |
| parents |
17a202419058 |
| children |
4c036b4fcae9 |
restdammit.txt A ReStructuredText Primer
==============================================================================
CONTENTS *restdammit-contents*
1. Intro .......................... |rest-intro|
==============================================================================
0. Quick Reference *rest-ref*
Taken from http://docutils.sourceforge.net/docs/user/rst/quickref.html
Inline Markup: >
*emphasis* Normally rendered as italics.
**strong emphasis** Normally rendered as boldface.
`interpreted text` The rendering and meaning of interpreted text
is domain- or application-dependent. It can
be used for things like index entries or
explicit descriptive markup (like program
identifiers).
``inline literal`` Normally rendered as monospaced text. Spaces
should be preserved, but line breaks will
not be.
reference_ A simple, one-word hyperlink reference.
`phrase reference`_ A hyperlink reference with spaces or
punctuation needs to be quoted with
backquotes.
anonymous__ With two underscores instead of one, both
simple and phrase references may be
anonymous (the reference text is not
repeated at the target).
_`inline internal target` A crossreference target within text.
|substitution reference| The result is substituted in from the
substitution definition. It could be text,
an image, a hyperlink, or a combination of
these and others.
footnote reference [1]_ Footnote reference.
citation reference [CIT2002]_ Citation Reference
http://docutils.sf.net/ A standalone hyperlink.
External links: >
External hyperlinks, like Python_.
.. _Python: http://www.python.org/
==============================================================================
1. Intro *rest-intro*
This document was taken from
http://docutils.sourceforge.net/docs/user/rst/quickstart.txt
and manually converted to Vim's help format.
==============================================================================
2. Structure *rest-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**. 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.
==============================================================================
3. Text styles *rest-styles*
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 "\*", or by enclosing
it in double back-quotes (inline literals), like this: >
``*``
==============================================================================
4. Lists *rest-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.
------------------------------------------------------------------------------
4.1 Enumerated Lists *rest-lists-enum*
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
------------------------------------------------------------------------------
4.2 Bulleted Lists *rest-lists-bull*
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
------------------------------------------------------------------------------
4.3 Definition Lists *rest-lists-def*
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.
==============================================================================
5. Preformatting *rest-code*
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
==============================================================================
6. Sections *rest-sections*
To break longer text up into sections, you use section headers. These are
a single line of text (one or more words) with adornment:
1. an underline alone
2. an underline and an overline together
in:
1. dashes "------"
2. equals "======"
3. tildes "~~~~~~"
4. any of the non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < >
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`_".
------------------------------------------------------------------------------
6.1 Document Title / Subtitle *rest-title*
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.
==============================================================================
7.0 Images *rest-images* *rest-image* *rest-img*
To include an image in your document, you use the the image directive.
For example: >
.. image:: images/biohazard.png
results in: >
<img src="images/biohazarg.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.