A ReStructuredText Primer
=========================

:Author: Richard Jones
:Version: $Revision: 4350 $
: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

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**``".

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 * asterisk is handled just fine.  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

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::

Add Line Breaks

On 20 Nov 2007, at 22:33, Robin Houston wrote:

On 20/11/2007, Frank Eves gold_eagle@mac.com wrote:

• TextMate Soft Wrap set to 66 characters
• How do I Hard Wrap my document at 66 columns?

As far as I know, TextMate doesn’t have a built-in command to do this. You can use Text > Filter Through Command… to run some external formatter of your choice. Unfortunately the BSD version of fmt included with OS X can’t quite be made to do the right thing […]

fold -sw66 though should do exactly what Frank wants. Or to make it actually use his soft wrap setting: fold -sw$TM_COLUMNS

Using Perl:

If you don’t need to worry about dealing properly with (hard) tabs, then you can easily write a short command to do the reformatting.

Set input to “Entire Document”, output to “Replace Document”, and put the code

#!/usr/bin/perl -p
print "$1\n" while s/(\S{$ENV{TM_COLUMNS}})//;
print "$1\n" while s/(.{0,$ENV{TM_COLUMNS}})\s//;

into the Command(s) box. This will treat a tab as though it took up a single column, so if you have a lot of tab indents then it will leave excessively long lines. Writing something that deals properly with tabs would be a bit harder, but very possible.

===

How to select something in a document by using a macro/command?

I found a way to select something – calculated on run-time – by using a normal macro (plus command) without TMTOOLS!!

The problem was if I have a script which outputs a text chunk or a regexp how can we select that text/regexp in a TM window? The approach is actually very simple. I copy the text/regexp into the shared find pasteboard; place the caret to a proper location; and execute ‘findNext’. Thus I wrote a tiny C program which copies a string into the shared find pasteboard. OK, then I wanted to write a man page for that command on basis of the normal pbcopy man page, and I figured out that pbcopy is already able to do this ;)

Fine. The only problem was that if I write a tmcommand à la:

echo -en “FINDTEXT” | pbcopy -pboard find

it doesn’t work because “pbcopy -pboard find” is called from inside of TM. If I execute that in a Terminal, switch back to TM it works. The solution: I have to execute this in a new bash environment.

The basic tmcommand (example name “SELECTTEXT”):

RESULT=$(A SCRIPT WHICH RETURNS A TEXT OR REGEXP) export RESULT /bin/bash -c ‘echo -en “$RESULT” | pbcopy -pboard find’ #place the caret to a proper location to be able to execute ‘findNext’! open “txmt://open/?line=$LINE&column=$COLUMN”

After executing that command the string $RESULT is in the shared find pasteboard, and the caret is set.

Next step > the macro: Before we can execute ‘findNext’ (= APPLE+G) we have to set the parameters of the find panel, meaning whether we want to do a regexp search or not; ignore case or not.

Thus record a macro à la:

1. open find panel, set the desired parameters, and do a dummy search for something which is NOT in the document -e.g. look for \xFFF3; and close it

2. execute the command “SELECTTEXT”

3. APPLE+G

That’s it. The nice side-effect is that the macro changes nothing within TM’s find panel ;) And the macro does not affect the undo buffer, it does not change the text etc., and the selection is done instantly.

But attention: The only tricky point : Be aware of correct escaping!!

On that basis I wrote the “Select XML/HTML balanced tags” script which will come as soon as possible. I only have to fix some tiny things.

Comments?

Addition:

To minimize the escaping one can use:

/bin/bash -c ‘echo -n “$RESULT” | pbcopy -pboard find’

instead of:

/bin/bash -c ‘echo -en “$RESULT” | pbcopy -pboard find’

Addition II:

To get rid of the utf8 encoding one can use:

/bin/bash -c ‘export __CF_USER_TEXT_ENCODING=0x1F5:0x8000100:0x8000100;echo -n “$RES” | pbcopy -pboard find’

On 5. Apr 2007, at 16:26, Digital Rust wrote:

Hi, the tidy feature used to create an xtml compliant document. Since I upgraded to 1.5.5 it now creates an HTML 4.01 doc. How can I change this back to XTML?

Set TM_XHTML to ” /” in Preferences → Advanced → Shell Variables, that should both make inserted tags XHTML and make Tidy default to XHTML as output.

I’ve just been trying TextMate, trying to move away from TextEdit and TextWrangler. One thing which is really bugging me is the way it underlines hyperlinks on the ‘Plain Text’ setting. If I wanted that kind of behaviour I’d use Microsoft Word! Is there a way I can set it up so that plain text is exactly that, completely plain vanilla typing?

Thanks

Go to the Bundle Editor (Bundle -> Bundle Editor -> Show Bundle Editor) and open the Text Bundle (click on the triangle). Then to scroll down to the object “Plain Text” with a gray L in front of it. If you want to remove all markings then just delete everything. If you just want to remove the underlined links then delete the following:

{ begin = ‘^([ \t]*)(?=\S)’; end = ‘^(?!\1(?=\S))’; patterns = ( { name = ‘markup.underline.link’; match = ‘(?x) ( (https?|s?ftp|ftps|file|smb|afp|nfs|(x-)?man|gopher|txmt)://|mailto:) [-:@a-zA-Z0-9_.,~%+/?=&#]+(?<![.,?:]) '; }, ); contentName = 'meta.paragraph.text'; },

Then close the bundle editor and TextMate and start it again.

I am now, more than ever, convinced that writers should be taught how to write on text editors and not on modern word processors. The same goes for beginning writers as well as advanced writers.

Why? Good text editors — and there are plenty of good ones for the Mac, for Linux, and for Windows — do not give you WYSIWYG. (“What You See Is What You Get” is a close approximation of what the printed page will look like). Instead, text editors give you a blank screen, perhaps some line numbers, perhaps some syntax coloring (more on this in a moment) and no real sense of what the output is going to look like. And that’s a good thing, because you shouldn’t be thinking about the output while you’re writing. You should be thinking about what it is you are trying to communicate. You shouldn’t care what the margins look like, what the headers and footers look like, what the headings look like, etc. What you should be paying attention to are the words themselves and how you structure them into paragraphs and sections that convey what it is you are trying to say.

Unfortunately, most word processors sidetrack writers, especially inexperienced writers, into worrying about formatting, into confusing the styling of typography with styling of prose. (Mark Turner’s Clear and Simple as the Truth explores what style really is.)

I want to be clear: typography and design are important, but they are only important insofar as they reflect and/or augment what it is the text itself is trying to say. Or, as I will say more about in a minute, design should be a function not only of the text and the audience and the intended meaning but also the medium in which the transaction is taking place. Even some of university professors and high-powered business people confuse formatting with structure, and so what hope for beginning writers and thinkers? And it’s going to get worse before it gets better, because for every web application that uses Markdown, Textile, ReST, or some other version of easy-to-use markup, there are four web apps that provide a WYSIWYG editing interface.

So let loose the dogs of bold and italics! Facebook and MySpace have made everyone having a home on the internet easy, but in making it easy they have also taken a lot of thinking out of the process. Okay, I’m a humanist. I think thinking should always be a part of the process. It stings me that so few humanists worry about this. I understand that not everything needs to be thought about. My wife is a good example. For her, Microsoft Word works just fine. And, so far, she has never had a Word document go bad. I have. And it only took a time or two before I began thinking about not only how my data was locked up in someone else’s proprietary format — it’s a lot like someone encoding your data and turning it into a secret message that you can’t open with anything else but their key — but also how fragile that format was. Fragile both in terms of corruptibility and in terms of longevity. And never mind that every document was ten times, ten times, the size of the data it contained. What else was Word stuffing in there?

Elsewhere I’ve written about the importance of thinking about platforms, so I won’t go into it here. But obviously one thing having “just plain text” that can then be transformed into xhtml and from there into an rtf document or a PDF or a myriad of other things does is allow the writer to move quickly across platforms, multi-purposing their work. It’s my belief that we’re going to have to teach both humanists and communications people not only how to do this but the mindset behind it. I know the humanists aren’t getting it in their classes, and I’m pretty sure the communications folks aren’t either.

Personally, I think this is the key not only to good thinking, but also the key to good design. Once you “get this,” then your world changes. Suddenly, all media forms become languages that have their own grammars that you are free both to use conventionally and also innovate within — depending upon your objective.