How to read PDF of Django Documentation on iPod

This is how I got a pdf of the latest Django Documentation onto my iPod. Of course this would work on your iPhone (iPad?) too. Everything shown here is don in Ubuntu. But the steps shouldn't be much different on other OS, be it Windows or Mac OS X, as long as you have root.

Step 1: get the source.
Good news, Django is Open Source! OK, that's kinda silly. But it's the fundamental reason all this is possible. Anyway, more useful info is that Django uses svn as its version control system and the Doc is part of the source in the repository. So let's check the source out:

svn co http://code.djangoproject.com/svn/django/trunk/

Caution: this is a fairly big repo so the check-out takes quite a bit of time!

Step 2: Compile the documentation
Here's the key to the next piece: Django uses a Python documentation generator called Sphinx to produce the Doc. Sphinx compiles reStructuredText into multiple formats, including HTML, CHM and LaTeX. And the source of the documentation is maintained in reStructuredText format. Our final goal here is to get a pdf, obviously we would generate that from LaTex. So, we need the sphinx-build script to compile the source into LaTeX. For Ubuntu users, the sphinx package in the official repo is called python-sphinx, install it:

sudo apt-get install python-sphinx

This will automatically install several related packages. When it's done, the compile should be smooth:

sphinx-build .../path/to/Doc/source/ .../path/to/the/latex/files

Step 3: Get the PDF
Now it's time to turn the LaTeX source code from last step into a PDF file. I'm a daily LaTeX user on Ubuntu, so for others there might be some additional latex-related packages to install from the official repo. But when I tried running pdflatex command, it complains that two style package were missing. I had to find them online: wrapfig.sty, titlesec.sty. According to Ubuntu Community Documentation, I did the following:

mkdir ~/texmf/tex/latex/titlesec
mv titlesec.sty ~/texmf/tex/latex/titlesec/
mkdir ~/texmf/tex/latex/wrapfig
mv wrapfig.sty ~/texmf/tex/latex/wrapfig/
texhash ~/texmf/

Basically, this creates folders for each package under the home path and informs tex of the added packages.

And now it should compile:

cd .../path/to/latex/files
pdflatex django.tex django.toc

When its done, you should find django.pdf lying in the folder, epic.

Step 4: Put the PDF into the iPod/iPhone(/iPad?)

There are tons of PDF reading apps in App Store. The one I've been using is a free app called Good Reader. It lets you read text, pics and PDF. The reason I'm using it is that it supports some really handy ways to transfer the files on to the mobile devices, including Dropbox.

If you haven't used Dropbox to sync files between your different devices I highly recommend that you follow this link to create a account and start using it immediately. For a starter, it's waaaay more convenient than emailing files as attachments. Anyway, once you get Dropbox folder syncing on your box, drop in djang.pdf there.

Open Good Read on your iPod/iPhone, go to Web Downloads -> Connect to Server -> Create New Connection to -> Dropbox. Fill in your username and password, hit "add". Go back to Connect to Server, click the the newly added account to navigate to the Dropbox folder, find django.pdf and download it.

And we are done, enjoy your mobile, beautiful copy of Django Documentation!

Make your evil iPod nano 3rd generation work with Linux

Well, for those who have a neutral attitude to iPod, and who use just Linux as personal operation system, I'm one of you. I think I don't need to say a lot about the reasons why I name this tiny MP3 player "evil".

For those who are not in the same situation as us, here's the story.

I bought this iPod nano 3rd gen from the official website, and happily received it before the tragedy started. I knew that it works with iTunes, but there's not a Linux version of that. I tried installing the newest iTunes with wine, however, the installation progress told me that I can't do this on linux. I download an old version and wine worked in installing it this time. Everything looked fine until I realized that this iTunes could do nothing but play music files. It didn't detect iPod nano 3rd gen at all.

Then I updated rhythmbox, which is installed by default in Ubuntu. Amazingly it recognized iPod and was able to transfer mp3 files into it. Although there were still some problem on mp3 tag editing, I did enjoyed few days driving iPod with Ubuntu. Later I learned that a newer version of Amarok could the samething.

But if that had been the ending, I wouldn't call it a tragedy!

The ending started on the day when I helped one of my friend install the newest iTunes on a Windows laptop. I plugged my iPod 3rd gen on the machine, iTunes found it, and told me that something is wrong with it, and then iTunes downloaded something sized around 50MB, redetected iPod, and I found all mp3 as well as all the game records disappeared in the player. Later, as you may expected, rhythmbox/Amarok stopped working on it. Every time after I tried to transfer something from Linux, the player just didn't display it. And iTunes on other machine would told me the same story that I needed to download/install that 50MB package.

Good job, Jobs!

But, wait.

VMware come to the rescue!

I'm not a Linux purist, nor am I a hard-drive-space-grubber. If you mind spending 5 GB on your hard drive to get the job done dirtily, don't waste time reading this post then. For the rest of you, let's start rocking!

Actually there's not much left to say. Here's all: Install VMware workstation -- Windows -- iTunes .

After that you'll get a virtual machine running on Linux, and a iTunes running in the virtual machine. Theoretically, it's possible to take advantage of the feature "Unity" in the new VMware workstation. Thus, iTunes would look just as a native application when working. But I haven't succeeded in doing that yet.


Here's a pic I found: Windows XP in VMware with Unity, on Linux Desktop.

My test is taken under:

OS: Linux Mint 4.0 (Ubuntu Based)

Laptop: Gateway T1616 (See how to drive everything out of box)
Desktop PC: Dell Dimension E510

It's really easy stuff.

1 Download VMware workstation, whose 6.5 Beta version is under testing. And don't forget the Serial Number given on the webpage.

2 Install VMware:

cd the_path_where_VMware_lies (e.g /home/home)
tar xzvf VMware-workstation-e.x.p-84113.i386.tar.gz
cd vmware-distrib
sudo ./vmware-install.pl

3 Imput the Serial Number. You will find the option in Help menu.

4 Build a new virtual machine. Once VMware starts, press the button "Creat a new virtual machine" under the Home tab. Leave everything as default on the first page, go next until the third page, where you choose the edition of windows which you are going to install. Name the system and choose its path on the next page. The next thing is to set the space for it. Let's give it 5GB (4 might be work ,too, but no guarantee here). Then you will be end up getting a virtual machine with 256MB memory, NAT network interface with the host system, and a share to all the DVD Rom,USB Controller,etc. It is actually just a (or more) file(s) on your linux machine. It won't have any infuence to the host system besides consuming some space on the hard drive.

5 Install Windows on the virtual machine. Put your installation disc into the DVD/CD ROM, press "Power on this virtual machine" on the tab of your newly built "PC". Then you will find yourself in regular Windows installation process. I didn't meet any difficulty during this step. VMware tells me that the Webcam/Sound/Wireless on Gateway T1616 all work for the virtual PC when Windows first starts.

6 Install VMware Tools. Make sure the virtual PC is on. Choose from menu VM-Install VMware Tools. The virtual machine will start a process installing a series of things. Just press next or OK if it stops anyhow. After this is done. You will find the virtual machine working faster. And you may also want to reset the resolution of the virtual screen.

7 Download iTunes, save the installation file in a certain place in the host system (linux), say, PATH_A.

8 Set the shared folder for the host PC and virtual PC. Poweroff the virtual PC first (Ctrl + Alt to get the mouse out of the virtual PC, for those who hasn't figured out). Press "Edit Virtual machine settings". Click the option tab, choose "Shared folders". Put "Always enabled" on the right. Press Add, put a name in Name, say, PATH_B. And put PATH_A in "Host Path". Press OK.

9 Install iTunes. Start the virtual machine. The Installation file for iTunes will be in the path "\\.host\Shared Folders\PATH_B".

10 Plug in iPod nano 3rd generation, the virtual machine should be able to detect it automatically, just as it happens in a real machine. Actually if you use the "Exlusive Mode", it feels exactly the same as if the system is on your host machine.


Since then, iPod nano 3rd generation, though still evil, is again available for me!