Zotero, LaTeX, Vim, Git, Pandoc, etc.

If you are planning on spending a lot of time writing— perhaps extending over many different versions, or in collaboration with others— why not use some of the state of the art tools designed by and for software developers to edit text? Some of these tools are easy to install and use, and will save you a huge amount of time and headache. Others are more difficult, and although the learning curve can be steep, the resulting increase in efficiency is well worth the time investment. In what follows, I will highlight some of the features of the software that I use for academic writing, providing a sense of the benefits of using these tools as well as the costs in time investment to learn how to use these tools. I will begin with tools which require the least effort to learn, concluding with Vim which I take to be the state of the art for editing text, where you can find extensive installation and configuration instructions on my GitHub repository.

  1. Zotero Pitch: Even if you have no interest in using LaTeX, Zotero is a must for managing your pdf database as well as bibliographic data. Zotero is an open-source reference management software which does all the work for you of saving bibliography data, pdfs, notes, or other files. Rather than ending up with an dizzying array of folders on your hard drive (or desktop!) crammed with documents, Zotero lets you easily create and destroy project folders without creating multiple versions of each paper (unless you want that). Additionally, Zotero will download and organise the associated pdf with the reference, all with the single click of a button in your web browser. That way, building your reference database is the passive result of sorting through papers that interest you online. Most importantly, this software allows you to generate bibliographies from any selected folders or files, and is compatible with most word processors. I’ve given detailed instructions below on how to install Zotero. (Cost: 3 minute installation, with another 10 minutes to get it linked to your LaTeX editor.)
    1. Download and install Zotero together with a plugin for your preferred browser.
      1. If you use Word, you can follow these tutorials to both install and use.
    2. Now run a simple test:
      1. Find a paper you would like to download. If you use a VPN provided by your research institution, make sure that it is turned on, and if you use an AdBlocker, make sure that it is not blocking pop-ups for the journal’s website.
      2. Before downloading the paper as you normally would, notice the small Zotero icon in the top-right of your browser. If Zotero has located a single paper, the icon will look like a paper; if it has located multiple, it will look like a folder.
      3. Click the icon and, if need be, select the desired paper. If all goes as it should, a small banner will pop up in the lower right-hand side of the screen that indicates that it has scraped the bib data and downloaded your file, giving you the chance to file the paper in a project folder if you desire. (Alternatively, if you open a project folder in Zotero by clicking on it on the left side of Zotero, then any papers you download will be automatically filed in that project folder.)
      4. Now switch from your browser to Zotero to check if the bib info (with the pdf) showed up. If it did not work, or did not grab the pdf with the bib data, make sure you are appropriately logged on to the journal website and repeat. For instance, if you are unable to download the pdf in the old fashioned way, then Zotero will not be able to download the pdf either. If problems persist, you can look for further answers here. You can also always add the file manually to the bib info by right-clicking the paper in question in Zotero. Some of the journal websites work better than others. For books, Amazon is a good resource for scraping bib data, though of course no pdf will be downloaded.
      5. Once you are able to capture bib data, you can check that the website provided complete and correct information, making any changes that are needed. I don’t typically do this if I trust the source. (PhilPapers is pretty inconsistent, and so I mostly avoid getting bib data from there.)
  2. LaTeX Pitch: Writing formal symbols is by no means the only reason to use LaTeX which is an extremely powerful and customisable typesetting tool, allowing you to separate composition from formatting, giving you the freedom to make “in line” notes. Additionally, by writing in LaTeX, you can take advantage of some of extremely powerful text editors out there such as Vim or Sublime Text, as well as advanced version control with Git (see below). (Cost: To get going, LaTeX is about as hard as learning to barely speak a foreign language while traveling. You will need to learn some vocabulary and new ways of doing things. I provide templates on my GitHub repository to make it easy to get started. If you like the way I have things formatted, then it will not take much to learn enough to write papers using these templates. Modifying the templates, or in general customising the formatting, is more advanced, and will likely require some googling.)
    1. Download and install the LaTeX distribution for your operating system.
    2. Create the ‘texmf’ folder tree in your directory.
      1. For Mac users:
        1. You will first need to locate your main ‘Library’ folder in Finder. Begin by opening a new Finder window. Press cmd+shift+h to go to the home folder, and cmd+j to open an options window. Check ‘show Library folder’.
        2. Then create a folder called ‘texmf’ in your Library if it is not already there, and another folder called ‘bibtex’ inside texmf. Inside bibtex, create folders called ‘bib’ and ‘bst’. Inside bst, place this style file (you can cut and paste the contents into a new file with the same name and extension to be saved in your bst folder if you do not intend to clone the full repository).
        3. Now add this template to Library -> TexShop -> Templates. This template includes the commands \bibliographystyle{Phil_Review} and \bibliography{Zotero} at the end of the document which will look up the file you placed in the bst folder as well as the bibliography you will place in the bib folder in Ciii below.
      2. For Windows users:
        1. In C, create a folder called ‘texmf’, and another folder called ‘bibtex’ inside texmf. Inside bibtex, create folders called ‘bib’ and ‘bst’. Inside bst, place this style file which comes from here.
        2. Now add this template to Users -> {user name} -> AppData -> Local -> MikTex -> 2.9 -> TexWorks -> 0.4 -> Templates. This template includes the commands \bibliographystyle{C:/texmf/bibtex/bst/Phil_Review} and \bibliography{C:/texmf/bibtex/bib/Zotero} at the end of the document which will look up the file you placed in the bst folder as well as the bibliography you will place in the bib folder.
        3. If you want to save the bst and bib files elsewhere, you will need to change the path in the template file. Note the forward slashes in place of backslashes. You can also substitute other bst (bibliography style) files for Phil_Review.bst such as this one.
    3. You can now integrate Zotero and LaTeX as follows (also see this video):
      1. Download and install Better BibTex by following these instructions, restarting Zotero after completed.
      2. Under ‘Edit’ in the Zotero menu bar, select ‘Preferences’ and open up the ‘Better BibTex’ tab. Under the ‘Citation’ sub-tab, replace the citation key format with this: [auth][year]. Also check ‘On item change’ at the bottom left.
      3. Now switch to the ‘Automatic Export’ sub-tab and check ‘On Change’. This means that the instant you update your database with a new bib entry, or edit an old bib entry, Zotero will update the .bib files where your database is exported. If your library is extremely large, this could be slow, and so you might want to select the ‘When Idle’ option. But I have no troubles with the ‘On Change’ feature.
      4. Close the Preferences window, returning to the main Zotero window. Right-click the main library folder in the left-most blue column, select ‘Export Library’ (alternatively you can export other project folders, but I like to keep things simple). Under the ‘Format’ dropdown menu, select ‘Better BibTex’. Then check the ‘Keep Updated’ box. Save the file as ‘Zotero’ (the extension will be added automatically) to the bib folder that you previously created.
    4. You can now run a test that everything is working.
      1. Open TexShop and create a new file (or create a file from template in TexWorks). In the ‘Templates’ drop-down menu, select PhilArticle. Press cmd+T (or click ‘Typeset’). Save the document in a new folder with the appropriate project name.
        1. Note: If the file does not run, open TexLive Utility in the Tex folder in the Applications folder, and update. Restart everything and try to typeset the file again.
        2. Note: Occasionally, it can also help to click Trash Aux Files in the error console, if the pdf is not generating properly.
      1. Once your file typesets, open Zotero and click on one of the files in your library, and look for the ‘Citation Key’ in the details. If no key is present, or the key data is not of the form [auth][year], you can right-click the file in your library and click ‘Generate BibTex Key’. Once you have the key, you can cite that paper by writing ‘\citet{CITEKEY}’ in the new tex file.
        1. Note: To list multiple sources by the same, or different authors, separate the cite keys with a comma. For other citation styles, refer to the preamble of the PhilArticle template for further commands, e.g., ‘\citep’, etc.
        2. Note: It can also be helpful to customize commands as exemplified in the preamble of the PhilArticle template provided above. I have included a definition of \citepos which is useful for making citation names possessive.
      2. In TexShop, you will need to hit cmd+T, then cmd+shift+b, then cmd+T, and the cmd+T for a final time. You should see both the citation you added in the text as well as the full citation in the references. Why all the command combinations? The first cmd+T will update the .tex file you are working on, adding the citation key. The cmd+shift+b will look up the citation key in your master Zotero.bib file saved in the bib folder. Then another cmd+T will import the citation data, and the final cmd+T will typeset it altogether. Sound clunky? It is, and that’s not the least of it. However, there are much better text editors out there (see below).
        1. Note: Want to check how many words your document has? Open the ‘Macros Editor’ under the ‘Macros’ toolbar in TexShop. Select ‘New Item’ giving it a name like ‘TexCount’ and dragging it from the bottom of the list (left column) up to the top. Then cut and paste this into the content. Many more macros can be found here. (TexWorks does not include a word count macro for some reason.)
    5. Now you are ready to tex! If you get stuck, get used to googling things and reading the bottom of the error console. YouTube also has many helpful tutorials. As you figure things out, I highly suggest making notes in the preamble of your template file of the really useful bits. By adding a ‘%’ symbol after the new bit of code you add to the preamble, you can explain what it does so that next time you will remember. Lots of helpful information is also available here including a nice lookup guide.
  3. Sublime Pitch: Instead of using TexShop (or TexMaker), there are much better text editors out there. In particular Sublime Text 3 is a relatively fast IDE with lots of nice features— e.g, does all the compiling at once— and takes integration with Zotero one step further, allowing you to look up citations in Zotero from a dropdown bar that appears in the editor when you write ‘\citet{‘ such that you reference papers without even having to use the mouse. There are lots of good youtube tutorials to see how to get started, and some of what you can do once you are up and running. If you know how to write LaTeX already, there is very little learning curve depending on how much you want to customise your editor. If you are happy with out of the box, it is still a huge upgrade in comparison to basic editors. (Cost: minimum 30 minutes to install and setup, where another hour will take you through some nice tutorials about customisation).
    1. Here is a detailed video for installation and customisation, and another video for academic writing more generally.
  4. Git Pitch: Want to be able to track your changes? How about across two computers, backing up to an open-source repository online? You can do much more than that with Git, which is a convenient version control software which can help you manage your workflow, track changes as you work, leaving yourself or others notes, and backing up a complete history of your work as it progressed. You can also compare any difference (in context or lumped together) between versions by simply selecting those versions to “diff”. (Cost: The hardest part about Git for a beginner is the install, requiring some use of the terminal. However, even if you don’t know how to do that stuff, carefully following the tutorials below should get you up and running in a little under an hour. Then it is pretty easy to use.)
    1. Here is how to use Git via the Git Savvy package inside Sublime (very easy to use, and avoids the need to run git commands in the terminal). That said, you will also need to know a thing or two about how Git works outside of a Sublime environment. This tutorial gives you all the basics.
  5. Vim Pitch: Although Sublime is a huge step up from TexShop with not much more required to get it configured to your needs, Vim takes this a lot farther, providing a lightweight and highly customisable stock text editor which can be configured to your exact needs without including anything extra. As a result, Vim is must faster Sublime, or some of the other IDEs like VScode or Atom. I have provided all of my configuration files on my GitHub repository along with extensive installation instructions so that you can recreate the Vim setup that I have optimised for writing LaTeX in Vim without going through the difficulty of cobbling together a collections of plugins and settings for yourself. I have also uploaded a number of videos demonstrating some of the virtues of writing LaTeX in Vim, as well as providing details on how to clone my configuration onto your computer.