Master and Gh-Pages branches: keep your code and website in the same repo on GitHub
Code and website in one repository: 2015 did not give us “Back to the Future” hoverboards, but it gave us the ability to put our websites next to our code on GitHub. However, doing it so is still easier said than done. In theory, this should be a one-click operation. But in practice, you need to be a little patient, understand a few git concepts and type in a small book on the command-line. And of course, you can skip all this and fork the template I created in this post which lives at gh-pages-orphan-branch-template
Creating a repo for your code
As of June 2015, you still cannot do this on the command line for GitHub. You can do it on the website or if you are over zealous, you can use the API with a RESTful client. For now, let’s say you like the simpler approach and do it on the website. First login to your account, and then click on this link and create your repository:
You may have no problem programming Python in naked Emacs out of the box. But you may also know that with Emacs, there is always more. Just like the way Popeye would pop a can of spinach down his stomach to boost his act into a super human being’s, you can install a few tiny packages to transform Emacs into a super Python IDE. You won’t regret feeding these supplements to your Emacs, because once you set them up, you will never go back.
Elpy.el mode is the lead actor here, with jedi and rope are in the supporting roles. After installing these three packages, you get everything you wish for from a nice Python IDE: auto-complete, snippet expansion, syntax error highlighting, lint-like pep8 highlighting, indentation highlighting, simultaneous editing, easy code block shifting.
Elpy.el mode itself is a conglomerate of many other packages each of which brings yet another greatness onto the table.
iMovie Fail: Very slow importing, iMovie'11 and h264
iMovie sometimes takes a really really long time to import a relatively small clip encoded in “h264”. For example, a 50 second clip can take up to 10 minutes to import, while a similar clip of the same duration with an ”mpeg4” encoding would take only seconds. If you are going to import a medium size movie, you are ultimately out of luck. For a 20 minute clip, iMovie can take up to 6 hours.
After a little experimentation, the source of the problem materialized itself on my computer screen like a dew drop on a lotus leaf. “h264” is a interframe codec. It can use information from other frames to encode a certain frame. This potentially decreases the size of encoded of video while maintaining the quality. However, iMovie’11 cannot edit a file encoded in an interframe encoding: in order to edit a frame, there should be no inter dependency across other frames. iMovie should be able to manipulate a frame independent of others in a clip. Hence, iMovie reencodes the movie in "iCod" (a Quicktime format), and this takes a really long time while requiring a great deal of free drive space.
There is a neat solution to all this mess. You can re-encode your video in “h264” with exactly the same settings but by only turning off inter frame lookups. This process will create a video with visually no quality degradation and very little increase in the size. And, iMovie will be able to import your movie quickly.
“ffmpeg” command line tool enables you to use “h264” with no inter frame lookups. You need to use “-preset ultrafast” to accomplish this. In my example,
I have always been baffled by how badly iMovie is designed for errors. There is no explicit communication of what is happening and no course of action is ever offered should you run into a problem. Design world has known it better since 1980s than the Apple iMovie engineers know in 2010s.
iMovie Fail: "This clip cannot be optimized. Error -50"
iMovie sometimes simply cannot implement “fast forward” or “slow motion” on movie clips. This happens when you have a project in which you want to edit part of a movie to play at higher speeds such as 2x, 4x, etc (or at lower speeds for that matter). iMovie will tell you that it will need to optimize the clip before you can fast forward it, and then it will fail with a cryptic message: “This clip cannot be optimized. Error: -50”
It turns out that the problem is unambiguous, you just don’t have enough space on your drive for the optimization. If you have multiple drives, this would be the drive on which you created the “Event” when importing your clip.
Evidently, the remedy is simple, just create more space on your drive. But, what if you cannot do that? There is an alternative, you can decrease the size of your clip by reducing the “bitrate” using a command line tool called “ffmpeg”. Of course, you will have to do this before importing your movie to iMovie.
Here are the steps:
1. Failed to import with optimization on iMovie on “Import Movies…”
The movie I had was 1.65 Gigs, and I had 3.5 Gigs empty on my hard drive. For iMovie, this was just not enough for optimizing the video. It would fail without any error messages.
Since this failed, I unchecked the "Optimize video" and imported the movie without any optimization.
2. Failed to optimize the clip when trying to “Fast Forward”
When I tried to “fast forward” the clip, iMovie said that “the clip must be converted before its speed can be adjusted”. When I ok’ed that, it started “optimizing”, only to fail with the ever famous cryptic message: “This clip cannot be optimized. Error: -50”
3. What to do next?
I could not delete more files, so I decided to lower the bitrate of my video to decrease the size. “ffmpeg” can do this easily.
4. Install ffmpeg using MacPorts
I decided to use MacPorts to install “ffmpeg”. After Google’ing and installing the macports pkg, I opened "Terminal" and typed “sudo port install ffmpeg”. Voila, I had ffmpeg on my computer. You can use Command + Space to open the search bar on the top right, and type "Terminal" to find Terminal on your Mac.
5. The command line
First you have to change to the directory that the movie resides in. For my case, it is in "~/Document". I typed "cd ~/Documents". Then, I wanted to check what the movie is encoded in. I typed “ffmpeg -i MOVIE_FILENAME”. This will tell you the encoding, and the bitrate. My file was encoded in h264 with 8147k bitrate. I decided to halve the bitrate to 4000k. So I typed:
“-b:v 4000k” sets the output bitrate 4000k, while “-c:v h264” sets the encoder for video to be h264.
Since my movie's audio was encoded in AAC, ffmpeg asked me to add "-strict -2" to the command line. I did that.
When I first tried to use "-c:v h264", iMovie's optimization on ffmpeg's output would take forever and the optimized file would be many times larger than the original, which beats my purpose. After a bit tinkering, I found out that you need to disable h264's interframe reference by adding the setting to "-preset superfast"
6. Success!
The output file was only 800 Megs with not so much of a difference in quality, at least for my purposes. And iMovie successfully optimized the new video.
It comes as a surprise how horrific iMovie is designed for errors. On one hand iMovie is an immensely user-friendly tool for quick editing your movies. But on the other hand, it does not go much further in error handling than the long-gone DOS operating system with its own version of cryptic error messages. From a design perspective this is one of the no-no’s in Donald Norman’s monumental “Design of Everyday Things”. In his book, Norman gives a simple recipe for ‘how to do things wrong’ and I believe iMovie engineers followed these instructions really well, especially the fourth bullet point:
“Use idiosyncratic language or abbreviations. Use uninformative error messages”(1)
Once you finish editing your movie, I strongly recommend to add Norman’s book to your reading list. It is quick and very informative.
Links:
(1) Donald Norman, “Design of Everyday Things” (2002), page 179
Real-time Html Development on Emacs with Impatient Mode
With the rise of jsfiddle.com and jsbin.com, the power of seeing how your html, css and javascript look together on a browser instantly just as you type is now available to the masses. Their popularity is already proving the point: it is much faster and more robust to develop in this manner. However, they both fall short of being the preferred tool for large projects with multiple files.
Would it not be great if you can use Emacs in a similar fashion to jsfiddle, i.e. just as you type into Emacs, you would be able to see it on the browser how the website renders real-time.
As it turns out, Emacs already supports this, and it is called the “impatient plugin”. In order to get it working though, you have to set it up. The plugin will start a local web server, and will serve the document you are editing to the browsers on your computer continuously. And once you taste the feel of immediate feedback, I can tell you that you will never go back.
1. Modify your ~/.emacs file
You can use ‘package’ command to install the impatient mode. “package” already comes together with Emacs 2.4 (or newer). The other option is to install it from the source code, but that is not what I did. In order to run “package” correctly, you need to change your .emacs file (which resides under your home directory) and add these 3 lines.
2. Upgrade your Emacs (if you need to)
After you add the lines, you need to restart Emacs. When I did so, I got an error message: I did not have “package”. Turns out that I had an older version of Emacs, so I needed to upgrade it to the most recent version. I decided to use MacPorts. After Google’ing and installing the macports pkg, all I had to do was to type “sudo port install emacs”, and voila. I had Emacs 24.3 on my computer.
3. Install "impatient" mode with "package"
Once I started my new Emacs version, everything was working fine. You type M-x package-list-packages, and “package” downloads the list of packages from MELPA. Next, you have to search for Impatient (Ctrl+S Impatient), mark it with “I”, and hit “X” to download and install “impatient” mode.
4. Start httpd and impatient modes
At this point, you have MacPorts, a new Emacs version, “package” and “impatient mode”. You did go through all this trouble to finally start your awesome mode. First, run “httpd-start” mode by typing M-x httpd-start. And then, run “impatient mode” by typing M-x impatient.
5. Enjoy your realtime html rendering
Start a new html file: I named mine temp.html. Open up your browser and go to “http://localhost:8080/imp”. You should see a list of all the Emacs buffers you are editing. If you also called your file temp.html, click on it. Now, as you type in Emacs, the changes will show automatically on the browser real-time. If you like, you can open different browsers such as IE or Firefox and navigate to the same location. All browsers will change you type in to temp.html.
The real-time immediate feedback really improves the development cycles as well as speeding them up. Have fun with it!
And voila, here is the short video for instructions:
Links
MacPorts makes it really easy to install open source projects on your mac.
MELPA is a package archive for Emacs. If you install "package", you can easily manage your Emacs packages.
Impatient mode is the topic of this post. It is awesome.
