I remember one of the very first articles I wrote for my high school newspaper. It was a front-page piece, and I was anxious to see the edits after I submitted the story. When my piece came back completely red, I felt hurt. Whole sentences were crossed out. Word selections were questioned. Even how I structured the article had to change.

Fast-forward to this book, and I feel like I’m back at that high school newspaper. As my editors today give me feedback, I remind myself that every edit is provided to increase the quality of the book. When I submit a chapter, I’m convinced it’s ready to print. But when I get the edits back, I can see how much better it could be.

I still feel stung looking at the edits. I then remind myself that I’m not a high school kid anymore. Finishing this project means considering and reacting to each edit. I have to get past my feelings, and remember that revisions make the book better.

There won’t be a BLOG post next week, as I’ll be giving a presentation about Git at the New England Drupal Camp in Providence, Rhode Island on Saturday, November 1. Thanks for reading everyone!

Most books have some kind of dedication page, near the very front. It’s a bare page, with just a name or a sentence indicating who the book is dedicated to. Over the past few months I spent time thinking who I might dedicate this book to.

When I took up the matter with my wife, I learned that not all books have dedications. This led me to look at other Manning titles. Some of them had dedications, and some didn’t.

This hasn’t stopped me from thinking about the short list of people for this special page. One name that persistently pops up is Peter Winston. He is the CEO of ICS, a technology company specializing in UX design utilizing Qt and Motif. He was the first person to hire me out of college.

I remember that in my interview with him, he asked me what I wanted to be when I grew up. I hardly remember my answer now. What I do remember is that he’s the only person who ever asked me that question so directly.

I enjoyed my time with ICS. Because it was a start-up, I was able to see and participate in a lot of the non-technical functions of a software company (training, support, technical sales). ICS was a great first job, and I look back on it with great fondness. It’s a testament to Peter’s business acumen that ICS is still flourishing.

Thank you for reading!

I plan to elaborate on this topic over at least two parts, and in more detail on my Tech BLOG (http://tech.rickumali.com). For this post, I wanted to describe at a high level how I use Git for this book.

I work over three machines (described in Book Blog #14). Each of those machines has Git installed. For the book files, I created the initial repository on my Windows machine, then pushed it up to a private repository on Atlassian’s BitBucket. The repo now contains almost 400 files, over almost 800 commits.

Since I’m the only contributor to this repository, my Git workflow is very simple. Whenever I start work on the book, I first run git pull. This synchronizes my working directory with the latest changes. Whenever I finish work, I run git push. This uploads my changes to BitBucket for use the next day.

In between the git pull and git push, I’ll perform the standard git add/git commit to save my changes. Whenever I upload code to the publisher’s system (Nuxeo), I tag the repository. I use three tags so far: CODE, SUBMIT, and V (for the table of contents). I add a number to each tag (I’m up to SUBMIT #50, for example).

In future parts, I’ll discuss using Git with MS Word files, and issues I’ve run into with this simple workflow (yes…even just by myself, I’ve run into issues).

Thank You for reading!

One of the benefits of Git is that you can obtain the differences between commits. So how does this feature work with Microsoft Word? The short answer: it’s somewhat OK.

Git for Windows (http://msysgit.github.io/) came with a piece of software called antiword. This program takes an MS Word document (with the “.doc” extension), and extracts all of its text. Git Bash then has a configuration such that any use of git diff on a Word document would first be converted by antiword. Git then takes the difference between the extracted text. This nifty piece of configuration prevents Git from saying that it cannot obtain the difference between two binary files, but unfortunately, Git cannot apply a diff to a binary Word document.

I found the configuration interesting, but over the course of the writing, I found myself not needing it. If I need to compare files, I resort to Word’s “Compare Documents” tool. This allows me to compare any two Word documents. Further, Word’s venerable “Track Changes” feature records each change to the document. These changes can then be inspected by anyone else. It’s the equivalent of an editor’s red pen!

antiword does have its uses, however. For one thing, with the extracted text I can use command line tools to do analysis (word count and frequency). Also, having the chapters as text makes it very easy to search with the grep command line tool across all my files (each chapter is a separate Word document, so globally searching the book isn’t possible with Word). Finally: it’s faster to open a text file than a Word document, so if I just want to reread something, I usually will check the text file.

There won’t be a BLOG post next week, because of the Thanksgiving holiday (in the US). Thank You, everyone, for reading!

I’m the only person committing to my repository. However, despite working alone, I still can flub up my Git repo. This means that I sometimes forget to pull in work from the last time I pushed work (the workflow I described in Part 1 of this series).

Using the command git log --merges, I can see every time where this time happened. For the record, this happened 21 times (so far). Every merge means I forgot about work I did!

One of the first times this happened was when I performed a git commit --amend. This command allows you to update the latest commit of your current branch. However, I had already pushed my change to BitBucket, so when I pushed again, Git complained.

More typical though is that I make a change to a text file on my Linux machine, then make a change to an MS Word document on my PC machine. Git forces me to merge these two pieces of work. It’s amazing to me how quickly I can forget what I’ve already done.

It’s cool that Git can help me figure out what I was doing in another part of the repository. No work is forgotten if you are diligent about committing to your repository. A simple git log or (if need be) a more involved git checkout operation is enough to remind myself that Git can keep even a solo worker organized.

Thanks for reading!

One of the things that I do with the MS Word manuscript files is compare versions. However, in Git your working directory represents only one commit. How do I compare two commits at the same time? (I can get a rough comparison with git diff, but for this post, how can I use MS Word’s comparison tool, which wants an old version and a new version of a file?)

Clearly I need two copies of the MS Word file that I want to compare. I looked briefly at git diff, which somehow compares two files. The code for git diff is in C, with plenty of Git internals. I didn’t go down that path, and in the end, I did a possibly low-tech solution:

1

$ git clone gitbook gitbook-timetravel

This command created a clone of my repository named gitbook-timetravel. Since it’s a clone, I can access any commit. And because its origin remote is my active repo, I can update it at any time by doing a git pull.

With these two directories (gitbook and gitbook-timetravel), I can now compare files using Word. I use the gitbook-timetravel for the older version, leaving gitbook at the current revision.

A solution to a technical problem doesn’t have to be technical! Thanks for reading, everyone!

I always thought it would be interesting to examine the commits for my book using some data visualization. It would be a way to visualize all the work I’ve been doing. This thought simmered as a side project for many months, then in November I installed GitLab. Once I uploaded my book’s repository into GitLab, I had a few visualizations that were interesting.

Clearly I’m busier during the middle of the week than towards the end of the week. And it looks like Saturday might well be a considered a day off as far as working on the book goes.

This shows that this book is clearly an after-hours project. I do manage to sneak in a few commits during the business day, and I would have to guess those are notes or scripts as opposed to actual manuscript writing.

Both of these graphs intuitively make sense to me!

There won’t be a BLOG post next week, due to the Christmas holiday. Thanks for reading everyone!

Happy New Year 2015!

Over the past holiday week I’ve been putting together Chapter 19. There is one more chapter to write after that. Though the work isn’t finished yet (revisions, always revisions), I am beginning to feel lighter, now that I can see the finish line. I’m almost there.

I plan to keep writing these entries until the book enters production, which is actually sometime in February or March.

I still learn interesting Git bits. For example, just this week, I learned you can obtain the key paths from which Git obtains its executables and manual pages, by typing:

1
2

$ git --exec-path
$ git --man-path

Esoteric, to be sure, but helpful when debugging.

Thank You everyone for reading!

I attended high school at St. Peter’s Prep, a Jesuit preparatory high school in Jersey City, New Jersey, during the early 1980s. That was an exciting time at the Prep (as it was affectionately known). They were piloting a computer science class, the first ever for the school, and its computer lab was expanding from a small room to a classroom-sized lab. I was there during all of this.

Fr. David Stump, SJ, helped lead all this change. He was a teacher who ran the computer lab with much humor and generosity. Before the computer science class was formalized, he formed the computer club, where students could sign up to use Apple-compatible computers. During our allotted time, we learned BASIC, using computer-based learning programs.

He took a sabbatical to learn computer science at a California school. I remember being struck by that: a teacher going back to school. When he returned, he helped formalize the computer science program. In his class, we learned Pascal, and I remember being grateful because that was the computer language for my freshman year in college.

Fr. Stump was the first teacher to introduce me to algorithms, and he valued clarity in our coding. He offered extra assignments for interested people, and often kept the lab open after school. I took advantage of this. Those assignments were similar to the problems you might find on Project Euler, and they helped stretch my thinking.

The summer after I graduated, I helped him on some data entry at a nearby college. We did this work on a punch card system, and the hours I worked there felt like a bridge from the past to the present. Fr. Stump started my formal learning of computers, a journey that I’m very grateful to still be on.

Thank You for reading!

When I tell people about the book project, some of them say that this is my secret path to financial riches. I’m very quick to point out that as I write the book, it generates no income, and even when it does get printed, I’m going to still need a day job.

There are two components in my financial proceeds from this book: the advance and the royalty. In the case of the advance, the money is enough to buy a new couch. It’s a nice reward, but it is not anything that approaches what I make as a programmer. The royalty, on the other hand, is a wildcard. If enough people buy the book, it could become something significant. If no one buys it, I’ll get nothing.

My goal is that the book earns my advance, so that I can make royalties. After that threshold is reached, it’s all gravy. By my uncorroborated calculations, I think that 1500 copies of the book would have to be sold before that happens. I hope my book stays in Manning’s catalog a good long time.

Thank You for reading!