I’m getting ready to write my PhD thesis, and for some time now I’ve been gathering information on tools that can help me get from here to there. This first post is an attempt to organize this material, to write down my thoughts on the approach I plan to take for tackling the beast. This might not be exactly what I end up doing, so I’ll try to update the post on the changes or difficulties I’ve found along the way, to keep this in a sort of live document.
First of all I’m going to describe very briefly my current situation and the kind of workflow I’d like to pursue. The main topic of my thesis is medical image processing and most of the work I’ve done has been in MATLAB. That means, a considerable amount of math, a lot of images, a graph here and there, several diagrams, and a not-so-little amount of code. For the most part, the journal papers and conference proceedings I’ve published have been written in LaTeX. This is my starting point. So, down to business.
The obvious choice for writing (typesetting) my thesis is LaTeX. I plan to split the document in chapters by working with multiple files and using the
\input command. More information on LaTeX and thesis writing can be found at Using LaTeX to Write a PhD Thesis. When I used to work in Windows I used TeXnic Center along with the MikTeX distribution for typesetting my LaTeX documents. It’s a free open source software and it was great several years ago. Since I moved to the Mac platform I’ve tried several front-ends and editors until I settled for texmaker. This one is also open source and it meets most of my demands for a LaTeX editor. It has syntax highlighting, code completion, code folding, spell checker, document structure view, built-in PDF viewer, among other features. One feature I really like, is the
clean command, which allows you to erase the files (dvi, toc, aux…) generated by a LaTeX compilation (except the ps and pdf files).
This front-end for LaTeX has worked quite well for me. However, for some time now I’ve been looking to change to an editor that would have a rather simple interface, yet powerful enough for most of the things I do. The main reason is that when writing, I’d like to focus more on the writing, than on the formatting. I can always worry about formatting later. That’s one of the reasons that led me to do the actual writing of critical parts of a paper in something as simple as TextEdit or similar, and later paste it in texmaker. For instance I’d like to disable syntax highlighting, I’d like to be able to hard wrap my text, spell check, and things of this sort. I’ve been giving TeXShop and TeXWorks a try. They seem to fulfill most of my requirements. Nevertheless, I’ve recently been exploring another approach. It consists in using your favorite text editor on any given app with a global keyboard shortcut. This is done by a small app called QuickCursor. I’ve been using it with a really nice distraction free text editor called Byword. I highly recommend it for writing a draft or a simple paragraph, and it also has markdown support. I’m actually writing this post in Byword. What I actually do, is I’m working in any given app I highlight the paragraph I want to modify (or nothing if the document is empty) and I hit ctrl+cmd+B and the text is sent to Byword. I’ll do my writing in a distraction free environment in full screen if I want, hit cmd+s, cmd+w, and my text will appear back at the original app I was working on. So far this seems like an elegant, and time saving, solution to my problem. You can use any text editor you want, I also have a shortcut for TextWrangler. I’ve also considered using Textmate, however I’ve never been much convinced of paying around €45 for a text editor for programming, however powerful it may be, if you think otherwise, please leave a comment I may yet reconsider.
To sum up, write first worry about format later, because LaTeX let’s you do this somewhat effortlessly.
I also want to keep track the changes to my thesis and the optimal way of doing it is by using version control software. While most of the resources found on the web will tell you to go svn all the way, I think it’s mainly because it’s been around for quite a while. After a considerable online sleuthing, I’ve decided to go with git version control. Version control software is excellent for keeping revisions of my thesis, and then compare revisions or getting back to an old revision. Before I explored the version control paradigm, I used to keep my revisions in a simple yet unpractical way. One thing I used to do was duplicate a file and rename it to something like
myfile_old.tex, then I could do latexdiff and verify the changed I had made to the document and so on. The other thing was to comment out parts I wanted to remove, but that I still wanted to keep if I later changed my mind. For small documents this might not be much of problem, but for a thesis this does’t really work out.
This somewhat naïve approach also lacks an important element of revisions: proper documentation. This is where revision control software thrives, documenting changes can help you stay in perspective as to what you have done and how you have done it. It can also help to resume work; if you’ve been working on something else for a week or two, getting back to your document and to the idea you were developing is not an easy thing to do. With proper documentation of changes this could prove to be less difficult.
One clear advantage of git is that it is a distributed version control system, it’s easy to work on multiple machines and also working offline. Being able to commit to your repository when you’re offline is very useful, particularly since not having internet access could provide a distraction free environment making it much easier to write. However, keeping a sort of master repository in a server for backup is actually not a bad idea. What I plan to do is to have host this master repository in Dropbox. This way I’ll have the advantage of backup, with version control and avoiding the constant uploading of files by Dropbox every time I hit cmd-S.
Another advantage of version control I hadn’t mentioned is the ability to keep working on your thesis while sending revisions to your advisor. When you get back the advisor comments, you can directly compare to the specific revision you sent to your supervisor. If there are no conflicts you can accept all changes and continue to work. One could even experiment crazy changes, while knowing that one can easily get back to that stable version without trouble.
There are some best practices for the workflow I’ve roughly described, which for the purpose of completeness I’ll include here, but they were taken from this link.
- Define the directory structure for your thesis. You can change it later, and use git for tracking the changes. Having a good structure would make your life easier.
Work with multiple files (use include and/or input in LaTeX). You can split them by chapters or sections. This will make easier to track changes that involve specific parts of your thesis (e.g. git log content/introduction.tex).
Track only the files you are going to touch, not the ones auto-generated. Creating a proper .gitignore file will help you a lot (LaTeX generate plenty of working files).
As in programs, do micro-commits, that is: one commit per idea/feature/fix/activity.
- Every time you commit, write meaningful messages (high level) that explains what you were trying to achieve in every change. After a week you might not remember what you tried to accomplish.
- Keeping track of every activity/idea/fix [see (4) and (5)] could be very helpful to know how much you have done (using git log). You can write your advance report for your supervisor(s) based on git log. Even more, you can share the repository with your supervisor (using a web interface), and they can check whatever you have been doing in your thesis. For the next meeting, they will know what to expect (it will depend on how fond are your supervisors on following a RSS).
- Using git will be useful for keeping you in a good mood (sometimes you would feel you have not done too much, but having track of every change will help you to keep things in perspective).
- For every progress report you send, create a tag. For the next report, you can checkout both version and apply latexdiff . It will be useful for tracking changes between versions you submit for revision. This also will help you to check if you addressed the feedback you received for the previous report.
- Why is Git better than Subversion?
- Basics of Git Version Control
- Help me implement version control and offsite backups for my thesis
- A tour of git: the basics
- latexdiff and git