/script-kiddie/002_script_kiddie/script-kiddie/node_modules/ace-builds/demo/kitchen-sink/docs/rst.rst |
@@ -0,0 +1,413 @@ |
========================================== |
*reStructuredText* Highlighter for **Ace** |
========================================== |
|
.. seealso:: |
|
http://docutils.sourceforge.net/docs/user/rst/quickstart.html |
|
|
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/ |