WebSVN – corrade-nucleus-nucleons – Blame – Rev 20 – /script-kiddie/002_script_kiddie/script-kiddie/node_modules/ace-builds/demo/kitchen-sink/docs/rst.rst

20

office

1

==========================================

2

*reStructuredText* Highlighter for **Ace**

3

==========================================

.. seealso::

http://docutils.sourceforge.net/docs/user/rst/quickstart.html

8

9

10

ReStructuredText Primer

11

=======================

12

13

:Author: Richard Jones

14

:Version: $Revision: 5801 $

15

:Copyright: This document has been placed in the public domain.

.. contents::

The text below contains links that look like "(quickref__)". These

21

are relative links that point to the `Quick reStructuredText`_ user

22

reference. If these links don't work, please refer to the `master

23

quick reference`_ document.

24

25

__

26

.. _Quick reStructuredText: quickref.html

27

.. _master quick reference:

28

http://docutils.sourceforge.net/docs/user/rst/quickref.html

29

30

.. Note:: This document is an informal introduction to

31

reStructuredText. The `What Next?`_ section below has links to

32

further resources, including a formal reference.

Structure

---------

From the outset, let me say that "Structured Text" is probably a bit

39

of a misnomer. It's more like "Relaxed Text" that uses certain

40

consistent patterns. These patterns are interpreted by a HTML

41

converter to produce "Very Structured Text" that can be used by a web

42

browser.

43

44

The most basic pattern recognised is a **paragraph** (quickref__).

45

That's a chunk of text that is separated by blank lines (one is

46

enough). Paragraphs must have the same indentation -- that is, line

47

up at their left edge. Paragraphs that start indented will result in

48

indented quote paragraphs. For example::

49

50

This is a paragraph. It's quite

51

short.

52

53

This paragraph will result in an indented block of

54

text, typically used for quoting other text.

55

56

This is another one.

Results in:

This is a paragraph. It's quite

61

short.

62

63

This paragraph will result in an indented block of

64

text, typically used for quoting other text.

65

66

This is another one.

67

68

__ quickref.html#paragraphs

Text styles

-----------

(quickref__)

__ quickref.html#inline-markup

77

78

Inside paragraphs and other bodies of text, you may additionally mark

79

text for *italics* with "``*italics*``" or **bold** with

80

"``**bold**``". This is called "inline markup".

81

82

If you want something to appear as a fixed-space literal, use

83

"````double back-quotes````". Note that no further fiddling is done

84

inside the double back-quotes -- so asterisks "``*``" etc. are left

85

alone.

86

87

If you find that you want to use one of the "special" characters in

88

text, it will generally be OK -- reStructuredText is pretty smart.

89

For example, this lone asterisk * is handled just fine, as is the

90

asterisk in this equation: 5*6=30. If you actually

91

want text \*surrounded by asterisks* to **not** be italicised, then

92

you need to indicate that the asterisk is not special. You do this by

93

placing a backslash just before it, like so "``\*``" (quickref__), or

94

by enclosing it in double back-quotes (inline literals), like this::

``*``

__ quickref.html#escaping

99

100

.. Tip:: Think of inline markup as a form of (parentheses) and use it

101

the same way: immediately before and after the text being marked

102

up. Inline markup by itself (surrounded by whitespace) or in the

103

middle of a word won't be recognized. See the `markup spec`__ for

104

full details.

105

106

__ ../../ref/rst/restructuredtext.html#inline-markup

Lists

-----

Lists of items come in three main flavours: **enumerated**,

113

**bulleted** and **definitions**. In all list cases, you may have as

114

many paragraphs, sublists, etc. as you want, as long as the left-hand

115

side of the paragraph or whatever aligns with the first line of text

116

in the list item.

117

118

Lists must always start a new paragraph -- that is, they must appear

119

after a blank line.

120

121

**enumerated** lists (numbers, letters or roman numerals; quickref__)

122

__ quickref.html#enumerated-lists

123

124

Start a line off with a number or letter followed by a period ".",

125

right bracket ")" or surrounded by brackets "( )" -- whatever you're

126

comfortable with. All of the following forms are recognised::

1. numbers

A. upper-case letters

131

and it goes over many lines

132

133

with two paragraphs and all!

134

135

a. lower-case letters

136

137

3. with a sub-list starting at a different number

138

4. make sure the numbers are in the correct sequence though!

139

140

I. upper-case roman numerals

141

142

i. lower-case roman numerals

(1) numbers again

1) and again

Results in (note: the different enumerated list styles are not

149

always supported by every web browser, so you may not get the full

effect here):

1. numbers

A. upper-case letters

155

and it goes over many lines

156

157

with two paragraphs and all!

158

159

a. lower-case letters

160

161

3. with a sub-list starting at a different number

162

4. make sure the numbers are in the correct sequence though!

163

164

I. upper-case roman numerals

165

166

i. lower-case roman numerals

(1) numbers again

1) and again

**bulleted** lists (quickref__)

173

__ quickref.html#bullet-lists

174

175

Just like enumerated lists, start the line off with a bullet point

176

character - either "-", "+" or "\*"::

177

178

* a bullet point using "\*"

179

180

- a sub-list using "-"

181

182

+ yet another sub-list

- another item

Results in:

* a bullet point using "\*"

189

190

- a sub-list using "-"

191

192

+ yet another sub-list

- another item

**definition** lists (quickref__)

197

__ quickref.html#definition-lists

198

199

Unlike the other two, the definition lists consist of a term, and

200

the definition of that term. The format of a definition list is::

201

202

what

203

Definition lists associate a term with a definition.

204

205

*how*

206

The term is a one-line phrase, and the definition is one or more

207

paragraphs or body elements, indented relative to the term.

208

Blank lines are not allowed between term and definition.

Results in:

what

Definition lists associate a term with a definition.

214

215

*how*

216

The term is a one-line phrase, and the definition is one or more

217

paragraphs or body elements, indented relative to the term.

218

Blank lines are not allowed between term and definition.

219

220

221

Preformatting (code samples)

222

----------------------------

223

(quickref__)

224

225

__ quickref.html#literal-blocks

226

227

To just include a chunk of preformatted, never-to-be-fiddled-with

228

text, finish the prior paragraph with "``::``". The preformatted

229

block is finished when the text falls back to the same indentation

230

level as a paragraph prior to the preformatted block. For example::

An example::

Whitespace, newlines, blank lines, and all kinds of markup

235

(like *this* or \this) is preserved by literal blocks.

236

Lookie here, I've dropped an indentation level

237

(but not far enough)

no more example

Results in:

An example::

Whitespace, newlines, blank lines, and all kinds of markup

246

(like *this* or \this) is preserved by literal blocks.

247

Lookie here, I've dropped an indentation level

248

(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

258

last "::" paragraph is removed

Results in:

::

This is preformatted text, and the

265

last "::" paragraph is removed

Sections

--------

(quickref__)

__ quickref.html#section-structure

274

275

To break longer text up into sections, you use **section headers**.

276

These are a single line of text (one or more words) with adornment: an

277

underline alone, or an underline and an overline together, in dashes

278

"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the

279

non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you

280

feel comfortable with. An underline-only adornment is distinct from

281

an overline-and-underline adornment using the same character. The

282

underline/overline must be at least as long as the title text. Be

283

consistent, since all sections marked with the same adornment style

284

are deemed to be at the same level::

Chapter 1 Title

===============

Section 1.1 Title

-----------------

Subsection 1.1.1 Title

293

~~~~~~~~~~~~~~~~~~~~~~

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

321

not possible to show actual processed output, as in the other

322

examples, because sections cannot exist inside block quotes. For a

323

concrete example, compare the section structure of this document's

324

source text and processed output.)

325

326

Note that section headers are available as link targets, just using

327

their name. To link to the Lists_ heading, I write "``Lists_``". If

328

the heading has a space in it like `text styles`_, we need to quote

329

the heading "```text styles`_``".

330

331

332

Document Title / Subtitle

333

`````````````````````````

334

335

The title of the whole document is distinct from section titles and

336

may be formatted somewhat differently (e.g. the HTML writer by default

337

shows it as a centered heading).

338

339

To indicate the document title in reStructuredText, use a unique adornment

340

style at the beginning of the document. To indicate the document subtitle,

341

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

357

signs, but are distict and unrelated styles. The text of

358

overline-and-underlined titles (but not underlined-only) may be inset

for aesthetics.

Images

------

(quickref__)

__ quickref.html#directives

368

369

To include an image in your document, you use the the ``image`` directive__.

370

For example::

371

372

.. image:: images/biohazard.png

results in:

.. image:: images/biohazard.png

377

378

The ``images/biohazard.png`` part indicates the filename of the image

379

you wish to appear in the document. There's no restriction placed on

380

the image (format, size etc). If the image is to appear in HTML and

381

you wish to supply additional information, you may::

382

383

.. image:: images/biohazard.png

:height: 100

:width: 200

:scale: 50

:alt: alternate text

388

389

See the full `image directive documentation`__ for more info.

390

391

__ ../../ref/rst/directives.html

392

__ ../../ref/rst/directives.html#images

What Next?

----------

This primer introduces the most common features of reStructuredText,

399

but there are a lot more to explore. The `Quick reStructuredText`_

400

user reference is a good place to go next. For complete details, the

401

`reStructuredText Markup Specification`_ is the place to go [#]_.

402

403

Users who have questions or need assistance with Docutils or

404

reStructuredText should post a message to the Docutils-users_ mailing

405

list.

406

407

.. [#] If that relative link doesn't work, try the master document:

408

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.

409

410

.. _reStructuredText Markup Specification:

411

../../ref/rst/restructuredtext.html

412

.. _Docutils-users: ../mailing-lists.html#docutils-users

413

.. _Docutils project web site: http://docutils.sourceforge.net/

corrade-nucleus-nucleons – Blame information for rev 20