Zotero, LaTeX, Git, 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 do exactly that? Some of these tools are really easy to use, and will save you lots of time and headache. Other are harder to learn— if you have never programed before, the learning curve can be steep, but I promise relatively short. In what follows, I’ve tried to reduce the difficulty of that initial dive into using some of the power tools of our digital age. I’ve organised sections according to the ratio of reward to difficulty, with the easy stuff coming first, and more advanced topics coming after. I will begin each section with a “pitch” which describes what you get, as well as a guess about how much time it will take to learn. I will also try to indicate differences for Mac and Window users where differences occur.

  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, bringing your research process into the 21st century. (Cost: 3 minute installation, with 10 minutes to get it running in your browser.)
    1. Download and instal 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. Note: Zotero 5 is not compatible with Better BibTex as of Nov 2017. If you want Zotero to be able to play nice with LaTeX, make sure to instal Zotero 4 which you can find available on the Zotero website.
      3. Note: Firefox is optimised for Zotero with a pop-up toolbar, however I prefer the low profile that Zotero keeps in Chrome or Safari.
    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.
      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, if the website is being fussy (Jstor is terrible!).
      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.)
      6. Note: If you have a project folder open in Zotero, the paper will be automatically added to that project.
  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 to others or your future self, as well as advanced version control with Git (see below). LaTeX also integrates nicely with Zotero so that you can add citations to your paper along with the associated reference in whatever style to your auto-generated bibliography. (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. But then it gets a lot easier, where you can learn more advanced practices as needed.)
    1. Download and instal 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 which comes from here.
        3. Now add this template to Library -> TexShop -> Templates. This template includes the commands \bibliographystyle{Analysis} 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/Analysis} and \bibliography{C:/texmf/bibtex/bib/Zotero} at the end of the document which will look up the file you placeed 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 Analysis.bst such as this one.
    3. You can now integrate Zotero and LaTeX as follows (also see this video):
      1. Download the Better BibTex plugin, installing the package by clicking Add-ons in the the ‘Tools’ menu bar at the top of your screen when Zotero is open. In the Add-ons manager, click the gear dropdown menu, selecting ‘Instal add-on from file’. Select the .xpi file you just downloaded. Restart Zotero.
      2. Now click the gear drop down menu in the main Zotero window and select ‘Preferences’. Open up the ‘Better BibTex’ tab just to the right of ‘Advanced’. Under the ‘Citation’ sub-tab, replace the citation key format with this: [auth][year]. (For other options, you can look up the syntax. Further information can also be found here.) 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’. It should look like ‘Fine1994a’. Once you have the key, you can cite that paper by writing ‘\citet{Fine1994a}’ (without quotes) in the new tex file.
        1. Note: To list multiple sources by the same, or different authors, separate the cite keys with a comma such as: ‘\citet{Fine1994a,Fine1995,Fine1995b}’. 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 at first, but becomes really natural and easy. However, there are much better text editors out there (see below for one such example).
        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 currently offer macros support.)
    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 loads of tutorials as you’ve probably already seen, though not all of them are great. As you learn, I would highly suggest making notes in the preamble of your template file of the really useful bits that you learn in order to instruct your future self. 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. Editor Pitch: Although TexShop (or TexMaker) isn’t bad to start, there are much better text editors out there. I highly recommend Sublime Text 3 which has 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 instal 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 instal, 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. Pandoc Pitch: This guy is way ahead of me.