LaTeX is a powerful tool used almost canonically in scientific writing. The main appeal is that, as a researcher, you focus on writing text and formatting is handled by LaTeX (and the template you are using). If you are using Python (an example), you can also export most of your results directly to LaTeX format and just copy and paste.
I’ll be honest with you, the non-technical part is an overstatement and refers mostly to the experience after setting up all the tooling we need. Nonetheless, the technical part is highly just-follow-along, you do it once, and then forget forever all the pain other academic pipelines can produce.
In any case, if you just want to test LaTeX the fastest way possible (and thus without all the addons that highly improve the experience), you can watch this less than 2 minutes video instruction.
This guide is tested for Linux (Ubuntu) and Windows. I have not tested it yet on Mac, but the process should be quite similar.
All this is possible thanks to the extremely competent and determined teams behind all the tooling we will scrap the surface in this post.
Windows Setup
Starting with setting up Windows Subsystem for Linux (WSL), Linux users can skip directly to: Setting up LaTeX (Tex).
Windows Subsystem for Linux (WSL)
Running LaTeX is considerably pain free in Linux, and thanks to WSL, working on Linux is considerably pain free on Windows.
If you don’t have WSL already enabled:
1. Open a PowerShell with administration permissions (search for “powershell” in taskbar, then right click “launch as administrator”).
2. Paste the following line:
wsl --install3. You can change the distribution to be installed if you like. In this guide I’ll be using Ubuntu (the default).
4. Restart your computer.
5. After restarting, a WSL terminal will open, if not you can open it by searching “terminal” in the task bar and then clicking the arrow next to the “plus” button and selecting Ubuntu (see image below).
6. In this terminal (which is Ubuntu or another distro running inside your windows installation) you will be requested to write your username (it can be any username, nothing to do with your windows account), and a password (characters will not appear on screen while typing the password; you type your password, you hit Enter, then you retype your password, then again Enter). Don’t forget your password.
7. In the same window paste the following line:
sudo apt update && sudo apt upgrade -y
8. Hit Enter, then type your password, then Enter again.
9. A lot of lines are going to appear inside the terminal, this is normal as the system is updating.
10. We let the process finish and in the meantime move to the next step.
Setting up LaTeX (Tex Live)
1. On an Ubuntu terminal paste the following:
sudo apt install texlive-latex-recommended The process will take some time, so let’s move on to the next step.
For the curious: Tex Live is a sort of processor for LaTeX that, for our purposes, converts our LaTeX syntax into a PDF document. There are other options to Tex Live, like MiKTeX.
Installing VS Code
You can write LaTeX in any word processor, but Visual Studio Code (VS Code), and the community behind the plugins we will use, make writing an enjoyable experience.
You can download VS Code for your operating system from the official webpage.
Windows users with WSL (Ubuntu or another disto) should still download the windows version.
VS Code plugins & Settings
Existing Users of VS Code
Existing users of VS Code may find it useful to create a new profile for their LaTeX workflows before installing plugins.
This can be done by selecting the icon in the bottom of the left bar, then selecting Profile, and then Profiles (Image 1). A window will popup where a new profile can be created with a distinct name, icon, etc. (Image 2)
Tip: Setting are saved for each profile, for example, you may prefer a lighter colour theme for LaTeX workflows and a darker for code. Colour themes can be changed by tapping ctrl+shift+p, then typing “Preferences: Color Theme” and selecting the one that you prefer.
(Optional) Enabling Word Wrap
If you are coming for a text editor like Microsoft’s Word, you are probably used to lines changing automatically. To achieve this in VS Code.
1. Go to File > Preferences > Settings (Image 3).
2. Type “word wrap” and set it to “on” (Image 4).
Alternatively, you can toggle word wrapping on or off temporarily by tapping alt+z.
For Windows Users
Because we need a way that VS Code communicates with our Tex Live installation in WSL, Windows users need to install the Remote Development Extension.
1. Go to Extensions tabs (5th icon from the top on the left bar).
2. Type: “Remote Development” and hit install.
LaTeX Workshop
LaTeX Workshop is the core of VS Code communication with Tex Live.
1. Go to Extensions tabs (5th icon from the top on the left bar).
2. Type: “LaTeX Workshop” and hit install.
3. (Optional) Click on the gear icon and select “settings”, then on the top bar where “@ext:James-Yu.latex-workshop” is shown, replace with “@ext:James-Yu.latex-workshop synctex”.
4. (Optional) Enable the Synctex > After Build option (Image 5), this allows for clicking anywhere on the Latex PDF and automatically going to the relevant point in the LaTeX document. Trust me it’s very useful.
Pretty much at this point you are all set to start writing LaTeX, but setting up the below considerably improved the overall experience.
Spell and Grammar Correction
For spell and grammar correction we will install the LTeX+ extension.
1. In Extensions tabs, type: “LTeX+” and hit install
2. Click the gear icon and select “settings”, then set the Ltex: Language (the main language to be set), you will have to scroll a bit to find it (Image 6).
3. If you are a perfectionist, setting up your Mother Tongue and Picky Rules is a good idea (Image 7).
Zotero Citations
If you are accustomed to writing scientific papers, you may be using Zotero for managing citations. So, I assume your have Zotero and Zotero Connector already installed.
Better BibTeX for Zotero
1. Go to Better BibTeX for Zotero github and download the .xpi for the latest release.
2. Open Zotero and go to Tools > Plugins.
3. Select the gear icon and then “Install plugin from file”
4. Choose .xpi that you’ve just downloaded and click ‘Install’
More info about Better BibTeX for Zotero.
Citation Picker for VS Code
To install the citation picker (which is the same UI if you used Zotero for Word) for VS Code:
1. In Extensions tabs, type: “Citation Picker for Zotero” and hit install
2. Click the gear icon and select “settings”, then in the “Zitero-citation-picker: Port” paste “http://127.0.0.1:23119/better-bibtex/cayw?format=latex“
Use Case Example
Now that we have a functional set up let’s see how it works in action.
We will go ahead an create a new folder for a new research paper and then in VS Code: File > Open Folder > the folder.
Windows users can …
We are going to be using ACM’s LaTeX Template, after downloading the zip, and copy the “acmart.dtx” and “ACM-Reference-Format.bst” into our folder.
Then we are going to create a new file, let’s say main.tex (Image 8), this is where we will write all our research.
Linking Citations with Zotero
1. In Zotero, we can create a new collection.
2. Right click on it and click export.
3. Select Format as “Better BibTeX” and enable “Keep updated” (Image 9).
4. Then select it to be saved in the folder we created.
Writing the Main Text
As an example, we start writing in main.tex the following text:
\documentclass[acmsmall,screen,review,nonacm]{acmart}
\usepackage{comment}
\AtBeginDocument{%
\providecommand\BibTeX{{%
Bib\TeX}}}
\begin{document}
\title{A Sample LaTeX Research Paper}
\author{Author name}
\maketitle
\section{Introduction}
This is a sample document that will be converted into a PDF using ACM's format \cite{veytsmanAcmartClassTypesetting2017}.
\begin{comment}
Author 1: I can write a comment like that.
Author 2: I can reply.
etc...
\end{comment}
% Another way of writing comments.
% For example below we append our bibliography.
\bibliographystyle{ACM-Reference-Format}
\bibliography{research-test} % Make sure to change the name here to the file that you exported
\end{document}
\endinput
Citations
When you have Zotero running and writing a text in VS Code you can click alt+shift+z to add a citation (in our example, “\cite{veytsmanAcmartClassTypesetting2017}”).
Creating and Viewing the PDF
LaTeX workshop will automatically compile the PDF on every save.
We can view this PDF but opening the relevant file (in the same folder as the one we placed our documents), or, by clicking the top right button with the magnifying glass (Image 10).
Advanced: Versioning and Tracked Changes
For those with experience in paper writing in groups, tracked changes is an indispensable feature. Git can provide both with back-ups and a way to track changes, albeit sub-word processor level.
Setting up Git
For Windows users, Git is best to be installed in WSL, thus the below process works both for Windows and Ubuntu users.
1. In a Ubuntu terminal type “sudo apt update & sudo apt install -y git”, then press Enter, enter your password if prompted, and then Enter again.
2. Although not strictly necessary, we will need an online repository to upload our changes for other co-authors to download. In this tutorial, we will use Github, but other options like Gitlab are equally as good.
3. In general, we need to have a Github account, and set up at least SSH access. There are two great guides by Github on How to Add a new SSH key. For the most basic usage the following code sets up SSH.
Setting up SSH
Windows users can follow the Linux instructions and pasting commands in their WSL terminal window.
1. Paste the text below, replacing the email used in the example with your GitHub email address.ssh-keygen -t ed25519 -C "your_email@example.com".
2. Follow the prompts, accepting the default options is fine.
3. In the terminal type: eval “$(ssh-agent -s)”
4. Then: ssh-add ~/.ssh/id_ed25519
5. Copy the line that will appear in the terminal.
6. In the upper-right corner of any page on GitHub, click your profile picture, then click Settings and in the “Access” section of the sidebar, click SSH and GPG keys.
7. Click New SSH key or Add SSH key and then add the line that you pasted.
Git Workflow
When git is set up we can manage all out workflow from “Source control tab” (Ctrl+Shift+G) on VS Code.
We can initialize a new repository and upload our changes in a private Github repository that we will create.
In this case, let’s imagine that we are a co-author in a paper and we have been sent a Github link with the first version by another of our co-authors (receiving workflow).
Receiving Workflow
1. We received a link with a format like “git@github.com:username/repo-name.git”.
2. In our Ubuntu terminal we type “cd ~ && git clone git@github.com:username/repo-name.git”, replacing with the link we got
3. Then we open VS Code. For Windows users, making sure it is connected to the WSL (Image 11).
4. We select “Open folder” and then the folder with the name of the repository we just cloned (Image 12).
5. We can now edit text to our liking.
6. After finishing editing, we switch to the “Source Control Tab” (Ctrl+Shift+G), and in the Changes section we add a name for our version (Image 13).
7. Then we click commit and then click on “sync changes” (you may be requested to type the SSH key password we created above), our changes will now be uploaded to Github and our co-authors can review them.
Tracking and Reviewing Changes
An Important Writing Guideline
The readability of using Git as “tracked changes” can be considerably improved if the authors are using Semantic Line Breaks.
Applying the full specification is an overkill for our purposes, but keeping in mind the first 4 rules greatly improves readability.
- Text written as plain text or a compatible markup language MAY use semantic line breaks.
- A semantic line break MUST NOT alter the final rendered output of the document.
- A semantic line break SHOULD NOT alter the intended meaning of the text.
- A semantic line break MUST occur after a sentence, as punctuated by a period (.), exclamation mark (!), or question mark (?).
Tracking and Reviewing
When a co-authored have pushed (uploaded) their changes, we can review them by
1.Going to the “Source Control Tab” and clicking pull. This will download the changes the co-author(s) made and add them to our file.
2. We can then view the changes by looking at the Graph Option and clicking on the version we want to review (Image 13).
3. When we select, for example the main.tex, we can look at the left the previous file version (left) versus the changes introduced (right). As shown in Image 14.
4. Then we can make changes, commit and sync (push) like before and keep going until we reach the last version. Every version is saved on all authors’ computer + the cloud infrastructure (Github), so we can revert at any point or just consult what we previously have written.
And that’s it. You made it!
Setting up just happens once and then you can write with this workflow forever (which for us, Linux users, is until the next reinstall).