Related Entries

XML editing with XML schema
Why XML?
What is XSLT?

« Fists of fury
» CSV to ASCII Grid

Using Leo for reST

Notes on coupling a great outliner with a great document format to make an easy documentation tool.

Leo is a terrific outliner and literate programming editor. For writing big documents including user documentation, presentations, tutorials etc., I would like to first create an outline. I love using Leo for that, because almost everything I need in Leo can be done via keyboard short-cuts.

re-Structured Text (reST) is a great format for writing plain text with some semantics. reST is far more easier to write documentation than using plain HTML. Writers are available to convert reST to many different formats, including DocBook.

So, why don’t I try to make my outline’d document in Leo and then get it into atleast HTML? I wrote a silly XSL to do that. But, I really wanted to use reST to be the language of choice for formatting. It turns out that Leo already comes with code for doing all that.

Note: Things have changed a bit after Leo 4.2 was released. For new instructions, please see my new entry on the subject. The old installation instructions below are only for historical interest.

Setting up the pieces

The striked out sections are for instructions when the article was originally written; other ones are valid with Leo version 4.1RC3, which has been available from 12/18/2003. The updates and strikes were made on 01/01/2004.

  1. Get and install docutils.
  2. Open LeoPy.leo from Leo distribution. Navigate to Customizing Leo - Plugins - Contributed Plugins. Scroll down the code for node and change if 0: to if 1:, to enable the reST plugin. Open plugins/leoPlugins.leo from Leo distribution. Navigate to @file pluginsManager.txt. In the body, add towards the end, to enable reST plugin.
  3. Right click on @file plugins/ and choose Write @file nodes.
  4. Now, go to Help - Open LeoConfig.leo in the main menu.
  5. Navigate to leoConfig.leo - @root leoConfig.txt - General Configuration Options....
  6. Scroll down the body pane and change use_plugins = 0 to use_plugins = 1.
  7. Go to File - Tangle - Tangle All and exit Leo, after saving the document.
  8. update: Looks like Tangle All doesn’t overwrite leoConfig.txt, which is the real configuration file. You can edit that file and set use_plugins = 1.

Next time, when you start Leo, you should see a enabled message in the console window.

Using Leo for reST

To write a reST document, start the root of your document with a headline (ie., a node’s name in Leo-speak) as: @rst my_restructured_text_file.rst

In that root node, I usually put the document fields, in the body. An example is given below. For more information about reST document fields, refer to the reST documentation.

My Document’s Title
:Author: My Name
:Organization: My Company
:Status: Draft
:Revision: $Revision: 0.01 $
:Date: $Date: 2003/06/02 20:54:10 $


   Simple document!

.. contents:: Table Of Contents
   :depth: 4
.. sectnum::
   :depth: 6

Edit away your document’s outline in Leo. Each node’s headline is automatically converted into a reST header according to indentation; ie., a 3rd level child node in Leo will automatically be written as header-3 in reST.

For sake of consistency, I tend to leave a blank line each at the top and bottom of each node’s body. This helps in avoiding line spacing issues that might come up. Extra blank lines don’t hurt reST.

To generate the reST document, simply double click on the node that says @rst my_restructured_text_file.rst. The reST file is generated. Now you can use the tools that come with docutils to generate HTML or any other format, from that reST document.

If you’ve questions about Leo, or the plugin, please use Source Forge forums. If you’ve questions about reST, consult that project’s site.

I’ll try to upload a sample Leo document as an example.

  1. Intrigued, I checked it out. Didn't seem to work for me. I've not used Leo before, so it's quite possibly user error. I followed the instructions but got no message about in the log window.

    Needless to say, the rest of the instructions didn't work either. Ho hum ;)

    Posted by: Richard Jones on June 3, 2003 02:29 AM
  2. Hmmm... I tried a fresh install using Leo on Win98. Had the same issue as Richard's. Found that step #7 doesn't work, even if I do "Apply Settings" from the menu.

    Work around - Go to Leo's installation folder, edit leoConfig.txt, search for use_plugins = 0 and make it use_plugins = 1

    Posted by: Babu on June 3, 2003 07:54 AM
  3. I downloaded and installed leo 3.11 & followed these directions. The plugin was properly enabled & everything seems to work. I'm new to Leo, though and still a bit baffled... time to read some docs.

    Thanks for posting this, though! I enjoy ReST & this looks like it'll make it even easier to use.

    Posted by: brian dorsey on June 16, 2003 02:08 AM
  4. I have noticed one strange (to me) ting - I expected my .rst file to be created in the same location as my .leo source file. However, it was originally created in the leo/plugins directory. After playing with the file more, it was saved in the leo dir. Any ideas?

    Posted by: brian dorsey on June 16, 2003 02:16 AM
  5. Brian, for me, .rst files were created in the same location as my .leo files... In Win98, XP and in Linux - 3 different machines. No idea :-)

    Posted by: Babu on June 16, 2003 08:05 AM
  6. I think I'm completely addicted to Leo now. My .rst files are now being created in the same directory as my .leo files - I'm not sure what changed there.

    Reading the comments in I discovered that you can output HTML via the ReST parser directly from this plugin by just changing the @rst filename.rst to @rst filename.html. Very nice. Also, it looks like the 0.3 release of docutils adds an option to embed the CSS in the html (which I like for distributing the html files) I was able to modify the output from the plugin to use that by changing the call to pub.publisher() to: pub.publish(argv=['--embed-stylesheet'])

    Having great fun with Leo & ReST! --Brian

    Posted by: brian dorsey on June 28, 2003 05:13 PM
  7. I found out why reST generated HTML files elsewhere --silly me! reST plugin writes generated files from Leo in the folder in which Leo was started. If we use Start Menu to run Leo, the startup folder is Leo's installation folder. The files get written there.

    If you just double-click a Leo file, the startup folder is that file's folder. In this case the file gets generated there, as we want it to be.

    Posted by: Babu on January 1, 2004 02:54 PM
  8. I had been using rst and leo for sometime now, and just upgraded to Leo 4.1 final.

    In addition to following the new instructions above to enable plugins, I had to do one other step to get it working again (so that double click on a top icon would export .rst and .html files).

    I had to add an '' line to the file leo/plugins/pluginsManager.txt

    Leo (this version anyway) only loads plugins explicitly listed in that file.

    Thanks for a cool bit of software. Not since my old DOS days with Grandview have I had such a happy place to write docs and outlines.

    Posted by: Paul Jackson on March 8, 2004 01:30 PM
  9. I have some problems using leo 4.2 on an XP machine.
    First of all there seems to be a bug in file leo/plugins/ line 162
    "writeTreeAsRst(rstFile,fname,p,c)" # syntax parameter is missing
    I changed that to:
    "writeTreeAsRst(rstFile,fname,p,c,False)" # workaround

    Furthermore to the generated .rst file leo adds some unwanted lines:


    .. class:: code

    at the beginning of each chapter.

    How can this be avoided ?
    Any help will be appreciated.


    Posted by: juergen on November 2, 2004 08:55 PM