The pros and cons of LaTeX
When you are dealing with rather large chunks of text that should become a thesis, a manual or whatnot, having to deal with MS Word or Pages might not be the best experience. During the writing process, I often find myself dealing with all kinds of formatting related tasks. Not only does this distract me from writing good content, it also leaves me with just one long document. Keeping track of all the chapters and their relations to each other can be a real pain when you have more than a couple of thousand words. At this point, Scrivener comes in as a great writing tool. Basically, Scrivener lets you organize your chapters and sub-texts in a tree-like project drawer. Jason Shafer has a good post about the why.
Writing LaTeX directly can be like writing source code and for most people it might not be the optimal environment for creating texts. For outputting and typesetting however, LaTeX is super cool. Not only will you have sugar-sweet PDF, you can manage and change your whole citation and bibliohraphy style literally with one command. So, before we look into the relationship between Scrivener and LaTeX, let’s first check the requirements for an academic writing workflow.
Here is how the end result should look like:
All files used here can be found on GitHub.
Don’t Repeat Yourself (DRY) is a common practice among programmers. The basic idea is that having duplicated information about the same thing will mess things up at some point. When writing a thesis, you might have experienced this with citations. In a Word document, you would do something like this:
Mayer & Moreno (2002) argue that computer-based learning environments can help improving student understanding.
Then in your bibliography index you add
Mayer, R. E. & Moreno, R. (2002). Aids to computer-based multimedia learning. Learning and Instruction (12), 107-119.
At some point you decide to throw out that top sentence. But in your bibliography index you will still find the entry for Mayer and Moreno. And what will happen when you decide to change your citation style from APA to Harvard or something else? There is no technical relationship between the two and you will have to fix everything by search and replace or by hand.
Introducing BibDesk and Citekeys
BibDesk is an open-source bibliography manager for the Mac. It has a clean and simple interface. Every book, article or website that is important for your thesis, you put into BibDesk with a new entry and a unique citekey. My citekeys look like this:
Using citekeys in Scrivener
In Scrivener we can write in MultiMarkdown (MMD) to link our citations to an unqiue entry in our BibDesk *.bib file.
[#Mayer_2002;] argue that computer-based learning environments can help improving student understanding.
This will later be formatted nicely to match a certain style like APA, Harvard & co. You can use your citekey as shown above by putting it into square brackets after a hash symbol like [#mycitekey]. If you use an inline citation, in the current version 3.2 of MMD, you have to put a semicolon behind your key inside the brackets like [#mycitekey;]. Here are some more examples:
Computer-based learning environments can help improving student understanding[#Mayer_2002]. [P. 108][#Mayer_2002;] notes: "Computer-based multimedia learning environments — consisting of pictures (such as animation) and words (such as narration) — offer a potentially powerful venue for improving student understanding." "Computer-based multimedia learning environments — consisting of pictures (such as animation) and words (such as narration) — offer a potentially powerful venue for improving student understanding"[P. 108][#Mayer_2002].
Update, 08.04.2014: I’ve written a follow up article on multimarkdown citations and optimizing the BibDesk workflow.
For more information about MMD 3 and citations, see the parapraph about Citations in the MMD Guide.
Please note that you’ll have to install MMD 3 *and* its support files. By default, Scrivener 2.2 will use MMD 2 which won’t support the above syntax. It took me four hours to discover that. Basically, you will have to download and install MultiMarkdown-Support-Mac-….pkg.zip into your users ~/Library/Application Support/MultiMarkdown/ directory. Thanks to Neil Ernst who explains in more detail in his blog post.
Organize your document in Scrivener
Putting your document together in Scrivener is very straightforward. Begin with a new blank project. I like organizing my chapters with folders as first level headers in which I put second and third level chapters.
Here is a sample that shows my structure for a sample document:
In Scrivener settings (Scrivener->Settings->General Tab) under “Bibliography Manager” pick the BibDesk Application to tell Scrivener what to open when you hit your bibliography shortcut CMD+Y within Scrivener.
Now let’s go and make a reference to a citekey. I added the article to BibDesk and gave it the citekey “Mayer_2002”. Now in Scrivener I simply embed it into my text like the following. Make sure to save your BibDesk file (best place is the same directory as your Scrivener file).
To achieve this, [#Mayer_2002;] mentions it would be necessary to have uniform grammar, pronunciation and more common words.
Compile the MultiMarkdown into LaTeX
At the moment, all we have is a Scrivener file with some MMD flavoured syntax. To generate a PDF from a LaTeX file we first have to generate a LaTeX file. This process is called compiling. In Scrivener, head over to File->Compile… (ALT+CMD+E). Change “Compile For: Print” at the bottom to “Compile For: MultiMarkdown -> LaTeX”. Under Formatting, check the “Title” checkboxes for every level if you want all to be part of your document (see second screenshot). Now comes the part every Scrivener to LaTeX tutorial I found was outdated. Before Scrivener 2, the Meta-Data settings were in some settings menu, now they are in the Compile window under “Meta-Data”. Meta-Data is important because it will include commands into the LaTeX file that gets saved. Scrivener will only output the plain text (in a structured way for LaTeX) but not any specific information about your thesis like your citation style or title page. Add the following Meta-Data key-value pairs as shown in the third screenshot like this:
Note: make sure you have the exact order and spelling! latex-input has to be at the very bottom!
So here is the explanation for the values. Base Header Level will tell LaTeX how you want your folder-file structure from Scrivener to be translated into chapters. Play around with 1, 2 and 3 and compare results. BibTeX (note spelling) references your literature.bib (or your naming of it) file. latex footer is a file called my-thesis-footer.tex we create and put into the same directory. This file includes everything that is at the very bottom of your latex document like your bibliography index. Bibliostyle can also be managed later in the my-thesis-input.tex file but we do it here for convenience. For more options, see this bibstyles.pdf file. Author and Quotes language should be clear and latex-input will be the document that we will create in a minute called my-thesis-input.tex which will include our LaTeX-Preamble.
Now press “Compile” and save the document into your thesis directory where your .bib file is.
my-thesis-input and my-thesis-footer
Before we generate the PDF we have to make two new files that we reference as our input (which is really more a header but the header meta-data seems to be broken) and footer file. Here is the input (preamble) file and here is the footer file. Drop those two files into your directory where your Scrivener file is.
Make the PDF
Now it is only the PDF that is left to be generated from our LaTeX file. Make sure you have installed the MacTeX-Bundle or similar. Iuse TextMate’s LaTeX Bundle to typeset my PDF files. Open the thesis.tex file in TexShop or TextMate and click “Set LaTeX” once, then click “Set BibTex” and click “Set LaTeX” twice more. Without any errors messages, you should now find eight more files next to your thesis.tex file. One of them is a pdf that should look like this:
Of course, everytime you have a change in your text, all you have to do is compile from Scrivener and typeset the LaTeX in TextMate or TeXShop into your PDF. The whole setup process described here is basically just a one time thing.
The project with all documents used and generated can be found on GitHub.
Follow up blog post on Multimarkdown citations: Optimize BibDesk, Multimarkdown and Scrivener for a nice scientific bibliography and citation workflow
Enjoy writing your papers!