Working with Latex

Don’t write your document/report/thesis in Word. Use LaTeX instead. Its a professional typesetting tool (whatever that means). However it can also seem quite complicated at first. The learning curve is a bit rough. So heres how I work with it.

First, there’s many different tools out there to help with using Latex.

• The easiest is by using Overleaf, the Online LaTeX Editor
• Writing LateX using some softwar. It sucks on Windows (it sucks)
• Using VSCode and various plugins

I tried all above, and ended up with a very barebones approach.

TLDR

• write plain latex files with Vim
• version the text in a Git repository and practice using Conventional Commits
• write a Makefile to automate compilation and add helper commands
• setup autocompile using entr on file changes
• view the pdf with zathura (which supports live changes on changes)

Workflow

1. Update repository (e.g., with git pull -r)
2. Start auto-compilation and open the PDF file with make
3. Write changes (break up long lines)
4. Git commit your changes, e.g git commit -am "docs(README): add citation
5. Push the changes (e.g., with git push origin master)

Install LaTeX

If you are using Linux, I recommend TeX Live

Install on Arch:

sudo pacman -S livetex

Getting Started

Let’s write a file called main.tex with this content.

\documentclass{article}
 
\begin{document}
 
\title{Hello, World!}
\author{Your Name}
\date{\today}
 
\maketitle
 
Hello, World! Welcome to LaTeX.
 
\end{document}

Now compile it to a pdf using latexmk. This is the command I usually use:

latexmk -quiet -pdf -shell-escape -f main.tex

To clean up the directory from temporary files, use this:

latexmk -c main.tex

Automating Compilation with entr

One of the most useful Linux command is entr. We can use it to run arbitrary commands upon files changes. It supports Unix pipes, which allows us to run our compilation command like this: echo ${FILE} | entr ${COMMAND}. If we want to run the compilation command on any latex file change, we can use this command.

ls *.tex | entr  latexmk -quiet -pdf -shell-escape -f main.tex

Project Structure

Start off with writing everything in a single file. Later on, think about separating document structure, the actual text content, or independent sections. This is useful when working with other people in Git.

You can include other files in your document with \input{folder/inp_document.tex}. This feature can be used to split larger LaTeX documents.

Versioning LaTeX Changes with Git

The LaTeX compiler will take care of formatting and displaying text. It will ignore linebreaks and carriage returns. So we can break up long lines of text and improve readabillity. I adopted the practice of either starting every sentence on a new line, or use a word count as a limit (Vim’s gq motion will autoformat it for you).

The reason is that Git by default shows the entire line as changed if a single word is modified. If multiple sentences are on one line, they will all be marked as changed and it gets difficult to see what changed.

Writing useful Commit Messages

To track documentation changes consistently, consider using Conventional Commits. A commit can look like this feat(bibliography): add missing citations and is comprised of the following parts:

1. Type - What type of change? Use a prefix that tells you the impact of the change.

   • feat - Represents a commit that changes content (text).
   • refactor - Represents a commit that changes formatting, structure.
   • fix - Correct latex errors or errors in the text.
   • docs - Documentation updates

2. Subject - What part did you touch? If theres no good separation you can omit this.

   • Examples: feat(bibliography), refactor(template), docs(README)

3. Headline - Indicate the why behind your changes, not what you changed.

   • Bad: fix margin, change X to Y, fix graph
   • Good: set margin to comply with submission requirements, reword summary, prevent graph overlap

4. Blank line - If a single line doesnt suffice, be sure to add an empty blank line to separate the headline from the description. Tools use this to show a brief version of commits.

5. Description - Add context for the change after the blank line if necessary. For example:

    feat: initialize repository
   
    - create layout folders
    - add latex compilation files to .gitignore
    - delete example text
   

Example output of git log --oneline with and without a blank line between the headline and description:

With blank line:

052855c feat: initialize repository

b7ff419 refactor: title of contents

The first line of the commit message is used as the headline by many programs (GitLab, IDEs, etc.). If no blank line is used, the entire commit message will be displayed.

Without blank line:

052855c feat: initialize repository - create IT-Grundschutz folder - create .gitignore file - delete test file__

b7ff419 refactor: format text - add image - remove test content - add PDFs to .gitignore file

For more information on writing clean commit messages, see: https://chris.beams.io/posts/git-commit/

Ignoring temporary files for Git

The hidden .gitignore file specifies files that Git should ignore. If additional files need to be added, ask me or try it yourself. The .gitignore file has its own syntax.

Example .gitignore file for latex files

*.pdf
*.aux
*.glo
*.idx
*.log
*.toc
*.ist
*.acn
*.acr
*.alg
*.bbl
*.blg
*.dvi
*.glg
*.gls
*.ilg
*.ind
*.lof
*.lol
*.lot
*.maf
*.mtc
*.mtc1
*.out
*.wcdetail
*.bcf
*.fdb_latexmk
*.fls
*.run.xml
*.synctex.gz
_minted-*