Michael McClimon

RSS

My dissertation setup

August 21, 2015

I spent all summer writing my dissertation (a boring summer, but productive). Over the course of the year or so I spent writing the thing, I developed a pretty extensive workflow for dealing with it. I always enjoy reading about people’s own personal setups (my favorite sites for this are The Setup and Lifehacker’s How I Work series), so I figured I’d write my own.

Motivating factors

The primary motivator for writing the thing is that I hate Microsoft Word. I can’t stand that it uses a whole bunch of memory, drags my computer to the ground, and occasionally crashes at random. Add to that the fact that the formatting is a huge pain to get right and that my dissertation has a lot of mathematical symbols in it, I knew from the start that writing in Word was a no-go. I also realize that these problems aren’t really unique to Word, but to word processors in general, so something like Pages or LibreOffice was also out.

Since I made a living for a while as a computer programmer, I really like doing things in text editors, and I wanted my dissertation to be in plain text. As it happens, there is a file format initially designed for mathematical writing that uses plain text as a format: LaTeX to the rescue! (More on this in a bit.) Plain text means that I can also store everything in git, which is really convenient for keeping track of things as it changes over time. (The dissertation is in a repository on Github, but for now it’s a private repository. Once it’s finished for good, I’ll probably open it up.)

Hardware

The first question usually on these setup-type posts is along the lines of “What hardware do you use?” After a stint of using Linux on my laptop, I’m back to all Apple products. I type on a mechanical keyboard, and use a Casio keyboard to input things into Finale.

Software

This is where things get more interesting. The basic process is this: the text is written in LaTeX with a text editor, which is processed automatically by LaTeX and when I save, the generated PDF gets updated, which I then look at with Skim.

Emacs

The central portion of all this is the text editor. I’ve written before how I am a hardcore Vim user, but the built-in LaTeX support in Emacs made me switch. I know, I know. GNU Emacs is now my main text editor, though I use vim keybindings via the excellent Evil package. It turns out that what I like most about vim is modal editing, and the Evil vim emulation is really good. Once I trained myself to use M-x (which I’ve rebound to C-x C-m to keep my pinky from going all over the place) instead of Vim’s command line, the transition really wasn’t so bad. (You can see my dotfiles to see my whole Emacs setup.)

The reason I switched to Emacs is that the AUCTeX and RefTeX packages are extremely useful. The dissertation is a complex document with lots of examples and references, and it’s really useful to be able to pull up an outline and jump to a particular section, or to pop up a list of examples when I want to reference one in the text. I tried for a while to use the Vim AucTeX emulation, but it didn’t really work the way I wanted it to.

There are also a bunch of other features of Emacs that make it nice for writing long-form things. I use flyspell-mode for catching dumb typos, Outline minor mode for hiding and showing sections I don’t want to look at, and abbrev-mode as a poor man’s autocorrect. (In general, I don’t like autocorrect, but when I’m typing quickly I almost never type the words “transformation,” “substitution,” or “separate” properly on the first try.)

LaTeX

LaTeX is really annoying, and I’m not sure I’d recommend it to most normal people unless they have something of a masochistic streak in them. That said, it can produce (with lots and lots of coaxing) really nice PDF output. As it happens, fiddling with LaTeX settings turned out to be a really nice procrastination tool, since it’s like work, but isn’t work.

I won’t go into all of the nitty-gritty details (though I’m happy to if you email me), invaluable packages for LaTeX included these (all are in the standard TeX Live distribution):

  • fontspec/mathspec – non-hideous fonts
  • sepfootnotes – to keep footnotes in separate files from the chapter texts
  • biblatex-chicago – Chicago-style references via BibTeX. I cannot emphasize enough how much time this saved me.
  • hyperref – automagic referencing of examples, page numbers, and so on
  • xstring – really useful for creating macros. The most useful one I wrote is one that automatically substitutes # and s characters for flats and sharps, so that I could write \h{Fs7b9} and a nicely-formatted chord symbol for “F#m7b9” would come out.

There are lots of others for really minor things; once I put the dissertation on Github you can troll through my style file if you like.

LaTeX compilation was done via the latexmk tool (also included in TeXLive). I have a very simple Makefile, so that I can type make watch and this process sits there waiting for a file to change, and when it does, the whole thing is run through XeLaTeX as many times as needed. I use the PDF app Skim because it automatically refreshes when the PDF file changes, without needing to switch mouse focus to the app.

Other miscellaneous software

For musical examples, I use Finale 2011. I don’t particularly like Finale, and it often does things which are completely incomprehensible to me (that’s a rant for another post). I use the 4-year-old version because I don’t pay the Finale upgrade tax every year, though once the dissertation is over I’ll probably bite the bullet and do it again. I use Finale mostly because I know it backwards and forwards. From what I can tell, all notation software is terrible, so I see no reason to spend a bunch of time learning a new one.

The other examples (and any annotations to musical examples) are done in Adobe Illustrator. I have tried using other programs so that I don’t have to pay for Illustrator once my magical IU subscription runs out, but Illustrator really is the best I’ve found. This is also a situation like Finale: I spent a lot of time learning Illustrator, and I don’t want to invest a lot more time learning something else that’s either less good or only marginally better.

All of the finished examples are saved as PDF files in a Git submodule inside the main dissertation repository. This lets me keep the giant binary files (which git doesn’t handle well) in source control, but doesn’t bog down the main repo. It also lets me pin a particular version of the examples to a particular version of the text, which is pretty handy.

When I’m doing transcriptions, I like to use Audacity. I don’t use anything close to all of its features; it’s mostly useful because I can set it to start playing at a particular point over and over again. I prefer to transcribe at full speed (though Audacity can slow things down when I need to), so normally what I do is set the cursor at the beginning of a bar, then bang on the space bar to hear that measure 5–6 times before writing it down. Needless to say, this is really annoying for anyone that has to share an office with me (Hi Carolyn!), so this is normally done with my computer and keyboard plugged into a mixer and running into my headphones.

Dream setup

This setup works pretty well for me, but it does have a lot of moving parts. In a perfect world, some software would make it better.

  • I wish Git dealt with large binary files better. I know there are workarounds (like git annex), but they always seem clunky to me. I’ve heard that Perforce is really good at dealing with them, but that’s not distributed and there are (as far as I know) no free/cheap hosting options.

  • I really want a good tabbed PDF reader. I usually wind up with a bunch of PDFs open (the dissertation, a handful of articles, LaTeX documentation…), and it’s annoying to have them all in separate windows. I use MightyPDF if I’m just reading, since it does have tabs, but it has almost no other features. If Skim had tabbed viewing, that would be a dream.

  • I have long wanted a music notation software that has no concept of playback. I don’t need the playback, and if the software didn’t either it would let you do a bunch of things Finale and Sibelius don’t. I often want to put barlines in non-regular locations (if examples start and stop in the middle of bars), and to do that I have to go in and fiddle with the time signatures, then hide the fake time signature. I really want to be able to say “put a barline here” and have the software figure it out; if it didn’t have to play anything back it would be a lot easier.

  • Notation software that also has vector drawing tools would be amazing. Then I could just use that, without having to export Finale to EPS, then import EPS to Illustrator. There’s essentially no market for this, but if it were decent, every music theorist on the planet would buy it.

  • I also wouldn’t mind a pair of giant retina monitors and a computer with obscene amounts of memory, but my little iMac usually does ok.

This setup probably won’t work for anybody else, but it works ok for me. The hard part, of course, is actually putting the words into the system.

Diatonic Spaces in Jazz: A Transformational Approach (materials)

March 10, 2015

(Again, I haven’t been blogging lately. More on that later, perhaps.) Below are links to the PDF slides/handouts for my paper at Music Theory Southeast.

“Diatonic Spaces in Jazz: A Transformational Approach”
Michael McClimon
Music Theory Southeast, March 28, 2015

bibkeys: Make BibTeX less annoying

October 31, 2014

I’m currently in the process of writing my dissertation (hooray?). For a number of reasons, I’m writing it using LaTeX:

  1. I can write in plain text, which means I get all of the plain-text tools I already use: vim, git, etc. (and can avoid opening Microsoft Word).
  2. My dissertation is about jazz and transformational theory: the TeX macro system means I can define a macro for annoying things I get tired of typing. I can just write \h{Gm7b5} and have the ‘b’ converted into a nice flat character without thinking about it.
  3. I can use the excellent biblatex-chicago package and not have to worry about citations at all.
  4. TeX typesetting is really nice, especially once you stop using the default Latin Modern fonts.

Number 3 is a big one for me: I’ve tried using other citation management software before (EndNote, Zotero, Papers), but never really liked them, since it was always kind of a pain to get it integrated into whatever I was using to write. BibTeX is great: the database is also plain text, so I can edit it however I like, and it’s flexible enough that I can define my own styles to deal with the bibliographic nightmare that is jazz discography.

For those of you not in the know, you can cite something in a paper by including the string \cite{someUniqueId}, where someUniqueId is a citekey. These can be anything you like, but usually include the author’s name: for Jack Douthett and Peter Steinbach’s “Parsimonious Graphs” article, I use the citekey douthettsteinbach:1996.

I really like BibTex, but remembering/typing all of these citekeys was getting annoying by the end of Chapter 1, so I wrote a program to fix it. Enter bibkeys! (Github) Bibkeys is a simple little Perl program that reads bib files in the current directory and spits out their keys in alphabetical order.

This is pretty useful by itself, but is super useful when integrated with your editor’s completion function (I use vim, so that’s what I’ll show here). Vim has something called Omni-completion: you can press Ctrl-X, Ctrl-O in insert mode to bring up a completion menu (see vim help for details). Now that I have bibkeys in my path, I can use it to complete citekeys while I’m writing!

I have this snippet in my vimrc now:

" A function to complete keys from a BibTeX file. Shells out
" to 'bibkeys' (see github.com/mmcclimon/bibkeys) to get a list
function! CompleteBibKeys(findstart, base)
    if a:findstart
        " locate the start of the word
        let line = getline(".")
        let start = col(".") - 1
        echom line[start - 1]
        while start > 0 && line[start - 1] =~ "[A-Za-z:]"
            let start -=1
        endwhile
        return start
    else
        " find months matching a:base
        let keys = systemlist('bibkeys -1')
        let res = []

        " bibkeys didn't return anything useful
        if v:shell_error
            return []
        endif

        for key in keys
            if key =~ '^' . a:base
                call add(res, key)
            endif
        endfor

        return res
    endif
endfunction

au Filetype tex set omnifunc=CompleteBibKeys

If I have a bunch of citekeys that start with “lewin” (no surprise in a dissertation about transformational theory), I can type “lew”, type Ctrl-X Ctrl-O, and get a pop-up completion menu of all of the citekeys starting with that string…pretty cool!

Anyway, bibkeys is up on Github, and is MIT-licensed, so do with it what you like. It’s pure perl, nothing fancy, so if you’re already running LaTeX chances are pretty high you can just dump it into your $PATH somewhere. Enjoy!

Some thoughts on licensing

December 5, 2013

I managed to find myself in a discussion on Twitter (@mmcclimon) this afternoon about licensing. The discussion started out about open access, where a colleague of mine (@krisshaffer) wanted to talk about the distinction between open access (which he equated with CC-BY licenses) and open source (CC-BY-SA). His argument was the open access (CC-BY) “still allows for-profit hijacking of materials.”

I responded and said that according to GNU, open source is not equal to free software, and subsequently that I didn’t particularly care for the GNU licenses. Richard Stallman has a well-known arbitrary definition of freedom whereby “do whatever you want” is less free than “do whatever I tell you to.”

This is a bit long, so I’ll put it behind the jump.

[Quick aside for context.] The Free Software Foundation (FSF) was founded by Richard Stallman, who in the 80s started developing an operating system called GNU, which he envisioned as the world’s first “free operating system.” This system still doesn’t exist entirely, though Linux is basically the same (despite what Stallman might tell you). The GNU Public License (GPL) is a software license which says that any modifications to the software must be released also be GPL-licensed (commonly referred to as a copyleft license). The Creative Commons system of licenses is similar, but are more applicable to non-software works: books, articles, music, etc. (All of Wikipedia is available under a CC-BY-SA license.)

[Aside over.] Kris asked which licenses I liked better, and the answer to that is “nearly all of them.” My software is typically under the MIT license (or Artistic License, for Perl), but I also like the BSD licenses quite a bit, along with Apache, Mozilla, and of course the WTFPL. He responded that he sees copyleft as “helpful for maintaining communtiy ownership and preventing corporate hijacking,” which is of course true. He continued, “CC BY lets the immediate user do more, but the restrictions of SA (GPL), allow the next users to do more.” I couldn’t compress a response into 140 characters, so I’m writing this instead.

Kris (and the FSF) are of course right that works under the GPL/CC-BY-SA allow later users more freedom. My disagreement with these licenses (the GPL in particular) is purely a moral one. The ultimate goal of the GPL is to force all software to be open source. I realize that this is in actuality not more restrictive than copyright, but it goes against what I feel is the spirit of open source.

When I write software (or anything, for that matter), what matters to me is getting it out to the public. If other people find it useful, excellent. If they expand on it, great. My thoughts on the GPL are pretty well summed up by this article. Both the LGPL and CC-BY (along with the MIT, BSD, et al) licenses require that the initial license is included in the final work, but not that the derivative work also be open source. Because the original, open-source version is still available, my work is still open source and any later user can do whatever they like with it. I don’t think it’s my place to tell other people they can’t do what they want to with my work. That’s a moral decision, and either way is really ok with me.

The more interesting part of this discussion is the connection to academia. Open access is a great thing (and pays my salary, incidentally). The distinction between open access and open source in academics is much fuzzier than in software, however. (And I mean “open source” in Stallman’s terms now: access to source code. When Kris is talking about open source he is really talking about copyleft.)

What’s interesting to me is that academia has always been open source, but not open access. Essentially everything is CC-BY: if I want to use David Lewin’s work in my dissertation (which I’d hesitate to call a derivative work!), I can. I don’t have to get permission from the Lewin estate, or from Oxford University Press, I just have to say that they’re his ideas and tell people where to find them.

This is because the distinction between “source” and “content” is non-existent in the humanities in a way that is different from software (I’m certainly not the first person to have pointed this out, but I can’t recall having read it before). There is no secret “source code” to GMIT that is then run to generate the book; if there is, I’d certainly like a copy! Open source is useful in software because I can ship you a piece of software that is a black box: you can use it and have no idea how it works. That’s not the case in academia, though I have seen some people try.

The distinction then, hinges on “access,” and in the humanities I’d argue this distinction isn’t terribly important. Let’s say that there is a website that has the full text to Lewin’s Generalized Musical Intervals and Transformations available for free (open access). If I want to use this resource, it doesn’t matter to me whether it’s CC-BY or CC-BY-SA: if I’m a responsible scholar I’m going to cite it in either case.

The caveat is that CC-BY-SA does not prohibit commercial use (the relevant CC license is the NC provision). If I want to print off a copies of this mythical CC-BY-SA licensed GMIT and sell them to my friends, that’s perfectly fine (just as it’s perfectly fine to sell GPL-licensed code). In practice this doesn’t matter much: because the GPL requires me to include the license, this original version is always available. Users are much more likely to use the free version rather than the paid version, unless there is significant added value to the paid version (I’d gladly pay someone if they had fixed all the typos in GMIT).

I think open access is a great thing, and I think more journals/presses should be doing it, but I don’t think the distinction between open source and open access in the humanities is one worth spending a lot of time on.

Introducing Mr. Poole

September 24, 2013

Last weekend, I released my first real open source project, “Mr. Poole” (available on Github). Mr. Poole is a helper for Jekyll, which is the software I use to write this blog. In the several days I was using jekyll, I got annoyed at creating scaffolding for posts/drafts. It was taking so long (maybe like 5 seconds every time I had to do it), so obviously the solution was to spend many many hours writing a script to cut this 5 seconds down to 2. If there’s one thing programmers do, it’s spend hours now to save seconds later.

Mr. Poole is the butler in Stevenson’s Jekyll and Hyde (which I must admit, I’ve never read). According to Wikipedia, “Poole is Jekyll’s butler who, upon noticing the reclusiveness and changes of his master, goes to Utterson with the fear that his master has been murdered and his murderer, Mr Hyde, is residing in the chambers. Poole serves Jekyll faithfully, and attempts to do a good job and be loyal to his master.” I thought it was a clever name, and apparently a few other people did too (he who ships, wins).

Mr. Poole provides an executable (poole) that eases this process. Creating a draft is as simply as running poole draft, which you can then create as a post by running poole post. Creating a post can be done with poole post, and if you decide later you don’t like it, it’s as easy as poole unpublish. You can read all of the details on the Github page.

At any rate, it was my first Ruby gem, and my first real open source project of my very own (I’ve contributed to others before). I think it’s doing pretty well (105 stars on Github and 317 downloads on RubyGems), which is pretty good considering I only announced it on my Twitter (which nobody reads, but you should!), on /r/ruby, and on Hacker News. I’ve already gotten one pull request, and hopefully people like it. Maybe one day I’ll have another decent idea for a project…it’s fun to contribute to the open-source community, and to participate in something that’s not a giant project.

Now it’s time to poole publish this thing and put it on THE INTERNET.