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:
-
Windows: https://miktex.org/
-
Linux/BSD: https://www.tug.org/texlive/
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 utuftlabreport.layout document class description file
for the same utuftlabreport.cls as the one used by TeX documents.
Start by editing the provided exercise.lyx. The file has been configured
to use the custom utuftlabreport 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, but it is often sufficient for simple lab reports.
Note: the more advanced LaTeX macros need to be passed through Pandoc, which kind of defeats the whole purpose of using simplified markdown notation in the first place.
In order to use Pandoc, install the following packages
pandoc, pandoc-citeproc, pandoc-crossref, python3, and
python3-pandocfilters.
Extra tools
The minted package is enabled by default. In order to compile program
listings using minted, install the following extra packages:
python3 and python3-pygments.
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/tech/education/misc/template-labreport
$ cd template-labreport
$ git remote add mylabreport https://gitlab.utu.fi/MYNAME/mylabreport
$ git push -u mylabreport 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. One can use the original CI script as a starting point.
Changes to the project will be pushed to your mylabreport 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
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 -output-directory=. exercise.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 -output-directory=. exercise.tex
Pandoc
The Pandoc version allows easily writing reports using Markdown syntax.
When using pandoc, XeLaTeX version can be compiled like so:
$ pandoc exercise.md --top-level-division=chapter -F pandoc-minted.py -F pandoc-citeproc -s --template utuftlabreport.pandoc -o exercise.tex
$ latexmk -xelatex -shell-escape -output-directory=. exercise.tex