The reStructuredText_ Cheat Sheet: Syntax Reminders

Info:	See <http://docutils.sf.net/rst.html> for introductory docs.
Author:	David Goodger <goodger@python.org>
Date:	2012-06-22
Revision:	7463
Description:	This is a "docinfo block", or bibliographic field list

Section Structure

Section titles are underlined or overlined & underlined.

Body Elements

Grid table:

System Message: ERROR/3 (<string>, line 18)

Malformed table.

+--------------------------------+-----------------------------------+
| Paragraphs are flush-left,     | Literal block, preceded by "::":: |
| separated by blank lines.      |                                   |
|                                |     Indented                      |
|     Block quotes are indented. |                                   |
+--------------------------------+ or::                              |
| >>>

System Message: WARNING/2 (<string>, line 25)

Blank line required after table.

Docutils System Messages

System Message: ERROR/3 (<string>, line 3); backlink

Unknown target name: "restructuredtext".

raw rst file used in screenshot

sack

s(hortcut)-ack: a faster way to use ack (and grep)!

sack acts as a wrapper for ack to provide convenience for the repetitive menial tasks

What is ack?

ack is the replacement for grep!

Here is why you should use ack over grep: http://betterthangrep.com/

(Now that you are sold on ack) To install ack in a one-line script:

curl http://betterthangrep.com/ack-standalone > ~/bin/ack && chmod 0755 !#:3

How to Install:

Open a terminal and run the following:

git clone git@github.com:sampson-chen/sack.git && cd sack && chmod +x install_sack.sh && ./install_sack.sh

How to Use:

You can use sack in exactly the same way you currently use ack! Woot!

For why sack is faster (and more fun!) to use, read on about its main / side features...

Main Feature 1 - Shortcuts:

sack prefixes shortcut tags to ack's search results:

user@linux:~/src$ sack thumbnail

... (omitted results)
/home/user/src/reviewboard/reviewboard/attachments/mimetypes.py
[13] 6

raw .md file used in screenshot

      rendered rst html used in screenshot (pre-crop)
 <?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils 0.9.1: http://docutils.sourceforge.net/" />
 <title>The reStructuredText Cheat Sheet: Syntax Reminders</title>
 <meta name="author" content="David Goodger &lt;goodger&#64;python.org&gt;" />
 <meta name="date" content="2012-06-22" />
 <style type="text/css">
 /*
 :Author: David Goodger (goodger@python.org)
 :Id: $Id: html4css1.css 7434 2012-05-11 21:06:27Z milde $
 :Copyright: This stylesheet has been placed in the public domain.
 Default cascading style sheet for the HTML output of Docutils.
 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
 customize this style sheet.
 */
 /* used to remove borders from tables and images */
 .borderless, table.borderless td, table.borderless th {
   border: 0 }
 table.borderless td, table.borderless th {
   /* Override padding for "table.docutils td" with "! important".
      The right padding separates the table cells. */
   padding: 0 0.5em 0 0 ! important }
 .first {
   /* Override more specific margin styles with "! important". */
   margin-top: 0 ! important }
 .last, .with-subtitle {
   margin-bottom: 0 ! important }
 .hidden {
   display: none }
 a.toc-backref {
   text-decoration: none ;
   color: black }
 blockquote.epigraph {
   margin: 2em 5em ; }
 dl.docutils dd {
   margin-bottom: 0.5em }
 object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
   overflow: hidden;
+}
 /* Uncomment (and remove this text!) to get bold-faced definition list terms
 dl.docutils dt {
   font-weight: bold }
 */
 div.abstract {
   margin: 2em 5em }
 div.abstract p.topic-title {
   font-weight: bold ;
   text-align: center }
 div.admonition, div.attention, div.caution, div.danger, div.error,
 div.hint, div.important, div.note, div.tip, div.warning {
   margin: 2em ;
   border: medium outset ;
   padding: 1em }
 div.admonition p.admonition-title, div.hint p.admonition-title,
 div.important p.admonition-title, div.note p.admonition-title,
 div.tip p.admonition-title {
   font-weight: bold ;
   font-family: sans-serif }
 div.attention p.admonition-title, div.caution p.admonition-title,
 div.danger p.admonition-title, div.error p.admonition-title,
 div.warning p.admonition-title {
   color: red ;
   font-weight: bold ;
   font-family: sans-serif }
 /* Uncomment (and remove this text!) to get reduced vertical space in
    compound paragraphs.
 div.compound .compound-first, div.compound .compound-middle {
   margin-bottom: 0.5em }
 div.compound .compound-last, div.compound .compound-middle {
   margin-top: 0.5em }
 */
 div.dedication {
   margin: 2em 5em ;
   text-align: center ;
   font-style: italic }
 div.dedication p.topic-title {
   font-weight: bold ;
   font-style: normal }
 div.figure {
   margin-left: 2em ;
   margin-right: 2em }
 div.footer, div.header {
   clear: both;
   font-size: smaller }
 div.line-block {
   display: block ;
   margin-top: 1em ;
   margin-bottom: 1em }
 div.line-block div.line-block {
   margin-top: 0 ;
   margin-bottom: 0 ;
   margin-left: 1.5em }
 div.sidebar {
   margin: 0 0 0.5em 1em ;
   border: medium outset ;
   padding: 1em ;
   background-color: #ffffee ;
   width: 40% ;
   float: right ;
   clear: right }
 div.sidebar p.rubric {
   font-family: sans-serif ;
   font-size: medium }
 div.system-messages {
   margin: 5em }
 div.system-messages h1 {
   color: red }
 div.system-message {
   border: medium outset ;
   padding: 1em }
 div.system-message p.system-message-title {
   color: red ;
   font-weight: bold }
 div.topic {
   margin: 2em }
 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
   margin-top: 0.4em }
 h1.title {
   text-align: center }
 h2.subtitle {
   text-align: center }
 hr.docutils {
   width: 75% }
 img.align-left, .figure.align-left, object.align-left {
   clear: left ;
   float: left ;
   margin-right: 1em }
 img.align-right, .figure.align-right, object.align-right {
   clear: right ;
   float: right ;
   margin-left: 1em }
 img.align-center, .figure.align-center, object.align-center {
   display: block;
   margin-left: auto;
   margin-right: auto;
+}
 .align-left {
   text-align: left }
 .align-center {
   clear: both ;
   text-align: center }
 .align-right {
   text-align: right }
 /* reset inner alignment in figures */
 div.align-right {
   text-align: inherit }
 /* div.align-center * { */
 /*   text-align: left } */
 ol.simple, ul.simple {
   margin-bottom: 1em }
 ol.arabic {
   list-style: decimal }
 ol.loweralpha {
   list-style: lower-alpha }
 ol.upperalpha {
   list-style: upper-alpha }
 ol.lowerroman {
   list-style: lower-roman }
 ol.upperroman {
   list-style: upper-roman }
 p.attribution {
   text-align: right ;
   margin-left: 50% }
 p.caption {
   font-style: italic }
 p.credits {
   font-style: italic ;
   font-size: smaller }
 p.label {
   white-space: nowrap }
 p.rubric {
   font-weight: bold ;
   font-size: larger ;
   color: maroon ;
   text-align: center }
 p.sidebar-title {
   font-family: sans-serif ;
   font-weight: bold ;
   font-size: larger }
 p.sidebar-subtitle {
   font-family: sans-serif ;
   font-weight: bold }
 p.topic-title {
   font-weight: bold }
 pre.address {
   margin-bottom: 0 ;
   margin-top: 0 ;
   font: inherit }
 pre.literal-block, pre.doctest-block, pre.math, pre.code {
   margin-left: 2em ;
   margin-right: 2em }
 pre.code .ln { /* line numbers */
   color: grey;
+}
 .code {
   background-color: #eeeeee
+}
 span.classifier {
   font-family: sans-serif ;
   font-style: oblique }
 span.classifier-delimiter {
   font-family: sans-serif ;
   font-weight: bold }
 span.interpreted {
   font-family: sans-serif }
 span.option {
   white-space: nowrap }
 span.pre {
   white-space: pre }
 span.problematic {
   color: red }
 span.section-subtitle {
   /* font-size relative to parent (h1..h6 element) */
   font-size: 80% }
 table.citation {
   border-left: solid 1px gray;
   margin-left: 1px }
 table.docinfo {
   margin: 2em 4em }
 table.docutils {
   margin-top: 0.5em ;
   margin-bottom: 0.5em }
 table.footnote {
   border-left: solid 1px black;
   margin-left: 1px }
 table.docutils td, table.docutils th,
 table.docinfo td, table.docinfo th {
   padding-left: 0.5em ;
   padding-right: 0.5em ;
   vertical-align: top }
 table.docutils th.field-name, table.docinfo th.docinfo-name {
   font-weight: bold ;
   text-align: left ;
   white-space: nowrap ;
   padding-left: 0 }
 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
   font-size: 100% }
 ul.auto-toc {
   list-style-type: none }
 </style>
 </head>
 <body>
 <div class="document" id="the-restructuredtext-cheat-sheet-syntax-reminders">
 <h1 class="title">The <a class="reference external" href="http://docutils.sf.net/rst.html">reStructuredText</a> Cheat Sheet: Syntax Reminders</h1>
 <table class="docinfo" frame="void" rules="none">
 <col class="docinfo-name" />
 <col class="docinfo-content" />
 <tbody valign="top">
 <tr class="field"><th class="docinfo-name">Info:</th><td class="field-body">See &lt;<a class="reference external" href="http://docutils.sf.net/rst.html">http://docutils.sf.net/rst.html</a>&gt; for introductory docs.</td>
 </tr>
 <tr><th class="docinfo-name">Author:</th>
 <td>David Goodger &lt;<a class="reference external" href="mailto:goodger&#64;python.org">goodger&#64;python.org</a>&gt;</td></tr>
 <tr><th class="docinfo-name">Date:</th>
 <td>2012-06-22</td></tr>
 <tr><th class="docinfo-name">Revision:</th>
 <td>7463</td></tr>
 <tr class="field"><th class="docinfo-name">Description:</th><td class="field-body">This is a &quot;docinfo block&quot;, or bibliographic field list</td>
 </tr>
 </tbody>
 </table>
 <div class="section" id="section-structure">
 <h1>Section Structure</h1>
 <p>Section titles are underlined or overlined &amp; underlined.</p>
 </div>
 <div class="section" id="body-elements">
 <h1>Body Elements</h1>
 <p>Grid table:</p>
 <table border="1" class="docutils">
 <colgroup>
 <col width="48%" />
 <col width="52%" />
 </colgroup>
 <tbody valign="top">
 <tr><td><p class="first">Paragraphs are flush-left,
 separated by blank lines.</p>
 <blockquote class="last">
 Block quotes are indented.</blockquote>
 </td>
 <td rowspan="2"><p class="first">Literal block, preceded by &quot;::&quot;:</p>
 <pre class="literal-block">
 Indented
 </pre>
 <p>or:</p>
 <pre class="last literal-block">
 &gt; Quoted
 </pre>
 </td>
 </tr>
 <tr><td><pre class="first last doctest-block">
 &gt;&gt;&gt; print 'Doctest block'
 Doctest block
 </pre>
 </td>
 </tr>
 <tr><td colspan="2"><div class="first last line-block">
 <div class="line">Line blocks preserve line breaks &amp; indents. [new in 0.3.6]</div>
 <div class="line-block">
 <div class="line">Useful for addresses, verse, and adornment-free lists; long
 lines can be wrapped with continuation lines.</div>
 </div>
 </div>
 </td>
 </tr>
 </tbody>
 </table>
 <p>Simple tables:</p>
 <table border="1" class="docutils">
 <colgroup>
 <col width="21%" />
 <col width="79%" />
 </colgroup>
 <thead valign="bottom">
 <tr><th class="head">List Type</th>
 <th class="head">Examples</th>
 </tr>
 </thead>
 <tbody valign="top">
 <tr><td>Bullet list</td>
 <td><ul class="first last simple">
 <li>items begin with &quot;-&quot;, &quot;+&quot;, or &quot;*&quot;</li>
 </ul>
 </td>
 </tr>
 <tr><td>Enumerated list</td>
 <td><ol class="first last arabic simple">
 <li>items use any variation of &quot;1.&quot;, &quot;A)&quot;, and &quot;(i)&quot;</li>
 <li>also auto-enumerated</li>
 </ol>
 </td>
 </tr>
 <tr><td>Definition list</td>
 <td><dl class="first last docutils">
 <dt>Term is flush-left <span class="classifier-delimiter">:</span> <span class="classifier">optional classifier</span></dt>
 <dd>Definition is indented, no blank line between</dd>
 </dl>
 </td>
 </tr>
 <tr><td>Field list</td>
 <td><table class="first last docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">field name:</th><td class="field-body">field body</td>
 </tr>
 </tbody>
 </table>
 </td>
 </tr>
 <tr><td>Option list</td>
 <td><table class="first last docutils option-list" frame="void" rules="none">
 <col class="option" />
 <col class="description" />
 <tbody valign="top">
 <tr><td class="option-group">
 <kbd><span class="option">-o</span></kbd></td>
 <td>at least 2 spaces between option &amp; description</td></tr>
 </tbody>
 </table>
 </td>
 </tr>
 </tbody>
 </table>
 <table border="1" class="docutils">
 <colgroup>
 <col width="21%" />
 <col width="79%" />
 </colgroup>
 <thead valign="bottom">
 <tr><th class="head">Explicit Markup</th>
 <th class="head">Examples (visible in the <a class="reference external" href="cheatsheet.txt">text source</a>)</th>
 </tr>
 </thead>
 <tbody valign="top">
 <tr><td>Footnote</td>
 <td><table class="first last docutils footnote" frame="void" id="id1" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
 <tr><td class="label"><a class="fn-backref" href="#id3">[1]</a></td><td>Manually numbered or [#] auto-numbered
 (even [#labelled]) or [*] auto-symbol</td></tr>
 </tbody>
 </table>
 </td>
 </tr>
 <tr><td>Citation</td>
 <td><table class="first last docutils citation" frame="void" id="cit2002" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
 <tr><td class="label"><a class="fn-backref" href="#id4">[CIT2002]</a></td><td>A citation.</td></tr>
 </tbody>
 </table>
 </td>
 </tr>
 <tr><td>Hyperlink Target</td>
 <td></td>
 </tr>
 <tr id="internal-target"><td>Anonymous Target</td>
 <td></td>
 </tr>
 <tr><td>Directive (&quot;::&quot;)</td>
 <td><img alt="images/biohazard.png" class="first last" src="images/biohazard.png" />
 </td>
 </tr>
 <tr><td>Substitution Def</td>
 <td></td>
 </tr>
 <tr><td>Comment</td>
 <td><!-- is anything else -->
 </td>
 </tr>
 <tr><td>Empty Comment</td>
 <td>(&quot;..&quot; on a line by itself, with blank lines before &amp; after,
 used to separate indentation contexts)</td>
 </tr>
 </tbody>
 </table>
 </div>
 <div class="section" id="inline-markup">
 <h1>Inline Markup</h1>
 <p><em>emphasis</em>; <strong>strong emphasis</strong>; <cite>interpreted text</cite>; <em>interpreted text
 with role</em>; <tt class="docutils literal">inline literal text</tt>; standalone hyperlink,
 <a class="reference external" href="http://docutils.sourceforge.net">http://docutils.sourceforge.net</a>; named reference, <a class="reference external" href="http://docutils.sf.net/rst.html">reStructuredText</a>;
 <a class="reference external" href="http://docutils.sf.net/docs/ref/rst/restructuredtext.html">anonymous reference</a>; footnote reference, <a class="footnote-reference" href="#id1" id="id3">[1]</a>; citation reference,
 <a class="citation-reference" href="#cit2002" id="id4">[CIT2002]</a>; like an inline directive; <span class="target" id="inline-internal-target">inline internal target</span>.</p>
 </div>
 <div class="section" id="directive-quick-reference">
 <h1>Directive Quick Reference</h1>
 <p>See &lt;<a class="reference external" href="http://docutils.sf.net/docs/ref/rst/directives.html">http://docutils.sf.net/docs/ref/rst/directives.html</a>&gt; for full info.</p>
 <table border="1" class="docutils">
 <colgroup>
 <col width="21%" />
 <col width="79%" />
 </colgroup>
 <thead valign="bottom">
 <tr><th class="head">Directive Name</th>
 <th class="head">Description (Docutils version added to, in [brackets])</th>
 </tr>
 </thead>
 <tbody valign="top">
 <tr><td>attention</td>
 <td>Specific admonition; also &quot;caution&quot;, &quot;danger&quot;,
 &quot;error&quot;, &quot;hint&quot;, &quot;important&quot;, &quot;note&quot;, &quot;tip&quot;, &quot;warning&quot;</td>
 </tr>
 <tr><td>admonition</td>
 <td>Generic titled admonition: <tt class="docutils literal">.. admonition:: By The Way</tt></td>
 </tr>
 <tr><td>image</td>
 <td><tt class="docutils literal">.. image:: picture.png</tt>; many options possible</td>
 </tr>
 <tr><td>figure</td>
 <td>Like &quot;image&quot;, but with optional caption and legend</td>
 </tr>
 <tr><td>topic</td>
 <td><tt class="docutils literal">.. topic:: Title</tt>; like a mini section</td>
 </tr>
 <tr><td>sidebar</td>
 <td><tt class="docutils literal">.. sidebar:: Title</tt>; like a mini parallel document</td>
 </tr>
 <tr><td>parsed-literal</td>
 <td>A literal block with parsed inline markup</td>
 </tr>
 <tr><td>rubric</td>
 <td><tt class="docutils literal">.. rubric:: Informal Heading</tt></td>
 </tr>
 <tr><td>epigraph</td>
 <td>Block quote with class=&quot;epigraph&quot;</td>
 </tr>
 <tr><td>highlights</td>
 <td>Block quote with class=&quot;highlights&quot;</td>
 </tr>
 <tr><td>pull-quote</td>
 <td>Block quote with class=&quot;pull-quote&quot;</td>
 </tr>
 <tr><td>compound</td>
 <td>Compound paragraphs [0.3.6]</td>
 </tr>
 <tr><td>container</td>
 <td>Generic block-level container element [0.3.10]</td>
 </tr>
 <tr><td>table</td>
 <td>Create a titled table [0.3.1]</td>
 </tr>
 <tr><td>list-table</td>
 <td>Create a table from a uniform two-level bullet list [0.3.8]</td>
 </tr>
 <tr><td>csv-table</td>
 <td>Create a table from CSV data [0.3.4]</td>
 </tr>
 <tr><td>contents</td>
 <td>Generate a table of contents</td>
 </tr>
 <tr><td>sectnum</td>
 <td>Automatically number sections, subsections, etc.</td>
 </tr>
 <tr><td>header, footer</td>
 <td>Create document decorations [0.3.8]</td>
 </tr>
 <tr><td>target-notes</td>
 <td>Create an explicit footnote for each external target</td>
 </tr>
 <tr><td>math</td>
 <td>Mathematical notation (input in LaTeX format)</td>
 </tr>
 <tr><td>meta</td>
 <td>HTML-specific metadata</td>
 </tr>
 <tr><td>include</td>
 <td>Read an external reST file as if it were inline</td>
 </tr>
 <tr><td>raw</td>
 <td>Non-reST data passed untouched to the Writer</td>
 </tr>
 <tr><td>replace</td>
 <td>Replacement text for substitution definitions</td>
 </tr>
 <tr><td>unicode</td>
 <td>Unicode character code conversion for substitution defs</td>
 </tr>
 <tr><td>date</td>
 <td>Generates today's date; for substitution defs</td>
 </tr>
 <tr><td>class</td>
 <td>Set a &quot;class&quot; attribute on the next element</td>
 </tr>
 <tr><td>role</td>
 <td>Create a custom interpreted text role [0.3.2]</td>
 </tr>
 <tr><td>default-role</td>
 <td>Set the default interpreted text role [0.3.10]</td>
 </tr>
 <tr><td>title</td>
 <td>Set the metadata document title [0.3.10]</td>
 </tr>
 </tbody>
 </table>
 </div>
 <div class="section" id="interpreted-text-role-quick-reference">
 <h1>Interpreted Text Role Quick Reference</h1>
 <p>See &lt;<a class="reference external" href="http://docutils.sf.net/docs/ref/rst/roles.html">http://docutils.sf.net/docs/ref/rst/roles.html</a>&gt; for full info.</p>
 <table border="1" class="docutils">
 <colgroup>
 <col width="21%" />
 <col width="79%" />
 </colgroup>
 <thead valign="bottom">
 <tr><th class="head">Role Name</th>
 <th class="head">Description</th>
 </tr>
 </thead>
 <tbody valign="top">
 <tr><td>emphasis</td>
 <td>Equivalent to <em>emphasis</em></td>
 </tr>
 <tr><td>literal</td>
 <td>Equivalent to <tt class="docutils literal">literal</tt> but processes backslash escapes</td>
 </tr>
 <tr><td>math</td>
 <td>Mathematical notation (input in LaTeX format)</td>
 </tr>
 <tr><td>PEP</td>
 <td>Reference to a numbered Python Enhancement Proposal</td>
 </tr>
 <tr><td>RFC</td>
 <td>Reference to a numbered Internet Request For Comments</td>
 </tr>
 <tr><td>raw</td>
 <td>For non-reST data; cannot be used directly (see docs) [0.3.6]</td>
 </tr>
 <tr><td>strong</td>
 <td>Equivalent to <strong>strong</strong></td>
 </tr>
 <tr><td>sub</td>
 <td>Subscript</td>
 </tr>
 <tr><td>sup</td>
 <td>Superscript</td>
 </tr>
 <tr><td>title</td>
 <td>Title reference (book, etc.); standard default role</td>
 </tr>
 </tbody>
 </table>
 </div>
 </div>
 </body>
 </html>