So, after slogging long and hard through the wee hours of the night, ReSTedit now supports non-contiguous selection and columnar selection. Simply cmd-drag to extend the selection in a non-contiguous manner and option-drag to make a columnar selection.

It was really really hard to do.

Yup. That is all a pack of lies outside of that ReSTedit now has said features. I didn’t do anything other than notice a new feature in Cocoa’s Text subsystem. All Cocoa apps now support these features which means, of course, that all PyObjC apps support these features, as well.

This post is targeted to that kind of developer.

Mac OS X ships with a perfectly usable build of Python included in the system (as long as you install the BSD package, which is enabled by default).

First, install the most recent production release of the Subversion client. That link leads to some very convenient to install packages. Alternatively, installation via Fink or DarwinPorts will also work quite nicely. Or you can build it from the source.

Next, grab a pre-compiled copy of the readline.so module. Decompress it, then copy it into the appropriate place within /Library/Python/2.3/. Interactive Python without readline is miserable.

Then grab the top-of-tree of the PyObjC repository via Subversion. The top-of-tree is almost always very stable as a result of the relatively large and high quality unit testing suite and the focus-on-quality of the developers. Once installed, the benefits are two fold. First, it will install PyObjC, including all examples, the Xcode templates, and the runtime itself. Secondly, it will install py2app which will allow one to easily package Python modules and applications, including creating Installer packages out of any standard Python module.

svn co http://svn.red-bean.com/pyobjc/trunk/pyobjc/

And build/install it:

python setup.py bdist_mpkg --open

The above will build a .mpkg that contains PyObjC, py2app, and related resources, then open it the Installer application.

From there, it is a matter of choosing your favorite editor. Xcode, SubEthaEdit and Emacs can all edit Python quite effectively. The key is to turn off tabs. Never, ever, insert tabs into Python source — always use spaces.

There are other editors available. I pretty much stick to a mix of Emacs with a custom setup (you’ll want to grab the latest python-mode, at the least) and Xcode, with the occasional bout of SubEthaEdit, depending on mood.

For learning Python, I would start with Dive Into Python and then– because this is aimed to Mac OS X developers– move on to ripping into the PyObjC examples. Also, ReSTedit is a fairly decent sized Cocoa-Python application that is under active development, tends to track the latest changes in PyObjC, and has a couple of relatively complex third-party Objective-C classes integrated into the project.

That should provide a pretty decent foundation for both generic and Mac OS X specific Python development. Certainly, there are any number of other tools that one might install, varying in size and complexity.

Recommendations, corrections, and suggestions welcome.

I re-rendered both the Primer and ReST Specification with the new CSS. Click through for a view of how it looks.

Thank you to Ian for providing the CSS! Very nice.

I also added the PEP CSS as found in the Docutils CVS repository. It is even more plain than the default CSS. There is certainly room for more styles.

Now I just need to figure out how to deal with setting a default style and potentially remembering the style per document.

I have rendered both A ReStructuredText Primer and reStructuredText Markup Specification. Each document embeds the default CSS included with docutils.

The ReSTedit README is a simple reStructured Text document that does not include the embedded CSS.

Note that this would benefit a lot more than just the ReSTedit community. docutils is the underlying formatting engine used by ReSTedit. It is portable to all platforms that run Python and has a good sized user and quite active user community. This subject has come up within that community several times and a choice of different CSS has been on the todo list for a long time.

Also, there is a growing community of weblogggers that are using reStructured Text for their posting. A variety of CSS would help that community, too.

Feel free to email me any CSS contributions. Anything that is an improvement will be added to ReSTedit and forwarded to the docutils community.

Update: Links to the spec and primer are [hopefully] fixed now.

I like the idea, but the result is useless. The “Render” button is slow, Auto Update isn’t Auto, and for some reason the rendered text is fucked up with characters being way to high.

See http://soiland.no/screenshots/restedit.png/view for example

I like the claim that the render button is slow. Not only is it slow, it isn’t hooked up at all! Neither is the Auto Update checkbox. The only rendering the app does is via the Auto Update timer, which he claimed didn’t work. That is pretty funny.

Now, as far as his claim that the output is rather fugly. Yup. Absolutely right. Sucks, doesn’t it.

So fix it and send me some new CSS! I tried and was tortured by the tools used to edit CSS (that, and I suck at web page design anyway).

The output format is entirely controlled by a CSS file found within the app wrapper. It is the same CSS that is provided in the docutils project source. Fix up that CSS and the rendered documents will look much better.

Update: I have added a toolbar item that allows you to quickly swap between style sheets. It is populated with any style sheets found in ~/Library/Application Support/ReSTedit and in the app’s wrapper.

This link leads to the current CSS style sheet used by docutils (and, hence, ReSTedit). Save it into the above directory and edit away!

And, of course, if anyone comes up with a decent style sheet or two, I’ll quite happily add it into the ReSTedit source.

As it turns out, it was trivial to add support for such to ReSTedit and doing so lays the foundation for different kinds of docutils output– HTML without CSS, PDF, etc..– that has been on the TODO list since the project was started.

The current ReSTedit top-of-tree contains support for MarkDown. There is now a pop-up button on the toolbar that can be toggled between ReST and MarkDown. As soon as it changes, the content on the left is re-rendered using whatever markup language has been selected.

ReStructured Text seems to be a superset of MarkDown; I don’t really see anything in MarkDown that can’t be done in ReStructured Text nearly as conveniently. From my brief play, I’m not sure why there was a need for MarkDown as opposed to simply using docutils & ReStructured Text directly. It is quite convenient that MarkDown can produce document fragments, but it would not be hard to patch docutils to do exactly that.

In any case, if you want to build a version of ReSTedit that supports MarkDown (on Panther), then:

- download and install PyObjC 1.2

- download and install docutils 0.3.8 (package on my file sharing page)

- grab the source from here (you can mount that URL in the Finder or use ‘svn checkout’)

- cd into the restedit source and python setup.py py2app

The built app will be found in the dist/ directory.

A build of ReSTedit 0.50 is available on my .mac file download page. It should “just work” on any Mac OS X 10.3 system as it includes both the pyobjc and docutils libraries within the app wrapper.

Beyond a handful of bug fixes, ReSTedit includes new features described in this post.

The README and ToDo list have also been updated.

Over vacation, I have recreationally hacked upon ReSTedit. In particular, I wanted to add two features that have been on the todo list since the project’s inception.

First, the toolbar has always had a segmented control that indicates whether both the source and rendered views were visible or which one was visible in the case where the vertical split view was fully expanded or collapsed.

It was totally useless. The original intention was to allow the user to click on one of the segments to pop the split view to a particular position, as appropriate.

Unfortunately, NSSplitView does not have API to tightly control the position of the split. Rainer Brockerhoff wrote a replacement for NSplitView called RBSplitView that does provide programatic control over the split.

Once I figured out how to plug the views into RBSplitView, it all just works. The real challenge was mostly of my own creation. RBSplitView is really designed to work via instantiation from an IB palette. I chose to configure it from my code because I didn’t want to have the palette around to edit the NIB and I eventually want to add some dynamic UI behavior.

Now, the reason why I wanted the above feature was for the second feature. Long ago, I added Uli’s UKKQueue class to the project. The intention was to monitor any opened files and automatically re-render the ReStructured Text whenever a file is changed on disk.

I never got around to implementing the feature because I assumed it would be more challenging than it appeared and I didn’t have the time to go off and figure out what the hell was going on if something break.

That particular assumption proved to be very accurate.

KQueue’s work by monitoring a particular open file for various events like delete, rename, write, attributes changed, or the like.

My initial naive implementation optimistically assumed that I could monitor the file for WRITE events and respond by reverting the document.

That didn’t work. As a matter of fact, it broke in different ways depending on which app the file was saved within. For emacs, you might see a delete event or a rename event depending on if a backup file is created or not. This also means that NSDocument will sometimes follow the file to the backup; that is, you’ll end up editing ‘foo.txt~’ instead of ‘foo.txt’. For TextEdit, it is a slightly different sequence of events.

All in all, it required quite a bit of head scratching and ‘print’ style debugging to figure out what the hell was really going on with each editor. I think I have a relatively complete solution now. Of course, then there was the little problem of leaking open file descriptors.

In the end, I watch for WRITE, DELETE, RENAME or EXTEND events. If any are received, I revert the document (and warn the user if there are unsaved changes that might be lost).

All of the code can be found in the ReSTedit SVN repository. REDocument.py contains all of the kqueue related code beyond the very simple bridge code found in ukkqueue.py. REWindowController.py contains all of the code related to the RBSplitView configuration and interaction.

Specifically:

A series of commits from Bob Ippolito and Ronald Oussoren have made it much less painful to use PyObjC with Distributed Objects, NSProxy, and in threaded environments. It worked before, but barely and inneffeciently. Now it is relatively stable. If this sounds a bit non-commital, it is because in-process DO, threading and use of NSProxy are all hard to get right, regardless of language of implementation. The word “easy” and the words “just works” does not belong here.

Donovan Preston has been actively working on the Xcode project template. It now uses Bob’s main.m and, as such, should work with any dynamic library or framework install of Python on OS X. Better yet, it does so automatically. Bob’s code also provides significantly better error handling during the startup phase of PyObjC based apps.

Finally, I am continuing to add PyObjC hacques to my Subversion repository. As well, ReSTedit continues to evolve and will be getting some pretty neat features fairly soon (I hope).

Overall, I have to say I’m incredibly impressed and proud of PyObjC. It isn’t mine, per se, but I do feel a bit of ownership from simply having been involved on the project for so long. It has come a long, long way since 1994 (I wish I knew the original date it came into existance — as it stands, I’m going to call WWDC the arbitrary 10 year anniversary of PyObjC).

Unfortunately, the CSS included with DocUtils does not produce documents that look like a decently formatted document.

In searching the web, I could not find anything resembling a set of CSS that would provide the basis for formatting whitepaper, reference or technical document style documents. I’m sure that if I looked closely enough at various random published papers, I could find some interesting CSS, but I really don’t want to just go and rip off someone else’s hard work.

Anyone know of a decent resource for CSS templates aimed at document formatting/publishing? Something other than the myriad of weblog templates? I don’t mind tweaking the various class declarations to fit the ReST structure, I just don’t want to start from scratch.

Speaking of hard work and weblog templates…

The current visual design of this weblog sucks. It is the generic default and it has zero character. I don’t like it, but I know that fixing it will suck many hours of my life away.

Why?

Because I know that CSS is amazingly powerful, but I don’t know how to harness that power without spending hours in a stupid text editor tweaking this, changing that, previewing the page, etc…

The various CSS editors I have tried don’t really seem to do WYSIWYG style editing. Then again, I haven’t tried any of the professional packages that claim to solve this problem.

CSS Zen Garden has a bunch of neat potential layouts. I might grab one, at some point. Yeah… right.