Self-publishing with CreateSpace

From time to time, somebody sends me a kind email saying that they only truly appreciated Git after encountering my Git guide. One such reader had already bought a few Git books, and he suggested I should therefore turn my website into a book.

I had idly thought about doing this, but why bother? Was: FREE, Now: $9.95!? However, the email made me realize that some seek information by buying books first, then look around online if they want more. Making a book out of my guide might be a good idea after all: I’m not trying to sell it to people who already know they can read it for free; rather, I’m aiming for those who might not otherwise find it until much later because they visit bookshops before search engines.

CreateSpace

Because the most renowned technical publishers already offered books on Git, I chose to self-publish on CreateSpace. Their tools are free, and they list your work on Amazon (who owns CreateSpace). I’d love to have bricks-and-mortar bookshops carry copies of the book too, but an Amazon listing should be enough for now.

In a brief search, I found controversy over CreateSpace ISBNs, but Richard Sutton’s post reassured me: firstly, for my book, the issues stemming from CreateSpace being the registered owner of the ISBN are irrelevant, and secondly, if you really want you can have an ISBN registered in your name (but you’ll have to buy it yourself).

The whole process is not quite free. After submitting your PDF file, you must order a proof copy. If you find errors, you submit a corrected PDF, and repeat. I made a stupid mistake the first time, so I went through this cycle twice and finished down about 16 bucks.

It’s not all bad though. I was surprisingly pleased to hold my book in my hand, as it felt like I had accomplished something. Also, in print form, the same old sentences become more authoritative and strangely convincing. Online, they look like stuff that some guy posted on some random website.

Preparing the book took much longer than expected. I had mentioned to a reader that I was considering making a book. I tried follow advice he gave me so it would look less amateurish. I cut a chapter and an appendix. I added an index. I renamed headings so they were more descriptive. I replaced all variables (e.g. "SHA1_HASH") in the command-line examples with values (e.g. "1b6d"). I selected a 6 inch by 9 inch form factor, which meant I had to shorten some lines to get them to fit. While doing all this, I found poorly spelled words, poorly worded paragraphs and poorly organized sections. I doubt I caught them all.

To avoid further delays, I used their Easy Cover Creator. Perhaps I’ll revisit this eventually, as I want a more spartan look: something like Kernighan and Ritchie’s "The C programming language". Or perhaps a sort of cheat sheet so the book would be useful even while shut.

I set the price to $9.95 USD, which means I get 2 bucks or so per sale. I considered a lower price, but I’ll be lucky to make my $16 back as it is! Still, it ought to be low enough that a buyer won’t be too annoyed when they find out the material is freely available on my homepage. (I would have linked to the free version from the book description, but this is forbidden.)

AsciiDoc, xsltproc, fop

I had some trouble with my tool chain that produces PDFs from text files. AsciiDoc produces a DocBook XML file out of the source text, which xsltproc turns into an XSL-FO file, which fop renders into a PDF. The design of the various formats probably have technical merit, but I found it difficult to figure out how to get what I wanted.

For example, I replaced variables with values because I could not italicize them easily with AsciiDoc. The only methods I discovered destroyed the natural beauty of the source text.

It seems the smaller the detail, the larger the effort required to tune it. Changing page sizes, font sizes and chapter heading styles was easy enough to figure out, but I still don’t know the right way to insert a blank page after the front matter so the first chapter starts on an odd page. I gave up editing some XSL file or other. Instead, I scripted a fragile search-and-replace on the XSL-FO output.

Nonetheless, I stand by my choices. There’s something appealing about source files which resemble old-school text files. Also, once the configuration nightmare is over, editing is simple: I can use any text editor, and the tool chain will automatically produce several HTML versions as well as a reasonable PDF for a book.

Shameless plug

I couldn’t possibly end this post without a link to my book: "Git Magic". It’s the most important book you’ll ever have, or my name is not Winston! Buy it now!

Notes on my notes on Git

I was mildly shocked, but honoured, to find that the venerable (or at least popular!) Wikipedia references my tutorial in its article on Git. Interestingly, the entry states that Git tips and tricks are 'popularly referred to as "magic"'. I named my guide Git Magic as a homage to Arthur C. Clarke's quip featured in the preface, and also because magic happens to be a hobby of mine. If the Wikipedia comment is true, then either my title was fortuitously appropriate, or I have unwittingly coined a phrase.

More pleasant surprises followed. The guide appeared on the first page when I Googled for "git" (though sadly much lower on Yahoo). I found several pages linking to mine, whose recommendations were probably responsible. Thanks to everyone who praised and promoted my site. [I do work for Google, but I have no control over the ranking of my content.]

It almost makes me feel guilty that my enthusiasm for maintaining the guide and for source control in general has waned. But this is inevitable because of Git's power and convenience: I use Git so frequently that it has faded into the background. Fascinating new commands have gradually transformed into boring old reflexes. Documenting them has as much appeal and utility to me as documenting my exploits with, say, the ls command, or sleeping and eating. Also, there are many more Git tutorials these days. But as long as my site ranks well, I'll attempt to keep it updated.

I use Google Analytics to keep an eye on site traffic as I lack access to the logs on the Stanford server hosting Git Magic. Some observations:

On 20080412, traffic to my site, which includes Git Magic, spiked at over 10000 hits. Previously few days saw more than 100 hits. The spike rapidly diminished to 100 to 200 hits per day until 20080805, when a larger spike of 16000 hits occurred. Again, this activity tapered off quickly to a few hundred hits per day until 20081102, which featured a small spike of over 3500 hits.

It seems the first and third spikes were caused by reddit.com, and the second spike was caused by an article at LWN.net.

Since mid-September 2007, roughly when the guide was released, the top three browsers were Firefox (67.43%), Safari (12.48%) and Internet Explorer (6%). The top three operating systems were Windows (36.53%), Linux (35.15%) and Macintosh (26.9%).

A handful of hits identified themselves as mobile devices: iPhone (489), iPod (113), SymbianOS (19), DangerHiptop (11), PalmOS (4), Android (3). Some intriguing curiosities: Playstation 3 (8), Nintendo Wii (6) and OS/2 (1).

During the last spike, the top three browsers were Firefox (69.42%), Safari (12.33%) and Chrome (5.15%), and the top three operating systems were Windows (49.45%), Macintosh (27.23%) and Linux (21.73%).

Git Magic

As I promised in a previous post, I'd write more on tricks one can perform with Git. I had so much to say that I made a site out of it: Git Magic.

It was also a great opportunity to practice my salesmanship, as can be seen from some of section titles: Ultimate Backups, Light-Speed Multitasking, Guerrilla Version Control, Uninterrupted Workflow. It was a probably a lot more fun to write than it is to read.

I'm hoping it will be useful to those new to version control, not just those new to Git. I took pains to explain the effects of Git branching. I had trouble understanding this from the official Git documentation, though it's probably better by now.

Git Revisited

To my consternation, the cogito package disappeared from Debian a few updates ago. I soon discovered the reason. Contrary to Linus Torvald's prognostications, raw Git is now (verson 1.5) a user-friendly version control system and does not need wrappers.

Still, I had to learn some new syntax. Luckily I was interested in learning about Git's more advanced features so I didn't mind. I was only previously using Git via Cogito in the same way one would use CVS or Subversion, except that it was faster, more robust and easier to use.

Now I finally understand why Git can do so much more. Better late than never!

101 Ways To Use Git

Git is the duct tape of version control. When I first started using it, I only cared about a very specific problem and ignored Git's design and internals. I focused only on remembering the Cogito commands I needed to type to do what I want, oblivious to how it worked its magic. Relatively poor documentation is partly to blame, but in truth, it is extremely difficult to convey Git's extraordinary versatility.

The book "Design Patterns" showcases the diverse problems that object-oriented design can elegantly solve. I wish there were an analgous Git book, instead of explaining Git fundamentals and leaving the reader to derive the implications, gave a set of recipes to accomplish a variety of tasks.

Below are a few examples of Git recipes such a book might contain.

Instant Backup

Just as in a computer game, when I'm about to attempt something drastic I like to save the current state, so I can go back and try again should things go awry.

git-init
git-add .
git-commit -m "Initial commit"

to take a snapshot of all files in the current directory.
Then if something goes wrong type

git-reset --hard

to go back to where you were. To save the state again, type git-commit -a. You'll have to type in a description of the current state.

One benefit to doing this instead of simply copying files is that with Git's hash chaining, you can tell if a backup gets corrupted.

Undo/Redo History

More generally, you can do the above, and every so often "save the game" by typing

git-commit -a -m "description of current state"

Note if you want to keep track of newly added files or forget about deleted files you'll need to first run "git-add" or "git-delete" accordingly.

Typing git-log shows you a list of recent commits, and their SHA1 hashes. Then typing

git-commit -a
git-revert SHA1_HASH

will restore the state to the commit with the given hash. You might like to use something like the following instead:

git-revert "@{10 minutes ago}"

You can undo the undo: type git-log and you'll see that the other commits you made are still there.

To take the computer game analogy again, git-revert is like loading a game and recording this fact as another saved game, and git-reset --hard is like loading an old save and deleting all saved games newer than the one just loaded.

Sync Files Between Computers

This is the reason I first used Git. I can make tarballs or use rsync to do backups. The problem was sometimes I'd edit on my laptop, other times on my desktop, and they may not have talked to each other in between.

Initialize a Git repository and commit your files as above on one machine. Then on the other:

git-clone git+ssh://other.computer/directory

to get a second copy. From now on,

git-commit -a
git-pull git+ssh://other.computer/directory

will pull in the state of the files on the other computer into the one you're working on. If you've recently made conflicting edits in the same file, Git will let you know and you should resolve them with another edit and commit.

If you have not committed any changes on the other computer, you may type

git-push git+ssh://other.computer/directory

to push the current state to the other computer. Next time you're there, run git-reset --hard or git-checkout HEAD . to update the files.

That Git does not do the last step automatically is good in case you were in the middle of some uncommitted changes.

Tune in next time...

I've barely scratched the surface, and so far haven't shown anything you can't do with older version control systems. Next time I'll show off problems that only the new generation of version control can solve.

Git and Cogito

Somehow, I have managed to avoid revision control systems until recently. I set it up for a typical reason: I wanted to be able to work on my thesis from different computers without worrying too much about keeping different copies in sync. Also, it's nice to be able to keep track of my progress. I don't expect to ever revert to an older version, but seeing a detailed log of changes makes me feel I've accomplished something.

Perhaps it's a good thing I put off learning about version control for so long. Back when I first thought about using it, CVS was the most popular open-source choice, Subversion was immature, and Linus Torvalds didn't use any system for the Linux kernel.

Now a new generation of source control tools has materialized, and are being improved rapidly. Development of the Linux kernel has benefitted ever since Linus started used revision control systems years ago.

So it seems it is a better time than ever to delve into version control. The old systems were plagued with various flaws and annoyances. The latest systems resolve these issues, but I wouldn't know. I never used the older systems so I have no idea what the problems were.

Things have gone smoothly for me with Cogito (basically some shell scripts based around Linus Torvalds' git tool). Even though it's designed to be a distributed source code management tool, it works well for one person editing a few files.

The only problem is that I can't easily host the repository on my Debian-stable server since git is too new, though Debian backports exist. I could just use rsync, but this method is deprecated and highly discouraged. [Also explained in this git tutorial; search for “rsync”.]