How To: Get started quickly using Subversion on Google Code (for Linux)

I had a little Python project I had been developing as a learning exercise and to take it (and myself) just a tad more serious, I decided that it needed project hosting! And version control! Like a real "program"... and stuff. And who knew, maybe people would sit up and pay attention and come begging to work with me and collaborate on this glorious, new... podcast client.

Google Code is - allegedly - a good option for beginners who want to get into project hosting, and though you have a choice between Mercurial and Subversion for version control, the idea seems to be to pick Subversion unless you've got specific large-scale needs.

Now, there's plenty of resources on using Google Code and Subversion, and there's no shortage of resources on Subversion and Linux, either. However, the Google Code stuff tends to refer you to TortoiseSVN (a Windows program) and the Linux-specific articles talk mostly about local repositories (which Google Code is not). So, to fill the gap, here's a quickstart intro to using Subversion with Google Code project hosting on a Linux machine to start up your new project - for those too impatient to properly understand Subversion before seeing their project online.

This step-by-step-guide assumes, that you've got a) a programming project in some sate of readiness (well, as long as you've got some source code files to put up....) b) a Google Code project hosting account, and c) a working knowledge of the command line.

Disclaimer: This does not in any way replace actually getting to know Subversion, e.g by reading the first chapter or two of this well-written and easily accessible introduction to Subversion, which will introduce you to things like conflicts and locks and all that cr*p that you really needn't worry about at this stage. This is just to get you started quickly and - hopefully - painlesslessly, and show you that this stuff isn't really all that complicated.

Step 1: Check to see if you've got Subversion installed.

Well, have you? Apt-go-get-it-yourself or whatever your package manager does. The package is usually just called 'subversion' (well it is in Ubuntu...) It should supply the basic command line tool called 'svn'.

Step 2: Download the source code from your Google Code repository.

But, but, but... I know, that seems illogical, seeing how that one is empty, right? Nevertheless, in order to establish the link and the hierarchy, you first need to pretend to want the version from Google Code. To download is called to 'checkout' and what it does is to establish a 'working copy' on your hard disk. Google kindly supplies you with the initial command needed:

# Project members authenticate over HTTPS to allow committing changes.
svn checkout https://poca.googlecode.com/svn/trunk/ poca --username madchine

When prompted, enter your generated googlecode.com password.

What running this command (notice the prefacing 'svn' - this is the subversion tool; anything that follows is considered subversion commands) would accomplish is to checkout the current version ('revision') of my project and put the files into a local directory named 'poca'.

This local directory is your 'working copy'. It should contain nothing. Do not choose any existing project folder as that just invites confusion. I can obviously choose whatever local directory I want and Subversion will create it for me if it does not exist. How about /home/user/svn/project-name? Do not be alarmed that you're not asked for your password - this will only happen when you try to upload your changes.

You should now have an empty project directory. Empty? Well, not quite. A hidden directory called .svn is placed inside it to keep track of things. But nevermind that for now...

Step 3: Copy your local files into the project directory.

Go ahead, this is pretty straight-forward. Supposing you've been writing on some files in /home/user/python/yaic (yet-another-itunes-clone, anybody?) and your new project directory created in the last step is /home/user/svn/yaic, just do an ordinary copy of all the files and subdirectories from the old directory to the new one.

In order for Subversion to know about these new files in your working copy and that you mean for them to be added to the project's repository, you well... 'add' them. With the project directory as the working directory, do:

svn add *

(or list all the files in the directory individually or whatever...)

Subversion should list all your files preceded by an 'A' - for 'added'.

Step 4: Upload your new files to the Google Code repository.

As in the previous command (add), be sure that you're inside the project directory for this one. To upload is called to 'commit'. Seeing as you supplied Subversion with the Google Code URL when you checkout'ed the original code, you do not need to reenter that information - it is saved in the hidden directory in your 'working copy' project folder. To upload all the files you've told Subversion you wished to see 'added' to the repository, the following line should do:

svn commit --message "Initial upload." --username madchine --password 1234567890AB

Since no specific files are mentioned, all in the working copy are implied. The --message switch indicates a comment for the revision we're committing (one way or the other, a comment must be supplied for the commit to be successful). The --username and --password switches are self-explanatory - use the ones Google have supplied you with.

If it worked Subversion should have spit something like this out:

Adding fileA.txt
Adding mainFile.py
Adding otherFile.py
Transmitting file data ...
Committed revision 2.

"Committed revision 2." Congrats, you've uploaded a new revision - really the first, but Google counts the empty, initial version as revision 1.

Step 5: Point your web browser to http://code.google.com/p/[NAME-OF-PROJECT]/source/browse/#svn/trunk and check to see that your files are there. Slap yourself on the back.

Step 6: Now, start reading a proper introduction.

Such as this one.

How To: Edit Mac OS .pages documents in Linux

Seeing as I had to spend an hour or two, figuring this out, I thought other might profit from my experience, at least with sufficient google-foo...

Pages is, according to a Machead friend of mine, "the Word of Mac OS X". Yuk.... Oh well, there is no arguing with these people. I had promised to help out with some grammar editing and translation on a document for another Mac user friend. My first step was to try OpenOffice but it does not appear to have an import/export filter for the format and neither Gmail nor Google Documents seemed to recognise it either.

I was about to give up and suggest using some kind of open format or, if all else failed, some old, ghastly incarnation of .doc, when I noticed that pcmanfm, my file manager, had classified the files as 'zip archives'. Aha! It turns out that the file format is nothing more than a zip archive, containing an XML file, whatever images have been added to the document, and a Quicklook folder, with a low quality PDF version and a JPEG thumbnail.

What follows is a step-by-step guide to my patented hi-tech-lo-fi approach to editing .pages files on a linux box. The outline is that you need to unzip the archive, make a few small adjustments using trusted old unix/GNU tools, like sed, cat, and tr, and can then easily edit the file, using a text editor. Creating a new pages file, is simply putting the process in reverse.

1. Create a folder in which to unpack the archive or you'll have a small tar bomb on your hands. Using pcmanfm I just throw a copy of the archive into the new folder, choose extract here, and delete the archive copy.
2. As mentioned above, the contents are very easy to understand:
   
   
   • The index.xml file is the main content file. This is the one to edit.
   
   
   • buildVersionHistory.plist is a file containing the version of the file format. I tried mailing an early example of my editing efforts to Machead friend 1 based on a file from Machead friend 2. The former got told by his copy of Pages that he needed to upgrade, so obviously the format has a version history.
   
   
   • The QuickLook folder contains a thumbnail image, supposedly for the file open dialog, and a low quality PDF file (any images included are extremely blurry)
   • Whatever images have been added to the document, will be in the 'root' folder, probably in TIFF format.
     


3. The index.xml file can be 'hand edited' as it is, but the entire file is one lone line - maybe because it saves a few kilobytes? - so we'll need to make som adjustments. Incidentally, opening the XML file as it was in any XML knowledgeable text editor consumed practically all of my 2.0 GHz. It was like editing in treacle. You will probably need to and want to insert some newlines in order to make it easier on yourself. Note that 'text wrapping' will not do it - the CPU wll still be struggling to handle this one huge line. This we can do with one line of sed. In the directory containing the archive files, do:
   
   sed -i 's,>,>\n,g' index.xml
   
   This will insert a line break after each tag ending and make the XML file a lot easier on the eyes and CPU.


4. Now the XML file is ready for editing. Open it in you favorite text editor, preferably something with the ability to colour code XML. I recommend Geany, a light-weight but very capable IDE, or medit, an all-purpose text editor, both of them GTK2. The first many lines will be incomprehensible formatting codes. The actual text is at the bottom fo the file. Try searching for an easy identifiable word or expression to find it. You can use the PDF file in the QuickLook folder as a visual guide to get some WYSIWYG help while editing. Be careful not to delete any XML tags - if the XML document is not well-formed and valid, chances are Pages won't open it. A few tags can however be easily identified and manipulated.
   
   [sf:br/]
   
   for instance is obviously a line break, and
   
   [sf:p style=""][/sf:p]
   
   is a paragraph. (note that i have switched ['s for <'s and so on in order to circumvent Blogger's moronic editor's sabotage). Still, since you cannot know if anything is broken before the Machead in question opens the file, it might be better to leave well enough alone.


5. Once you're done editing, save and close. Now, we need to reverse the sed effect. sed is very good at inserting line breaks but due to its line editor nature, not very good at removing them. So I resorted to tr:
   
   cat index.xml | tr -d '\n' > index.xml.new
   
   which will remove all the line break sed inserted. One line break however should be kept: the one after the xml version declaration ([?xml version="1.0"?]), so open index.xml.new and add it manually. Then
   
   mv index.xml.new index.xml
   
   
6. Now, we just need to re-zip the whole thing. I prefer using pcmanfm's option: just select the entire content of the directory (index.xml, QuickLook, etc.), right click, choose 'compress', and selct the 'zip' format. The same option is probably built into most file managers. The corresponding command line is 'zip -r *' but I don't know how to control what name is given to the archive or where it is put. Once your archive is created, rename it from .zip to .pages and email it back to the Machead. That's it, you're done.

I hope this has proven useful to you (and that I haven't just missed the correct option in OOo, in which case this is just stupid geekery for the sake of geekery...)