This post originated from an RSS feed registered with Java Buzz
by Wilfred Springer.
Original Post: Automatic preview for reStructuredText
Feed Title: Distributed Reflections of the Third Kind
Feed URL: http://blog.flotsam.nl/feeds/posts/default
Feed Description: Distributed Reflections of the Third Kind
I have to admit, I'm a markup junkie. I do believe that with some other folks that markup picks up where punctuation left off. That's why I - when still at Sun - always fought management to be able to use DocBook instead of StarOffice. I like the WYGIWYM (What You Get Is What You Mean) paradigm; I'm not a huge fan of WYSIWYG - probably mostly because I almost never get what I want, and I don't want to get constantly reminded of that.
Now, I still like DocBook, in a way, but the last couple of years I started to see there is a point in having markup that is a little easier on the eyes. I like Markdown, but I have to say: I like reStructuredText even more, and that's probably - again - since I can be much more specific. (This is not only verbatim text, it's Scala source code.)
The other day, I stumbled across Marked. It looks like an excellent tool, and not all that expensive. I would have gotten it if only it would have offered support for reStructuredText as well - but it doesn't. Still, I couldn't stand not having the same kind of authoring experience when writing reStructuredText.
(If you don't know what Marked is: it's a tool that automatically updates a preview of the Markdown document you're authoring. It works with any editor. As soon as you hit 'Save', it will update the preview.)
Meet Rested, Marked for reStructuredText
Good news. There is a way to have the same convenience as what Marked is giving you, even if you're writing reStructuredText. Admittedly, there is a little more work you need to do, but once you get it done, the net effect is pretty much the same. (Or better, since now you can also write reStructuredText.)
Perhaps it's best to first check the video, and then read on.
What do you need?
First of all, you need to install a couple of gems:
Guard is the tool that is monitoring your filesystem for changes. It allows you to set up some rules for responding to changes in a DSL.
Once you installed these gems, next you need to add the rules for your DSL. First you need to get a basic Guardfile. In my case, I started typing a couple of commands, to get the basic file in place, but you might as well just write your own and ignore the commands.
guard init guard init shell guard init livereload
I made some changes, and in the end my file looked like this:
guard 'shell' do watch('(.*).rst') {|m| `rst2html --link-stylesheet --stylesheet-path=/Users/wilfred/workspace/rested/style.css #{m[0]} target/#{m[1]}.html` } end
guard 'livereload' do watch(%r{(target/).+\.(css|js|html)}) end
So, what does this script do? Well, if you start guard, it will start monitoring the directory in which the file is placed for files with an .rst extension. In case they get modified, it will run the script for turning the file into an HTML file.
The other portion is even more interesting. It monitors the target directory for changes, and inform your browser of the changes. That is, you do need to install a Livereload plugin into your browser, and make sure it's activated for the page that you're looking at, but then for every change to the HTML it will reload the page.
Conclusion
I felt much better about using reStructuredText when I found out there is a way you can simulate Marked behavior with just a bunch of tools. With this in place, I got even more convinced that I don't need a Scrivener license any longer. Just a text editor and a couple of ruby tools, Emacs and a browser is all I need.
Previous Topic
