documentation

LaTeX

Documentation is an important aspect of anything from programming to university papers.

I’ve had to create documentation in the past using LaTeX and always found it an interesting method compared to using a word processor.

In this post I will go over how to setup your system to generate pdf documentation using xeLaTeX.

Before we begin there are a few things we should discuss. Firstly I am using openSUSE for my Linux installation, so that is the method of installation I’ll be describing.
If time allows I will list the steps necessary for a Windows setup as well. Sorry I can’t do a Mac install as I have no access to such a system.

Installation

on openSUSE

Luckily the packages we need are available from the openSUSE repository, so no need to find them manually. Just run the following to install texlive.

sudo zypper install texlive

This will install the base texlive system. You may need to install some packages manually but no worries they are just a search away with the package manager.
All packages starts with texlive- which makes it a lot easier to find packages.

sudo zypper search texlive

There is a long list of packages available. To save on system resources only packages you need should be installed.

Let’s check if xelatex is available after the installation.

user@machine:~> xelatex --version
XeTeX 3.141592653-2.6-0.999996 (TeX Live 2024/TeX Live for SUSE Linux)
kpathsea version 6.4.0
Copyright 2024 SIL International, Jonathan Kew and Khaled Hosny.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the XeTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the XeTeX source.
Primary author of XeTeX: Jonathan Kew.
Compiled with ICU version 73.2; using 73.2
Compiled with zlib version 1.3.1; using 1.3.1
Compiled with FreeType2 version 2.13.2; using 2.13.2
Compiled with Graphite2 version 1.3.14; using 1.3.14
Compiled with HarfBuzz version 8.4.0; using 8.4.0
Compiled with libpng version 1.6.43; using 1.6.43
Compiled with pplib version v2.2
Compiled with fontconfig version 2.15.0; using 2.15.0

Next we need an editor for LaTeX documents. I opted for using TexStudio. It’s also available in the repo. You can of course use any editor you want. Even Visual Studio Code can be used with a few plugins.

sudo zyper install texstudio

on Windows

The Windows procedure entails downloading an installer from the web and using it to install texlive. It’s best to get it from the official website🔗.

I would suggest following the instructions on the official website.

Next install TeXstudio. Again you should download it from the official website🔗.

I opted for using the portable version but you don’t have to do that.

Container setup

Another option is to run texlive in a podman container. I have created a repository with the instructions for building the image and running the container.

You can find it here🔗.

Setting up TeXstudio

I prefer to use XeLatex to generate pdf files, so I typically change the default compiler to xelatex.

texstudio-build-settings

Basically that and the theme and font size is all I change.

You may notice in the screenshot above I also created a user command. It’s a simple command to just convert a pdf file to a ps file. You may or may not need this.

First document

Now let’s create a simple document and make sure we can create a pdf file.

  1. Fire up TeXstudio

  2. Select File -> New to create a new document

  3. Select Wizards -> Quick Start… and press OK to use the default settings.

  4. Enter some text between the start and end document lines. e.g. below.

    \documentclass[10pt,a4paper]{article}
    \usepackage[T1]{fontenc}
    \begin{document}
        Hello. This is a test.
    \end{document}
    
  5. Select icon Build & View from the toolbar and check your PDF is displayed on the right. First document

Congratulations! You just created your first PDF document using LaTeX.