87 lines
5.9 KiB
TeX
87 lines
5.9 KiB
TeX
\chapter{Source code listings}
|
|
\label{sec:source-code-listings}
|
|
|
|
There are many ways in \LaTeX{} to display source code.
|
|
We have come to appreciate the package \mintinline{latex}{minted}, which causes some additional installation overhead, but generates very appealing source code renderings.
|
|
|
|
\section{Installation}
|
|
Using \mintinline{latex}{minted} requires a working installation of the programming language Python 3 (henceforth referred to as Python).
|
|
On some operating systems, Python comes pre-installed, in which case entering the command \mintinline{bash}{python --version} or \mintinline{bash}{python3 --version} in a terminal of your choice\footnote{Opening a terminal on Windows: \faWindows\ + R → Type \enquote{cmd} → Enter} should print out the installed Python version.
|
|
|
|
If Python is yet to be installed, then you can find the installation files on the project website\footnote{Available at \url{https://www.python.org/downloads/}.}.
|
|
There are extensive articles that cover all relevant steps to install Python on
|
|
Windows,\footnote{Jason Fitzpatrick, How to Install Python on Windows. How-To
|
|
Geek. July 11, 2017. Available at
|
|
\url{https://www.howtogeek.com/197947/how-to-install-python-on-windows/}.
|
|
Windows users will have to adjust the system path. Forgetting this step has
|
|
been the number one installation problem in past workshops.}
|
|
Linux,\footnote{\url{https://docs.python-guide.org/starting/install3/linux/}}
|
|
or macOS.\footnote{\url{https://docs.python-guide.org/starting/install3/osx/}}
|
|
|
|
After a successful installation, you should be able to execute the aforementioned command in a terminal, confirm by pressing Enter, and see approximately the following result:
|
|
|
|
\begin{minted}[]{bash}
|
|
$ python --version
|
|
Python 3.8.5
|
|
\end{minted}
|
|
|
|
\noindent If the version number is equal to the one stated here, or higher, then everything should be set up correctly.
|
|
Next, enter the command \mintinline{bash}{pip install Pygments}\footnote{On some operating systems, you might have to use the command \mintinline{bash}{pip3 install Pygments}} in the same terminal window to install the Pygments package for Python.
|
|
Once the installation is complete, you are ready to include the \LaTeX{} package \mintinline{latex}{minted} into your documents by adding \mintinline{latex}{\usepackage{minted}} to your preamble.
|
|
|
|
|
|
\section{Changing the compiler command}
|
|
There is one last adjustment needed before you can actually compile your documents---we will have to adjust the compile command.
|
|
Out of the box, your editor will probably execute the following command after you clicked the green compile arrow:
|
|
|
|
\begin{minted}[]{bash}
|
|
$ pdflatex main.tex
|
|
\end{minted}
|
|
|
|
\noindent The exact command can be found and configured in \TeX{}studio under Options → Configure \TeX{}studio → Commands.
|
|
It is stated next to the label Pdf\LaTeX{}.
|
|
The file that is to be compiled will replace the placeholder \mintinline{bash}{%.tex} upon compilation.
|
|
Additionally, there are typically two additional options configured.
|
|
You can recognize them by the hyphen before their names (\mintinline{bash}{-synctex=1 -interaction=nonstopmode}).
|
|
These options are called flags and configure the program \mintinline{bash}{pdflatex}.
|
|
We will have to add another flag.
|
|
Place the string \mintinline{bash}{-shell-escape} before the file placeholder (\mintinline{bash}{%.tex}):
|
|
|
|
\begin{minted}[]{bash}
|
|
pdflatex -synctex=1 -interaction=nonstopmode -shell-escape %.tex
|
|
\end{minted}
|
|
|
|
\noindent After a click on \enquote{Okay} the configuration is finished.
|
|
Other editors usually provide similar options to configure the compilation command.
|
|
We recommend you to have a look at the settings or to use of a search engine to figure it out.
|
|
|
|
\paragraph{An important note on the shell escape flag.} \mintinline{bash}{minted}'s syntax highlighting is done by a Python package, which adds the necessity to communicate between the compiler and the Python runtime.
|
|
The shell escape flag adds this communication path.
|
|
When enabled, \LaTeX{} can execute any command in a terminal, which can be very useful.
|
|
Nonetheless, it would also be possible to execute malign code on your computer via \LaTeX{}, especially when you are compiling unknown documents from the Internet.
|
|
Therefore, do not compile downloaded documents with the shell escape flag if you do not trust the authors and did not check the packages and commands they include.
|
|
|
|
\section{Defining listings}
|
|
We are finally ready to marvel at the aesthetic quality of the listings \mintinline{bash}{minted} produces.
|
|
You can define listings using a dedicated environment:
|
|
|
|
\example{lst:minted-environment}{source-code-listings/minted-environment}{Examplary source code listing}
|
|
|
|
\example{lst:minted-variants}{source-code-listings/minted-variants}{Shorthand and inline listing}
|
|
|
|
\noindent There is also a shorthand and an inline variant of the command (cf.\ \cref{lst:minted-variants}).
|
|
To avoid redundancy, it may be practical to import source code directly from the source file.
|
|
To accomplish this, we only have to pass the programming language and the file path to the \mintinline{latex}{\inputminted} command (cf.\ \cref{lst:minted-external}).
|
|
|
|
\example{lst:minted-external}{source-code-listings/minted-import}{Including from a separate file}
|
|
|
|
\todo{Fix overflow issue in the listing}
|
|
|
|
\section{Configuring minted}
|
|
|
|
Optional parameters allow us to add line numbers, line breaks, and colors.
|
|
Moreover, there are numerous themes available (\todo{Anscheinend sind crefs nicht wirklich mit english spacing kompatibel. Können wir das abschalten? Gibt eigentlich eh keinen guten Grund dafür.)}\cref{lst:minted-external-styled}).
|
|
The introduction on Overleaf and the package documentation\footnote{Available at \url{https://www.overleaf.com/learn/latex/Code_Highlighting_with_minted} and \url{https://ctan.kako-dev.de/macros/latex/contrib/minted/minted.pdf}, respectively.} give an extensive overview.
|
|
|
|
\example{lst:minted-external-styled}{source-code-listings/minted-import-styled}{Themes and further options}
|