Setting up the required tools
Setup: Local LaTeX Installation
  1. LaTeX distributions
  2. LyX
  3. Pandoc
  4. Workflow for using the template
    1. Git
  5. Compiling the thesis
    1. Latexmk (PdfTeX)
    2. Latexmk (XeTeX)
    3. Source code listings
  6. Validating PDF/A conformance
  7. Installing new TeX packages

LaTeX distributions

In order to compile documents locally, one needs to install one of the LaTeX distributions. The following three are typically used on main operating systems:

Note that the LaTeX distribution is also required when using Pandoc or LyX.

LyX

LyX provides a graphical WYSIWYM interface for editing TeX-like LyX documents that can be converted to TeX. The template distribution contains the utuftthesis.layout document class description file for the same utuftthesis.cls as the one used by TeX documents.

Start by editing the provided thesis.lyx. The file has been configured to use the custom utuftthesis document class.

Depending on your LyX version, you may need to enable -shell-escape from the global LyX settings. Follow the program's instructions. When updating your TeX distribution, LyX may require reconfiguration. This functionality is available via the tools menu.

Pandoc

Pandoc offers very limited functionality for editing a document. Basically all of the more advanced LaTeX macros need to be passed through Pandoc, which defeats the whole purpose of using simplified markdown notation in the first place.

Pandoc is mentioned here mainly because it is one of the options for compiling the lab report template, which is a fork of the thesis template.

Workflow for using the template

Git

Start by cloning the whole template repository (or fork the project in GitLab). The following command line instructions can be used for setting up a new document (replace MYNAME with your utu username):

$ git clone https://gitlab.utu.fi/ttweb/thesis
$ cd thesis
$ git remote add mythesis https://gitlab.utu.fi/MYNAME/mythesis
$ git push -u mythesis master

If you'd like to use the GitLab CI script, considering setting up the simplified CI pipeline that does not run the full test suite (invoke these commands in the root directory of the local repository):

$ cp .gitlab-ci-simple.yml .gitlab-ci.yml
$ rm -fr tests
$ git add -A
$ git ci -m 'Removed unnecessary testing.'
$ git push

Changes to the project will be pushed to your mythesis repository (invoke these commands in the root directory of the local repository):

$ touch test
$ git add test
$ git ci -m 'Just testing'
$ git remote -v
$ git push

Compiling the thesis

Latexmk (PdfTeX)

PdfTeX is the default engine for compiling the template. It offers better compatibility with most features.

When using latexmk, the project can be compiled like so:

$ latexmk -pdf -shell-escape thesis.tex

Latexmk (XeTeX)

XeTeX / XeLaTeX version is required if you want to use OpenType/TrueType fonts.

When using latexmk, XeLaTeX version can be compiled like so:

$ latexmk -xelatex -shell-escape thesis.tex

Source code listings

To minted=true functionality in the template requires Python3, Pygments + the LaTeX minted package for pretty printing the source code listings.

Validating PDF/A conformance

The VeraPDF tool can be used to validate the resulting document's PDF/A conformance.

Assuming a Java JRE (11 or later) distribution (e.g. AdoptOpenJDK) has been installed locally, the prebuilt validation tool can be used like this:

$ wget https://tech.utugit.fi/soft/thesis/veraPDF-apps/greenfield-apps-latest.jar
$ java -cp greenfield-apps-latest.jar org.verapdf.apps.GreenfieldCliWrapper --format text -v thesis.pdf

For a conforming document, built in the version=final mode, a successful run of the validation tool (pdfa-validate) will print a single line starting with "PASS". See the PDF/A page for further instructions.

Installing new TeX packages

The TexLive distribution provides a package manager of its own for installing extra TeX packages.