reStructuredText Plugin for RapidWeaver

Features

  • Standard page plugin for reST. Using this means you don't have to use a Styled-Text page and mark/highlight sections. As well, the HTML output will be a little nicer than with Styled-Text.
  • Styled-Text page plugin for reST. This is a must if you ever want to use reST inside a Blog entry.
  • Bundled front-end for reST which can incorporate Pygments, along with the ability to reformat it nicely for Styled-Text (and for a normal page as well).
  • Customizable command-line options for the reST front end.
  • The ability to use your own reST front end instead of the bundled version.

Oh, and just FYI, this doc was written with reStructuredText.

TODO

  • Figure out to handle errors properly. I've got to dig in to exceptions in ObjC and figure out how it does throw/catch/etc... Probably no big deal, but I still gotta do it.
  • Error handling is pretty bad :) For instance, if you don't use the bundled front end, but also don't specify an alternate, then all you get is some cryptic error about scriptPath.
  • Put something better in for the override parser. Clearly some regexps would be better.
  • Make a neat little icon for the ReST plugin... how the hell do you make icons?
  • Implement cancel

Download

Head to this page to download.

Installation Instructions

Docutils

For this, obviously, you're going to need the reStructuredText code. You can obtain this as part of the Docutils project. Get it from the Docutils Homepage. Follow the installation instructions and run a quick test. Make sure it works.

Pygments (optional)

One of the big reasons I use reST is because of Pygments, but if you don't need it or want it, then you can just skip this step. Pygments allows you to nicely highlight and format "sourcecode", whether it be bash, HTML, C/C++, Ruby... whatever.

If you want to use Pygments, you can get it from The Pygments Homepage or be more direct by going to The Pygments download page at sourceforge.

Install it, make sure it does what you want, but don't worry about installing or making a special front-end for it as the bundled one has some special stuff in it that will make it format properly for Styled-Text and also does a pretty nice job on normal pages as well.

The RapidWeaver Plugins

These are easy -- just double click on them and the go in.

  • The "ReST" plugin is the standalone page-type of plugin.
  • The "STReST" plugin is for Styled-Text pages.

You can always pick up the latest of these plugins at http://derekwyatt.org/rapidweaver/reStructuredText/reStructuredText.html.

How To

There's not really that much to it. The goal here is to simply enter a bunch of valid reST markup and when it renders, it will turn itself into some nice, valid HTML.

Settings

The only interesting bits come from the Preferences. On an ReST page, simply click on "Global Settings" and they pop up. On an STReST page, select "Settings" from the Format -> reStructuredText menu. In either case, you'll get the following:

assets/settings_window.png
Use bundled reSTRWFront
A decent little front-end to reST is bundled with each of the two plugins. If you select this then you will get some of the other features in the preferences.
Path to reST front-end
If you opt-out of the "Use bundled reSTRWFront" then you must provide a path to an alternate. This is where you do it.
Agruments for front-end
Pass in any of the standard options for the front end here.
Convert spaces to   in sourcecode directive
If you are using the reSTRWFront front-end and you have Pygments installed, then you can convert any spaces to &nbsp;. This is most important in the STReST plugin as the Styled-Text page is going to make the <pre> aspect of the code pointless.
Code wrapper start
I like to have my own wrapper around the Pygments generated HTML. It allows me to format things nicely. I use <div class=styledcodecontainer><code>, but that's pretty specific for me.
Code wrapper end
Do something reasonable here. To complete the wrapper, I use </code></div>, but again your specific situation will probably be different.

Settings Override

Just for fun, I put in a dead-simple override directive into the parser. By dead simple, I mean that it's stupid, and unforgiving :). If you put the following at the top of your reST document (and I do mean the top -- the first "[" must be character 0):

[reST Options]
arguments = < put your arguments here >
executable = < put the path to the executable here >
starttag = < put your starttag override here >
endtag = < put your endtag override here >
convert = < 1 or 0 goes here >
[/reST Options]

You can have any number of those in that section to override the specifics, but you have to have one space on either side of the equals sign.

This allows you to have a per-page override for various things. I don't know why you'd need it but, hey... you've got it if you want it.

Credits

Version History

0.3

  • Fixed up an annoyance caused by Styled-Text pages. Styled-Text will concatenate strings separated by newlines. All newlines are now replaced by single spaces. Doing this before the data gets back to RW fixes the problem.

  • A bug crept into the Python code. There was an exception that would occur if you didn't install Pygments which resulted in a consistent error:

    Exception while exporting page

*** -[NSCFString deleteCharactersInRange:]: Range or index
out of bounds

0.2

  • Changed the colour to something a little lighter on the styled text pages. It was black on darkish brown, which was a bit hard on the eyes. Lightened up the brown a bit.
  • Fixed an annoying and really quite stupid bug with the preferences. The bundled front end checkbutton, somehow, got unbound.

0.1

  • Initial release.
Last modified on April 1st 2007