A new Riff-radio.org site with a static approach.

quickstart.html 16KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356
  1. <dl class="docinfo simple">
  2. <dt class="author">Author<span class="colon">:</span></dt>
  3. <dd class="author"><p>Richard Jones</p></dd>
  4. <dt class="version">Version<span class="colon">:</span></dt>
  5. <dd class="version">5801</dd>
  6. <dt class="copyright">Copyright<span class="colon">:</span></dt>
  7. <dd class="copyright">This document has been placed in the public domain.</dd>
  8. </dl>
  9. <nav class="contents alert alert-info pull-left" id="contents" role="doc-toc">
  10. <p class="topic-title">Contents</p>
  11. <ul class="simple">
  12. <li><p><a class="reference internal" href="#structure" id="toc-entry-1">Structure</a></p></li>
  13. <li><p><a class="reference internal" href="#text-styles" id="toc-entry-2">Text styles</a></p></li>
  14. <li><p><a class="reference internal" href="#lists" id="toc-entry-3">Lists</a></p></li>
  15. <li><p><a class="reference internal" href="#preformatting-code-samples" id="toc-entry-4">Preformatting (code samples)</a></p></li>
  16. <li><p><a class="reference internal" href="#sections" id="toc-entry-5">Sections</a></p>
  17. <ul>
  18. <li><p><a class="reference internal" href="#document-title-subtitle" id="toc-entry-6">Document Title / Subtitle</a></p></li>
  19. </ul>
  20. </li>
  21. <li><p><a class="reference internal" href="#images" id="toc-entry-7">Images</a></p></li>
  22. <li><p><a class="reference internal" href="#what-next" id="toc-entry-8">What Next?</a></p></li>
  23. </ul>
  24. </nav>
  25. <p>The text below contains links that look like &quot;(<a class="reference external" href="../quickref/">quickref</a>)&quot;. These
  26. are relative links that point to the <a class="reference external" href="../quickref/">Quick reStructuredText</a> user
  27. reference. If these links don't work, please refer to the <a class="reference external" href="https://docutils.sourceforge.io/docs/user/rst/quickref.html">master
  28. quick reference</a> document.</p>
  29. <aside class="admonition note">
  30. <p class="admonition-title">Note</p>
  31. <p>This document is an informal introduction to
  32. reStructuredText. The <a class="reference internal" href="#what-next">What Next?</a> section below has links to
  33. further resources, including a formal reference.</p>
  34. </aside>
  35. <section id="structure">
  36. <h1><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">Structure</a></h1>
  37. <p>From the outset, let me say that &quot;Structured Text&quot; is probably a bit
  38. of a misnomer. It's more like &quot;Relaxed Text&quot; that uses certain
  39. consistent patterns. These patterns are interpreted by a HTML
  40. converter to produce &quot;Very Structured Text&quot; that can be used by a web
  41. browser.</p>
  42. <p>The most basic pattern recognised is a <strong>paragraph</strong> (<a class="reference external" href="../quickref/#paragraphs">quickref</a>).
  43. That's a chunk of text that is separated by blank lines (one is
  44. enough). Paragraphs must have the same indentation -- that is, line
  45. up at their left edge. Paragraphs that start indented will result in
  46. indented quote paragraphs. For example:</p>
  47. <pre class="literal-block">This is a paragraph. It's quite
  48. short.
  49. This paragraph will result in an indented block of
  50. text, typically used for quoting other text.
  51. This is another one.</pre>
  52. <p>Results in:</p>
  53. <blockquote>
  54. <p>This is a paragraph. It's quite
  55. short.</p>
  56. <blockquote>
  57. <p>This paragraph will result in an indented block of
  58. text, typically used for quoting other text.</p>
  59. </blockquote>
  60. <p>This is another one.</p>
  61. </blockquote>
  62. </section>
  63. <section id="text-styles">
  64. <h1><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">Text styles</a></h1>
  65. <p>(<a class="reference external" href="../quickref/#inline-markup">quickref</a>)</p>
  66. <p>Inside paragraphs and other bodies of text, you may additionally mark
  67. text for <em>italics</em> with &quot;<code class="docutils literal">*italics*</code>&quot; or <strong>bold</strong> with
  68. &quot;<code class="docutils literal">**bold**</code>&quot;. This is called &quot;inline markup&quot;.</p>
  69. <p>If you want something to appear as a fixed-space literal, use
  70. &quot;<code class="docutils literal">``double <span class="pre">back-quotes``</span></code>&quot;. Note that no further fiddling is done
  71. inside the double back-quotes -- so asterisks &quot;<code class="docutils literal">*</code>&quot; etc. are left
  72. alone.</p>
  73. <p>If you find that you want to use one of the &quot;special&quot; characters in
  74. text, it will generally be OK -- reStructuredText is pretty smart.
  75. For example, this lone asterisk * is handled just fine, as is the
  76. asterisk in this equation: 5*6=30. If you actually
  77. want text *surrounded by asterisks* to <strong>not</strong> be italicised, then
  78. you need to indicate that the asterisk is not special. You do this by
  79. placing a backslash just before it, like so &quot;<code class="docutils literal">\*</code>&quot; (<a class="reference external" href="../quickref/#escaping">quickref</a>), or
  80. by enclosing it in double back-quotes (inline literals), like this:</p>
  81. <pre class="literal-block">``*``</pre>
  82. <aside class="admonition tip">
  83. <p class="admonition-title">Tip</p>
  84. <p>Think of inline markup as a form of (parentheses) and use it
  85. the same way: immediately before and after the text being marked
  86. up. Inline markup by itself (surrounded by whitespace) or in the
  87. middle of a word won't be recognized. See the <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup">markup spec</a> for
  88. full details.</p>
  89. </aside>
  90. </section>
  91. <section id="lists">
  92. <h1><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">Lists</a></h1>
  93. <p>Lists of items come in three main flavours: <strong>enumerated</strong>,
  94. <strong>bulleted</strong> and <strong>definitions</strong>. In all list cases, you may have as
  95. many paragraphs, sublists, etc. as you want, as long as the left-hand
  96. side of the paragraph or whatever aligns with the first line of text
  97. in the list item.</p>
  98. <p>Lists must always start a new paragraph -- that is, they must appear
  99. after a blank line.</p>
  100. <dl>
  101. <dt><strong>enumerated</strong> lists (numbers, letters or roman numerals; <a class="reference external" href="../quickref/#enumerated-lists">quickref</a>)</dt>
  102. <dd><p>Start a line off with a number or letter followed by a period &quot;.&quot;,
  103. right bracket &quot;)&quot; or surrounded by brackets &quot;( )&quot; -- whatever you're
  104. comfortable with. All of the following forms are recognised:</p>
  105. <pre class="literal-block">1. numbers
  106. A. upper-case letters
  107. and it goes over many lines
  108. with two paragraphs and all!
  109. a. lower-case letters
  110. 3. with a sub-list starting at a different number
  111. 4. make sure the numbers are in the correct sequence though!
  112. I. upper-case roman numerals
  113. i. lower-case roman numerals
  114. (1) numbers again
  115. 1) and again</pre>
  116. <p>Results in (note: the different enumerated list styles are not
  117. always supported by every web browser, so you may not get the full
  118. effect here):</p>
  119. <ol class="arabic simple">
  120. <li><p>numbers</p></li>
  121. </ol>
  122. <ol class="upperalpha">
  123. <li><p>upper-case letters
  124. and it goes over many lines</p>
  125. <p>with two paragraphs and all!</p>
  126. </li>
  127. </ol>
  128. <ol class="loweralpha simple">
  129. <li><p>lower-case letters</p>
  130. <ol class="arabic simple" start="3">
  131. <li><p>with a sub-list starting at a different number</p></li>
  132. <li><p>make sure the numbers are in the correct sequence though!</p></li>
  133. </ol>
  134. </li>
  135. </ol>
  136. <ol class="upperroman simple">
  137. <li><p>upper-case roman numerals</p></li>
  138. </ol>
  139. <ol class="lowerroman simple">
  140. <li><p>lower-case roman numerals</p></li>
  141. </ol>
  142. <ol class="arabic simple">
  143. <li><p>numbers again</p></li>
  144. </ol>
  145. <ol class="arabic simple">
  146. <li><p>and again</p></li>
  147. </ol>
  148. </dd>
  149. <dt><strong>bulleted</strong> lists (<a class="reference external" href="../quickref/#bullet-lists">quickref</a>)</dt>
  150. <dd><p>Just like enumerated lists, start the line off with a bullet point
  151. character - either &quot;-&quot;, &quot;+&quot; or &quot;*&quot;:</p>
  152. <pre class="literal-block">* a bullet point using &quot;*&quot;
  153. - a sub-list using &quot;-&quot;
  154. + yet another sub-list
  155. - another item</pre>
  156. <p>Results in:</p>
  157. <ul class="simple">
  158. <li><p>a bullet point using &quot;*&quot;</p>
  159. <ul>
  160. <li><p>a sub-list using &quot;-&quot;</p>
  161. <ul>
  162. <li><p>yet another sub-list</p></li>
  163. </ul>
  164. </li>
  165. <li><p>another item</p></li>
  166. </ul>
  167. </li>
  168. </ul>
  169. </dd>
  170. <dt><strong>definition</strong> lists (<a class="reference external" href="../quickref/#definition-lists">quickref</a>)</dt>
  171. <dd><p>Unlike the other two, the definition lists consist of a term, and
  172. the definition of that term. The format of a definition list is:</p>
  173. <pre class="literal-block">what
  174. Definition lists associate a term with a definition.
  175. *how*
  176. The term is a one-line phrase, and the definition is one or more
  177. paragraphs or body elements, indented relative to the term.
  178. Blank lines are not allowed between term and definition.</pre>
  179. <p>Results in:</p>
  180. <dl class="simple">
  181. <dt>what</dt>
  182. <dd><p>Definition lists associate a term with a definition.</p>
  183. </dd>
  184. <dt><em>how</em></dt>
  185. <dd><p>The term is a one-line phrase, and the definition is one or more
  186. paragraphs or body elements, indented relative to the term.
  187. Blank lines are not allowed between term and definition.</p>
  188. </dd>
  189. </dl>
  190. </dd>
  191. </dl>
  192. </section>
  193. <section id="preformatting-code-samples">
  194. <h1><a class="toc-backref" href="#toc-entry-4" role="doc-backlink">Preformatting (code samples)</a></h1>
  195. <p>(<a class="reference external" href="../quickref/#literal-blocks">quickref</a>)</p>
  196. <p>To just include a chunk of preformatted, never-to-be-fiddled-with
  197. text, finish the prior paragraph with &quot;<code class="docutils literal">::</code>&quot;. The preformatted
  198. block is finished when the text falls back to the same indentation
  199. level as a paragraph prior to the preformatted block. For example:</p>
  200. <pre class="literal-block">An example::
  201. Whitespace, newlines, blank lines, and all kinds of markup
  202. (like *this* or \this) is preserved by literal blocks.
  203. Lookie here, I've dropped an indentation level
  204. (but not far enough)
  205. no more example</pre>
  206. <p>Results in:</p>
  207. <blockquote>
  208. <p>An example:</p>
  209. <pre class="literal-block"> Whitespace, newlines, blank lines, and all kinds of markup
  210. (like *this* or \this) is preserved by literal blocks.
  211. Lookie here, I've dropped an indentation level
  212. (but not far enough)</pre>
  213. <p>no more example</p>
  214. </blockquote>
  215. <p>Note that if a paragraph consists only of &quot;<code class="docutils literal">::</code>&quot;, then it's removed
  216. from the output:</p>
  217. <pre class="literal-block">::
  218. This is preformatted text, and the
  219. last &quot;::&quot; paragraph is removed</pre>
  220. <p>Results in:</p>
  221. <pre class="literal-block">This is preformatted text, and the
  222. last &quot;::&quot; paragraph is removed</pre>
  223. </section>
  224. <section id="sections">
  225. <h1><a class="toc-backref" href="#toc-entry-5" role="doc-backlink">Sections</a></h1>
  226. <p>(<a class="reference external" href="../quickref/#section-structure">quickref</a>)</p>
  227. <p>To break longer text up into sections, you use <strong>section headers</strong>.
  228. These are a single line of text (one or more words) with adornment: an
  229. underline alone, or an underline and an overline together, in dashes
  230. &quot;<code class="docutils literal"><span class="pre">-----</span></code>&quot;, equals &quot;<code class="docutils literal"><span class="pre">======</span></code>&quot;, tildes &quot;<code class="docutils literal"><span class="pre">~~~~~~</span></code>&quot; or any of the
  231. non-alphanumeric characters <code class="docutils literal">= - ` : ' &quot; ~ ^ _ * + # &lt; &gt;</code> that you
  232. feel comfortable with. An underline-only adornment is distinct from
  233. an overline-and-underline adornment using the same character. The
  234. underline/overline must be at least as long as the title text. Be
  235. consistent, since all sections marked with the same adornment style
  236. are deemed to be at the same level:</p>
  237. <pre class="literal-block">Chapter 1 Title
  238. ===============
  239. Section 1.1 Title
  240. -----------------
  241. Subsection 1.1.1 Title
  242. ~~~~~~~~~~~~~~~~~~~~~~
  243. Section 1.2 Title
  244. -----------------
  245. Chapter 2 Title
  246. ===============</pre>
  247. <p>This results in the following structure, illustrated by simplified
  248. pseudo-XML:</p>
  249. <pre class="literal-block">&lt;section&gt;
  250. &lt;title&gt;
  251. Chapter 1 Title
  252. &lt;section&gt;
  253. &lt;title&gt;
  254. Section 1.1 Title
  255. &lt;section&gt;
  256. &lt;title&gt;
  257. Subsection 1.1.1 Title
  258. &lt;section&gt;
  259. &lt;title&gt;
  260. Section 1.2 Title
  261. &lt;section&gt;
  262. &lt;title&gt;
  263. Chapter 2 Title</pre>
  264. <p>(Pseudo-XML uses indentation for nesting and has no end-tags. It's
  265. not possible to show actual processed output, as in the other
  266. examples, because sections cannot exist inside block quotes. For a
  267. concrete example, compare the section structure of this document's
  268. source text and processed output.)</p>
  269. <p>Note that section headers are available as link targets, just using
  270. their name. To link to the <a class="reference internal" href="#lists">Lists</a> heading, I write &quot;<code class="docutils literal">Lists_</code>&quot;. If
  271. the heading has a space in it like <a class="reference internal" href="#text-styles">text styles</a>, we need to quote
  272. the heading &quot;<code class="docutils literal">`text styles`_</code>&quot;.</p>
  273. <section id="document-title-subtitle">
  274. <h2><a class="toc-backref" href="#toc-entry-6" role="doc-backlink">Document Title / Subtitle</a></h2>
  275. <p>The title of the whole document is distinct from section titles and
  276. may be formatted somewhat differently (e.g. the HTML writer by default
  277. shows it as a centered heading).</p>
  278. <p>To indicate the document title in reStructuredText, use a unique adornment
  279. style at the beginning of the document. To indicate the document subtitle,
  280. use another unique adornment style immediately after the document title. For
  281. example:</p>
  282. <pre class="literal-block">================
  283. Document Title
  284. ================
  285. ----------
  286. Subtitle
  287. ----------
  288. Section Title
  289. =============
  290. ...</pre>
  291. <p>Note that &quot;Document Title&quot; and &quot;Section Title&quot; above both use equals
  292. signs, but are distinct and unrelated styles. The text of
  293. overline-and-underlined titles (but not underlined-only) may be inset
  294. for aesthetics.</p>
  295. </section>
  296. </section>
  297. <section id="images">
  298. <h1><a class="toc-backref" href="#toc-entry-7" role="doc-backlink">Images</a></h1>
  299. <p>(<a class="reference external" href="../quickref/#directives">quickref</a>)</p>
  300. <p>To include an image in your document, you use the <code class="docutils literal">image</code> <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html">directive</a>.
  301. For example:</p>
  302. <pre class="literal-block">.. image:: /images/nikola.png</pre>
  303. <p>results in:</p>
  304. <img alt="/images/nikola.png" src="/images/nikola.png" />
  305. <p>The <code class="docutils literal">/images/nikola.png</code> part indicates the filename of the image
  306. you wish to appear in the document. There's no restriction placed on
  307. the image (format, size etc). If the image is to appear in HTML and
  308. you wish to supply additional information, you may:</p>
  309. <pre class="literal-block">.. image:: /images/nikola.png
  310. :height: 100
  311. :width: 200
  312. :scale: 50
  313. :alt: alternate text</pre>
  314. <p>See the full <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#images">image directive documentation</a> for more info.</p>
  315. </section>
  316. <section id="what-next">
  317. <h1><a class="toc-backref" href="#toc-entry-8" role="doc-backlink">What Next?</a></h1>
  318. <p>This primer introduces the most common features of reStructuredText,
  319. but there are a lot more to explore. The <a class="reference external" href="../quickref/">Quick reStructuredText</a>
  320. user reference is a good place to go next. For complete details, the
  321. <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html">reStructuredText Markup Specification</a> is the place to go <a class="footnote-reference brackets" href="#footnote-1" id="footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>.</p>
  322. <p>Users who have questions or need assistance with Docutils or
  323. reStructuredText should post a message to the <a class="reference external" href="https://docutils.sourceforge.io/docs/user/mailing-lists.html#docutils-users">Docutils-users</a> mailing
  324. list.</p>
  325. <aside class="footnote-list brackets">
  326. <aside class="footnote brackets" id="footnote-1" role="note">
  327. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-1">1</a><span class="fn-bracket">]</span></span>
  328. <p>If that relative link doesn't work, try the master document:
  329. <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html">https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html</a>.</p>
  330. </aside>
  331. </aside>
  332. </section>