Daring Fireball, as ever, with the wry commentary:

It strikes me as an odd coincidence that two serious Subversion clients would debut at a time when many developers are starting to switch away from Subversion to distributed revision control systems such as Git and Mercurial.

I have been meaning for some time now to blog about ManOpen, a GUI man page viewer originally developed on NEXT, and another example of a hybrid app. However, Brett Terpstra over at TUAW has beaten me to it, in a post comparing a number of GUI man page viewers (including plugins that allow the viewing of man pages in your browser).

In the comments, someone mentions piping man pages to AquaLess, a GUI text pager for OS X. Not nearly as full featured as ManOpen, but AquaLess is another cool hybrid app. So make sure to check out the comments to Brett’s post for more ideas about viewing man pages outside of the confines of the terminal.

The problem is not, or not solely, aesthetic—the coloring degrades readability. Fortunately, the default color settings can be overidden with the help of the color package. I wanted the difference to be discernable but not distracting. So I opted for a shade of gray:

Unfortunately color selection in LaTeX is tedious and requires knowledge of the LaTeX color system that I lack. Fortunately, for OS X users, Maarten Sneep has written a nice color picker, LaTeXColorSelector. Using the operating system’s color selection, it outputs LaTeX color definitions in rgb and cmyk. A nice hybrid app.

Subversion is a great command line utility waiting for decent GUI. While the GUI’s supplanting the command line represents the triumph of the Image over the Word, the GUI has its place—even in text editing. With respect to subversion, there’s cognitive utility in being able to visualize the structure of your repository or working copy. While there are GUI front ends to subversion, none are perfect. While on OS X svnX works reasonably well, a compelling solution to graphically representing subversion repositories and working copies has yet to be found. The ideal hybrid app has yet to be written. (The situation is not unlike MP3 players before the iPod.) Fortunately, competition is good, and competition is emerging on the Mac platform. Versions promises a clean look and simple approach without compromising on functionality. A collaboration between João Pavão and madebysofa.com, the beta of Versions is soon ready for a private trial. You can sign up for the private beta at versionsapp.com.

In my first post, I reported my discovery that a lot of tools that programmers use are, in fact, readily adaptable to the task of writing. In a previous post I discussed diff programs—programs for comparing differences between text files. In this post, I will be discussing version control.

Programmers and writers face at least one common problem. In writing a complex program, programmers need to track small changes over time. In writing a complex document, writers need to track small changes over time. Programmers, being programmers, have written software to meet this particular need, software that can meet the writer’s corresponding need.

There are a variety of version control systems currently available, but I will be talking about subversion, a popular open source replacement for CVS. Subversion tracks changes to a directory, saving the differences in a database. Wish you hadn’t deleted that paragraph and somehow didn’t save it in the ad hoc versions of the paper you created? With subversion it is just a:

svn cat

away.

This post will be covering installing subverion on Mac OS X. Subsequent posts will cover usage, and integration with the diff program of your choice.

Installation:

STEP ONE: Martin Ott of Coding Monkeys has helpfully provided a binary for OS X. (One cool feature of the OS X version is its keychain integration.) Download the Subversion.pkg.

STEP TWO: Unzip the subversion.pkg, click the pkg-installer and follow the instructions to install Subversion.

STEP THREE: OK, let’s test it out. Open the Terminal (located in /Applications/Utilities), and type:

svn help 

If successfully installed, you should see a helpful usage message. If not, then chances are that subversion is not in your path. (Don’t worry if you do not know what this means.) To add the relevant path do the following: Type:

cd

in Terminal and hit return to navigate to your home directory. Type:

ls -a 

and hit return to see the contents of your home directory (including the files beginning with a ‘.’ normally hidden from the Finder). If a file called ‘.profile’ exists open it up in your favorite text editor. If it doesn’t exist, create it. Now just add the following line:

export PATH=$PATH:/usr/local/bin

Save .profile and type

source .profile

and hit return.

svn help

should now return the help message.

STEP FOUR: First a bit of terminology. A subversion repository is where all your files are stored. Your working copy is a local copy of its contents where changes are made. If you are happy with them, you commit them to the repository. It is possible to have a local repository on your machine, but having your repository on a server allows for some interesting possibilities (such as syncing your files on multiple machines). OpenSVN is a free subversion server. It worked well for me. (Though now mine is on TextDrive which isn’t free.) A comprehensive list of subversion servers can be found on this page of the subversion website. If you are using OpenSVN, click on the link called ‘Create a New Project’ and follow the instructions.

STEP FIVE: Subversion can be managed on the command line. You should take the time to learn how to do so. However, like diff programs (and arguably text editing), there’s a point to using a GUI environment. There are several GUI front ends for subversion. None of the interfaces are ideal. (The killer GUI front end for subversion has yet to be written.) However, svnX is by far the best I have seen on OS X. And it is free. Download it here.

STEP SIX: When you open up svnX you will see two windows. In the window entitled ‘Repositories’, add the url and login name and password from your subversion server.

STEP SEVEN: OK, you are in the home stretch now. You have installed subversion, created a subversion repository on a subversion server, and have a GUI program to manage your subversion repository and working copy. Now all that you have to do is import your project directory into your subversion repository. Once more to the Terminal. (After this, most everything can be handled through svnX.) Type:

svn import -m "import message" /path/to/your/project/directory /url/of/your/repository

(making the appropriate substitutions for the import message and path and url) and hit return.

STEP EIGHT: Now we need to create the working copy. Move your project directory to the Trash. (Don’t worry, you don’t have to empty the trash just yet.) In svnX, click on the name of your repository in the repository window. This will open a new window. Select root and click on ‘svn checkout’. In the dialogue window, select where you want your working copy to live and click ‘open’. Now in the window entitled ‘Working Copies’ add the path of the working copy you just created and the login information from the subversion server.

Congratulations! You are now set up. Subsequent posts will describe usage and integrating with the diff tool of your choice. I you can’t wait check out the tutorial at O’REILLY macdevcenter.com and the subversion book.

As our sample text we will use the following passage from Moby Dick (available at Project Gutenberg):

While Daggoo and Queequeg were stopping the strained planks; and as the whale swimming out from them, turned, and showed one entire flank as he shot by them again; at that moment a quick cry went up. Lashed round and round to the fish’s back; pinioned in the turns upon turns in which, during the past night, the whale had reeled the involutions of the lines around him, the half torn body of the Parsee was seen; his sable raiment frayed to shreds; his distended eyes turned full upon old Ahab.

The harpoon dropped from his hand.

and this slightly modified version:

While Dagoo and Queequeg were stopping the strained planks; and as the whale swimming out from them, turned, and showed one entir flank as he shot by them again; at that moment a quick crie went up. Lashed round and round to the fish’s back; pinioned in the turns upon turns in which, during the past night, the whale had reeled the involutions of the lines around him, the half torn body of the Parsee was seen; his sable raiment frayed to shreds; his distended eyes turned full upon old Ahab.

The harpoon dropped from his hand.

I saved these as text files called, respectively, passageone.txt and passagetwo.txt.

First up is GNU diff. See the man page for diff’s options. An extensive manual is provided by Texinfo. Simply type:

info diff

in the terminal. The command:

diff passageone.txt passagetwo.txt

yields the following output:

1c1
< While Daggoo and Queequeg were stopping the strained planks; and as the whale swimming out from them, turned, and showed one entire flank as he shot by them again; at that moment a quick cry went up. Lashed round and round to the fish's back; pinioned in the turns upon turns in which, during the past night, the whale had reeled the involutions of the lines around him, the half torn body of the Parsee was seen; his sable raiment frayed to shreds; his distended eyes turned full upon old Ahab. 
---
> While Dagoo and Queequeg were stopping the strained planks; and as the whale swimming out from them, turned, and showed one entir flank as he shot by them again; at that moment a quick crie went up. Lashed round and round to the fish's back; pinioned in the turns upon turns in which, during the past night, the whale had reeled the involutions of the lines around him, the half torn body of the Parsee was seen; his sable raiment frayed to shreds; his distended eyes turned full upon old Ahab. 
3c3
<    The harpoon dropped from his hand.
---
> The harpoon dropped from his hand.
\ No newline at end of file

One limitation, from the writer’s perspective is immediately apparent. GNU diff compares line differences. But as paragraphs are long lines, multiple differences within a paragraph are not displayed. What would be more useful is a representation of word differences.

Fortunately, there is a frontend for GNU diff that displays word differences, wdiff. wdiff is available from fink and MacPorts. The command:

wdiff passageone.txt passagetwo.txt

yields the following output:

While [-Daggoo-] {+Dagoo+} and Queequeg were stopping the strained planks; and as the whale swimming out from them, turned, and showed one [-entire-] {+entir+} flank as he shot by them again; at that moment a quick [-cry-] {+crie+} went up. Lashed round and round to the fish's back; pinioned in the turns upon turns in which, during the past night, the whale had reeled the involutions of the lines around him, the half torn body of the Parsee was seen; his sable raiment frayed to shreds; his distended eyes turned full upon old Ahab. 

The harpoon dropped from his hand.

[-foo-] is a word that occurs in passageone.txt and {+foo+} is a word that occurs in passagetwo.txt.

In an earlier post I observed that the GUI has its place even in the manipulation of text. If you install the developer tools on Mac OS X, one gem that you will get is FileMerge, a descendant of NEXTSTEP’s Merge utility. FileMerge provides a visual comparison of text files. FileMerge can be invoked from the command line with opendiff. A screenshot of the output is below:

Notice, FileMerge, like GNU diff, captures line differences, but, like wdiff, it also highlights word differences.

FileMerge is Apple software, so it is simple and easy to use. If you need a more powerful GUI diff program, kdiff3 might be for you. Here’s a screenshot:

Another hybrid application from Apple is Activity Monitor:

Of course a lot of the information displayed by Activity Monitor can be accessed by top in the terminal, but there’s more besides. In a How To article in About This Particular MacIntosh Sylester Roque begins the first part of a review of the Activity Monitor. Check it out to get a sense of the potential of this underappreciated utility.

While on the topic of ATPM, Ted Goranson in his column about outliners (text editors that allow multiple views of a document based on its logical structure), will be writing about writing environments next month. If you are not yet familiar with this fascinating column, the archives are a rewarding read.