reStructuredText Tools for Gedit

Syntax highlighting, keyboard shortcuts ("snippets"), and HTML preview for reStructuredText in gedit.

Contents

• Download, installation and usage
• Syntax highlighting
  • Creating an RST MIME type
• Snippets accerlators
• Preview plugin

Download, installation and usage

Read the rest of the document for more detailed information, including any dependencies. The short version is:

• Download and unpack the tarball. (Alternately, for the latest source: darcs get http://fs.textmethod.com/repos/textmethod)
• Place rst.lang in ~/.gnome2/gtksourceview-1.0/language-specs/
• Place rst.xml in ~/.gnome2/gedit/snippets
• Place markuppreview.py and markuppreview.gedit-plugin in ~/.gnome2/gedit/plugins
• Start gedit and go to Edit > Preferences > Plugins to enable it.
• Try it out by selecting Select View > Highlight Mode > Markup > reStructured Text and Tools > Markup Language > reStructured Text, and working with your RST document.
• Optionally, follow the section on Creating an RST MIME type. Doing so will mean that loading files with an .rst extension will automatically select the appropriate radio buttons.

Syntax highlighting

Syntax highlighting is handled by the rst.lang file, which needs to be placed in your ~/.gnome2/gtksourceview-1.0/language-specs/ directory. (If you want to make this feature available globally, you'll want to place the file in /usr/share/gtksourceview-1.0/language-specs/.)

The file consists of a set of regular expressions that match common RST syntactic structures. The "style" element of the tags indicates which gedit style to apply. Note that gedit default styles usually just consist of a color scheme with boldfacing of certain elements. You can customize the scheme for RST via Edit > Preferences > Syntax Highlighting to achieve more interesting and useful effects. For example, I've chosen to give a gray background to literals, both block and inline, and a red background to directives.

Note that the file references a MIME type called text/restructured. (See next section.)

Creating an RST MIME type

If you want files with an ".rst" extension to automatically set the highlight mode to reStructured Text (as gedit already does with source files), you'll need add a MIME type to your Gnome system, as described in this tutorial. The short version is to create or edit your system's /usr/share/mime/packages/Overrides.xml file with the following entry:

<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
  <mime-type type="text/restructured">
    <alias type="text/x-rst" />
    <comment xml:lang="en">reStructured Text document</comment>
    <glob pattern="*.rst"/>
  </mime-type>
</mime-info>

Snippets accerlators

gedit "snippets" are basically keyboard shortcuts. They require the Snippets plugin, which shipped with gedit in Ubuntu Dapper, and hopefully other distros as well.

They're defined by the rst.xml file which must be placed in your ~/.gnome2/gedit/snippets directory (or /usr/share/gedit-2/plugins/snippets for global installation).

I've included 3 snippets to start:

• Text emphasis: Pressing Control-E on highlighted text emphasizes the text (i.e., puts asterisks around it)
• Hyperlink shortcut: Pressing the backtick character (`) and then tab, expands an RST link definition
• typing "lst" and then tab creates an unordered list.

Preview plugin

The preview plugin is based on the Markdown preview plugin, which it extends to include support for HTML, reStructuredText and Textile. Note that you'll have to have the docutils, python-textile, and markdown.py packages installed to support RST, Textile, and Markdown, respectively. Unavailable options will be grayed out.

It also requires the Python gtkhtml2 library, which on Ubuntu Dapper is included with the python-gnome2-extras package.

The plugin provides a "Markup Preview" tab in the bottom panel (press Ctrl+F9 to toggle), and a shortcut (Shift+Ctrl+M) to render your markup to HTML.