| Author: | Nathaniel Beaver |
|---|---|
| Date: | 2014-08-01 (Friday, 1 August 2014) |
| Copyright: | This document has been placed in the public domain. |
If you are reading an output format like HTML, the source file is ../readme.rst. If you are reading on Github, the source file is ./readme.rst.
This is meant to be read from the source file. It is more of a template than a tutorial, and reading the output is not as helpful.
See also the official reStructuredText demo:
http://docutils.sourceforge.net/docs/user/rst/demo.txt
http://docutils.sourceforge.net/docs/user/rst/demo.html
Unofficial guides:
http://www.trueelena.org/computers/articles/restructuredtext_for_fiction.html
Run the Makefile to generate all the various output formats,
or make open-all to open them with the default applications.
Contents
The reStructuredText specification is on Sourceforge, as is the docutils Quick Reference.
The Wikipedia page on reST is also helpful, as is the Sphinx documentation generator page.
Inline hyperlinks are also possible, although they tend to clutter up the source markup.
Anonymous hyperlinks are also possible if you are just too lazy to name your hyperlinks, or if you want two hyperlinks with the same text (e.g. Georgia or Georgia, can or can).
They are assigned by the order of the links in the document, unlike named hyperlink targets where order is irrelevant.
Some characters must be escaped in links,
including some characters in URLs.
Backslashes (\) must be escaped in both the link text and the target,
a leading underscore (_) must be escaped in the target,
and colons (:) must be escaped anywhere in the target.
For example, to link to the title "LaTeX: a document preparation system", the colon does not need to be escaped in the link text, but it does in the target.
To link to _why, the leading underscore does not need to be escaped in the link text, but it does in the target.
To link to C:\Program Files\, the backslash must be escaped in both the link text and the target.
The backtick (`) must be escaped in the link text, but does not need to be escaped in the target.
Relative and absolute links both work.
For example, we can make a relative link to the source file in the parent directory, or link to the same file inline.
Absolute links are done similarly.
Linking to the section on how to do math.
Inline link to the title.
Linking to the section on unordered/bulleted lists.
Linking to an arbitrary cross-reference target.
blah blah blah blah
blah blah blah blah
From the documentation:
- Underline is different than underline and overline.
- Do not indent the title for underline-only section titles.
- Valid section adornment characters:
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - Reccomended section adornment characters:
= - ` : . ' " ~ ^ _ * + #
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections
Example of turning an rst markup document into HTML:
rst2html reStructuredText.rst reStructuredText.html
The quadratic equation, a x^2 + b x + c = 0, has two solutions, x = \frac{-b \pm \sqrt{b^2 - 4 a c} }{2 a}.
The Einstein field equations.
G_{\mu\nu} \equiv R_{\mu\nu} - \frac{1}{2} R g_{\mu\nu} = \frac{8 \pi G}{c^4} T_{\mu\nu}
You can also use MathJax by defining a raw-latex directive.
Inline math is done like this: \( \vec{F} = e \vec{v} \times \vec{B} \)
Displayed math is done like this:
\[ e \vec{v} \times \vec{B} = m \frac{d \vec{v}}{dt} \]Cheese is delicious. [1]
Labeled footnotes? Why bother? [2]
Symbolic footnotes: there are ten symbols to run through before it starts doubling them up. [*] [†] [‡] [§] [¶] [#] [♠] [♥] [♦] [♣] [**]
Citations with the label instead of a number are easy. [jdoe2014]
Note that the location of a footnote's target does affect the placement of the footnotes in the document.
| [1] | Especially limburger cheese. |
| [2] | You can always add a label later. |
| [*] | Asterisk *. |
| [†] | Dagger †. |
| [‡] | Double dagger ‡. |
| [§] | Section sign §. |
| [¶] | Pilcrow/paragraph sign ¶. |
| [#] | Number sign #. |
| [♠] | Black spade suit ♠. |
| [♥] | Black heart suit ♥. |
| [♦] | Black diamond suit ♠. |
| [♣] | Black club suit ♣. |
| [**] | Double asterisk **. |
| [jdoe2014] | Doe, John. Bulletin of Stuff. 2104. |
A multiplication table.
| 1 | 2 | 3 | 4 | |
| 1 | 1 | 2 | 3 | 4 |
| 2 | 2 | 4 | 6 | 8 |
| 3 | 3 | 6 | 9 | 12 |
| 4 | 4 | 8 | 12 | 16 |
A less laborious multiplication table; the first cell cannot be empty or have multiple lines.
| x | 1 | 2 | 3 | 4 |
| 1 | 1 | 2 | 3 | 4 |
| 2 | 2 | 4 | 3 | 8 |
| 3 | 3 | 6 | 9 | 12 |
| 4 | 4 | 8 | 12 | 16 |
Tables with a header row.
| X | Y |
|---|---|
| 1 | 1 |
| 2 | 4 |
| 3 | 9 |
| 4 16 | |
| X | Y |
|---|---|
| 1 | 1 |
| 2 | 4 |
| 3 | 9 |
| 4 | 16 |
Lists in tables.
|
|
- One example
- using hyphens.
- Another using
- asterisks.
- Another using
- plus signs.
- Nesting levels: 1st.
- 2nd level.
- 2nd level again.
- 3rd level.
- 3rd level again.
- 4th level.
- 4th level again.
- 5th level.
Any language benefits from the ability to comment things out.
If we use rst2html, we get this output:
<!-- This won't appear, since we used two dots. -->
If we use rst2latex, we get this output:
% This won't appear, % since we used two dots.
This is a block quote. It is indented, and does not preserve line-breaks.
If you want to start a new paragraph, you must leave a blank line.
This is an indented line block.It preserves line-breaks, and is useful for poems and other verse.
This is a literal block. It is indented, uses monspace font, and preserves line-breaks. Don't forget to leave a blank space before the leading ::.