Editing a book with collaborators

Posted: January 22, 2012 in Uncategorized

So Alchemy Reigns is finished and the process of editing begins. In fact it has already started. With Emblem Divide, I used Open Office for both writing the book and for changes. With AR I decided to go down the path of using LaTeX. Why? Well, I wanted to store it in Git right? After writing the Git In The Trenches book and finding out actually awesome it was to have all this text in a version control system, I decided to do the same for AR too.

The problem with that is editing. I mean, with Open Office it’s easy. You just give the document to your proofer and they send it back and you go through the Accept/Reject merge process. There are no built in tools to do that with text, but there are some which function in a very similar way. So, all editors/proofers for AR have access to the Git repository and have their own branch that they commit changes into. I request that a commit only contains changes to one chapter file.

The files are all in plain text as they are written in the LaTeX language. It is practically identical to say html, or plain text and just has a little markup in there for quotes and extra line breaks or chapter titles. So each chapter is split up into a single file. When the proofer reads it, they makes changes to that one file and commit it.

I will generally then do a git fetch to pull their changes into my repository. Then I will fire up the gitk tool and mark each commit that contains revision with a tag. Generally I’ll use a letter to represent the authors name, followed by a number which represents the chapter that has been changed. See the screenshot below.

So in this case the first chapter has been edited by an author with a name beginning with r. Now that this is done, I use the power of Git to get me the version of the file that they have edited for comparison with my own.

git show r1:example.tex > example.tmp

Then finally I run meld like so to pull the two files side by side. The visualisation here is far superior to anything that the Accept/Reject changes one in Open Office can offer. Often the changes look so confusing in OO, but in Meld, they look perfect. I always put the editors changes on the left and mine on the right.

meld example.tmp example.tex

The I simply use the arrows down the middle column to either push my changes into their file (not that that is necessary, it just removes the change from sight), or pull their change into my own file. The thing I love about meld is you can also edit the file as you go. This means if you are not quite happy with their change, you can tweak it.

And that’s it. After finishing, I just delete the tmp files and commit into my Git repository. Cool huh?


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s