XWT
Water!
XML editing with XML schema
Why XML?
What is XSLT?
« Fists of fury
» CSV to ASCII Grid
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.
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.
if 0: to if 1:, to
enable the reST plugin. use_plugins = 0 to use_plugins = 1.use_plugins = 1.
Next time, when you start Leo, you should see a mod_rst.py enabled
message in the console window.
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 :Contact: myemail@myworld.com :Organization: My Company :Status: Draft :Revision: $Revision: 0.01 $ :Date: $Date: 2003/06/02 20:54:10 $ :Abstract: 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 mod_rst.py 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.
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 mod_rst.py in the log window.
Needless to say, the rest of the instructions didn't work either. Ho hum ;)
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
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.
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?
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 :-)
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 mod_rst.py 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
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.
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 'rst.py' 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.
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/rst2.py 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:
<snip>
**code**:
.. class:: code
</snip>
at the beginning of each chapter.
How can this be avoided ?
Any help will be appreciated.
Cheerio
Juergen