Film & TV goesZen

In a past post I thought about my workflow, especially about how I could refine it by adding a tool of some sort to handle the versioning of my documents and texts.

In computer programming, this problem is a daily task. That's why a look into this domain is very enlightening. Over decades, numerous people have developed, tuned and conceptualized how a single person or a group can safely write and modify complex texts (in essence, that's what programs are). One result of that research work is the concept of a central host, that stores the text material, and a client application that connects to this host, checks out versions, edits them and hands them back to the host. This approach can becompared to a library shelf, where "where authors keep successive revisions of one or more documents. The version control systems acts as the librarian between the author and the repository." Although many (any?) version control systems have their problems, we will jump in bravely and try to apply these tools to fictional writing in general and screenwriting in particular.

Subversion (SVN)

The most popular version control systems are CVS, and its successor Subversion (SVN). We will use the more advanced SVN here to control versions of our text. Interesting is that "Project Orange" the group of people that produced the open-source movie Elephants Dream (imdb) has also extensively used SVN on their project. As can be read here, they used SVN to coordinate their collaborative work on the script and initial layout, animatics and the following 3D blender files. Okay, as the overall concept of using SVN for a script is a bit geeky, I assume that if you are still reading, you might as well be able to follow my descriptions below:

SVN Installation

1. Get a snapshot of subversion here.
2. Download TortoiseSVN and install it. This will add a new set of commands to your right-click "context menus" on Explorer.
3. Open Explorer and navigate to a path where you would like to have your project folder reside.
4. Create two directories there: the actual project folder and a "repository folder" where SVN will store its data (locally! as we do not intend to use a fully-fledged SVN server here -from HED comes the hint to use ProSVN, an online service, as another solution. Haven't tried it myself, but it looks promising).
5. Right-click on your future /repository folder (not the folder where you will keep your texts) and select "TotoiseSVN" > "Create repository here...". Select "Native Filesystem(FSFS)" from the pop-up.
6. After the pop-up "Repository was successfully created" right-click again on /repository and select "TotoiseSVN" > "SVN Checkout...". A windows opens with two fields, the upper showing the location of your /repository folder (be sure the path is correct). The lower field, the "Checkout directory" should point to your /project folder, something like "file://<Drive>/path/to/your/<folder>". Press OK.
7. Your /project folder has a changed icon beneath it now. A green check mark, indicating that this folder is now versioned and up-to-date. Go and edit your files in there. Each new file you create ther has to be added into SVN tracking by right-clicking > "TotoiseSVN" > "Add...".
8. Edit the file.
9. After each cycle the folder icon will carry a red mark, indicating that you need to commit your changes into the repository. Do so by Right-clicking onto the folder "SVN Commit...", enter a comment and press "OK". SVN will then tell you that it raised revision from for example 0 to Revision: 1.

The layout of your repository/workfolder hierarchy might be different, see this for an alternate approach. And this for basic handling.
The way you use SVN strongly depends on what word processor you use for writing. As I am using the basic Microsoft Windows Editor for my current work and do only final formatting in Word or specialised software. SVN is quite easy to implement, but when using only Word it will be a bit less useful, as Word outputs binary files and SVN was designed for textual files.

If you happen to use the free word processor LaTeX, which uses a non-binary form of storing files, you can quite heavily integrate versioning using SVN into your workflow. Although the WikiBook "Collaborative Writing of LaTeX Documents" focuses on groups working together, I would recommend it as it explains quite well the basic concepts of SVN and further, how to integrate it with LaTeX. Also check out this blog post about how to set this up, with a more command-line orientated view of things.

Mercurial

Is SVN the best match? What about these new distributed revision control systems? Yes, it's true. The beasic concept behind CVS and thus also SVN is dated back twenty years. Especially larger projects suffer from a server-centric view of things. This led to the development of techniques for peer-to-peerversioning, the third generation of version control tools: distributed revision control systems. We look at free tools only, so the main candidates for this type of tools are: Git, Mercurial, Bazaar and Darcs. (see this or this for a comparison)
I like Mercurial and Bazaar, they seem to be simple and mature. Have a look at Mercurial's introductory docs to further understand what it is all about. One main aspect that is importan for our use as an aid in screenwriting is the fact that a distributed RCS stores a copy of the repository locally, so we can hack away everywehere without a need for an interrnet connection- these systems do not mandatorily rely on a central server, they "allow people to distribute their revision control data to where it’s actually needed".

Mercurial Installation

Ok, let's get our hands dirty (we'll use Windows here):

Prerequisite: I assume you have a directory where you store your files, for example your screenplay.txt file or screenplay.doc. This project folder is named "C:project" in our example. Then...

1. Download the mercurial.exe installer
2. Double-click the .exe and install the software (be sure to confirm "add hg to search path")
3. Navigate to your working directory: cd C:project
4. Init version control for all files currently in this directory: hg init - See how all mercurial commands start with hg, the chemical symbol for Mercury? So, all files in this directory are now under version control. Mercurial added a subdirectory to our dir called ".hg" where it stores its version data. Apart from messing with this dir, you can freely modify and edit files within this dir. If you add a new file, use hg add <filename> to add this new file to version control
5. Edit your screenplay
6. Commit your changes via: hg commit
7. Text editor fires up with title "hg-editor-<random-ID>". This is where you can add some comments about your latest change. Mercurial explains this to you in some lines that are already in thetexteditor but they will be regarded as comments as these lines begin with "HG:" So be sure to enter something, otherwise Mercurial will deny the commit with "transaction abort! rollback completed. Abort: empty commit message" - a little kick, so you document your edits. Select "File > Save".
8. That's it. The concept is that the C:project folder is always your working directory, representing the current state of your work. You can commit (store) your working directory into the Mercurial .hg folder via hg commit or you can recreate an earlier version of your work in that project's working directory for example with hg revert --rev 0 --all --no-backup, which reverts the dir's state to the initial version ("no-backup" states that your latest non-commited changes might get lost, so commit first!).

An interesting function is that Mercurial can act as a local webserver. That can make life a lot easier if you hate the command line. Enter hg server -n "My Repo" -p 80 will enable you to browse your repository with your webserver on http://localhost.

If you would like even more eyecandy or a TortoiseSVN-like GUI, try TortoiseHG.

Consult the online documentation, wiki and especially the tutorials for further help with Mercurial. Here is a tutorial for a setup on the Mac.
Coda

It might be helpful to read Agile Authoring about problems in and solutions for collaborative environments. If you are working alone, think about it: is the added weight of version control worth it? Many authors surely feel that this kind of tech tools is more in their way than helpful. But if you are the type of writer I am, who likes the warm and fuzzy (yet mostly useless) feeling of having that 'good draft No.23' still around, then version control can be a great win. So ask yourself: am I the "screenplay.doc", "screenplay_version2.doc", "screenplay_version3.doc" -type of guy or not. Answer the question, have a look at your project folder and see if you are fit for version control.