|
|
|
|
@ -1,69 +1,79 @@
|
|
|
|
|
\chapter{Quelltext-Listings}
|
|
|
|
|
\chapter{Source code listings}
|
|
|
|
|
\label{sec:source-code-listings}
|
|
|
|
|
|
|
|
|
|
Um Quelltext in eigenen Arbeiten darzustellen, gibt es in \LaTeX verschiedene Wege.
|
|
|
|
|
Wir verwenden hierfür gern das Paket \mintinline{latex}{minted}, das zwar etwas zusätzlichen Installationsaufwand verursacht, dafür aber ansprechende Ergebnisse generiert und gut zu handhaben ist.
|
|
|
|
|
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}
|
|
|
|
|
Zur Verwendung von \mintinline{latex}{minted} ist eine Installation der Programmiersprache Python 3 notwendig. Je nachdem, welches Betriebsystem ihr nutzt, kann es sein, dass Python 3 bei euch schon installiert ist. Das könnt ihr durch die Engabe des Befehls \mintinline{bash}{python --version} oder \mintinline{bash}{python3 --version} in einem Terminal\footnote{Navigation unter Windows: \faWindows\ + R → \enquote{cmd} eingeben → Enter} herausfinden
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Sollte Python bei euch noch nicht installiert sein, sind die Installationsdateien auf der Projekt-Website\footnote{Verfügbar unter \url{https://www.python.org/downloads/}.} zu finden.
|
|
|
|
|
Ein ausführlicherer Beitrag zur Installation unter Windows,\footnote{Jason Fitzpatrick, How to Install Python on Windows. How-To Geek. July 11, 2017. Verfügbar unter \url{https://www.howtogeek.com/197947/how-to-install-python-on-windows/}.} Linux\footnote{ \url{https://docs.python-guide.org/starting/install3/linux/}} oder MacOS\footnote{\url{https://docs.python-guide.org/starting/install3/osx/}} führt euch durch die verschiedenen Schritte, die speziell für euer Betriebssystem notwendig sind.\footnote{Insbesondere das Anpassen des Systempfads sollte unter Windows nicht vergessen werden.}
|
|
|
|
|
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/}}.
|
|
|
|
|
|
|
|
|
|
Nach der erfolgreichen Installation solltet ihr, je nach Betriebssystem, in der Eingabeaufforderung den oben genannten Befehl noch mal eingeben und mit Enter bestätigen können und in etwa folgendes Ergebnis erhalten:
|
|
|
|
|
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 Sollte die Versionsnummer höher sein, ist alles bestens.
|
|
|
|
|
Im gleichen Fenster gebt ihr jetzt den Befehl \mintinline{bash}{pip install Pygments}\footnote{Achtung: In einigen Betriebssystem lautet der Befehl \mintinline{bash}{pip3 install Pygments}} ein, womit das Pygments-Paket für Python installiert wird.
|
|
|
|
|
Nach Abschluss dieses Vorgangs könnt ihr das \LaTeX-Paket \mintinline{latex}{minted} über \mintinline{latex}{\usepackage{minted}} einbinden.
|
|
|
|
|
\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{Compiler-Befehl ändern}
|
|
|
|
|
Bevor es allerdings richtig losgehen kann, müssen wir noch eine Kleinigkeit im Compile-Prozess anpassen.
|
|
|
|
|
Normalerweise ruft euer Editor beim Klick auf den grünen Pfeil etwa den folgenden Befehl auf:
|
|
|
|
|
\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 Welcher Befehl das bei euch genau ist, könnt ihr in \TeX{}studio unter \enquote{Optionen → \TeX{}studio konfigurieren → Befehle} einsehen.
|
|
|
|
|
Neben Pdf\LaTeX{} seht ihr den Befehl.
|
|
|
|
|
Die Datei, die kompiliert werden soll, wird hier durch \mintinline{bash}{%.tex} angegeben.
|
|
|
|
|
Außerdem sind üblicherweise noch zwei zusätzliche Angaben enthalten, jeweils mit einem Bindestrich davor (\mintinline{bash}{-synctex=1 -interaction=nonstopmode}).
|
|
|
|
|
Diese Angaben heißen Flags und konfigurieren das Programm \mintinline{bash}{pdflatex}.
|
|
|
|
|
Eine solche Flag müssen wir ergänzen.
|
|
|
|
|
Platziert die Angabe \mintinline{bash}{-shell-escape} vor der Datei-Angabe (\mintinline{bash}{%.tex}):
|
|
|
|
|
\noindent The exact command can be found and configured in \TeX{}studio under \enquote{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 Nach Klick auf \enquote{Okay} ist der Einrichtungsschritt abgeschlossen.
|
|
|
|
|
Auch andere Editoren bieten die Möglichkeit, den Kompilierbefehl anzupassen.
|
|
|
|
|
Schaut am besten mal in die Einstellungen oder bemüht eine Suchmaschine.
|
|
|
|
|
\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.
|
|
|
|
|
|
|
|
|
|
\section{Quelltext setzen}
|
|
|
|
|
Jetzt kann der eigentliche Spaß losgehen.
|
|
|
|
|
Quelltext könnt ihr von nun an unter Angabe der Sprache in einer eigenen Umgebung setzen:
|
|
|
|
|
\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.
|
|
|
|
|
|
|
|
|
|
\example{lst:minted-environment}{source-code-listings/minted-environment}{Beispielhaftes Quelltext-Listing}
|
|
|
|
|
\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-variants}{source-code-listings/minted-variants}{Kurzschreibweise und Inline-Listing}
|
|
|
|
|
\example{lst:minted-environment}{source-code-listings/minted-environment}{Examplary source code listing}
|
|
|
|
|
|
|
|
|
|
\noindent Außerdem gibt es eine Kurzschreibweise und eine Inline-Variante des Befehls (vgl. \cref{lst:minted-variants}).
|
|
|
|
|
Um Redundanz zu vermeiden, ist es manchmal praktisch, den Quelltext direkt aus der Quelldatei einzulesen.
|
|
|
|
|
Hierzu müssen nur die verwendete Programmiersprache und der Dateipfad an den Befehl \mintinline{latex}{\inputminted} übergeben werden (vgl. \cref{lst:minted-external}).
|
|
|
|
|
\example{lst:minted-variants}{source-code-listings/minted-variants}{Shorthand and inline listing}
|
|
|
|
|
|
|
|
|
|
\example{lst:minted-external}{source-code-listings/minted-import}{Einbinden aus einer externen Datei}
|
|
|
|
|
\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}).
|
|
|
|
|
|
|
|
|
|
\section{Minted konfigurieren}
|
|
|
|
|
\example{lst:minted-external}{source-code-listings/minted-import}{Including from a separate file}
|
|
|
|
|
|
|
|
|
|
Durch optionale Parameter können Zeilennummerierung, Umbrüche und Farben ausgewählt werden.
|
|
|
|
|
Außerdem sind zahlreiche Themes verfügbar (\cref{lst:minted-external-styled}).
|
|
|
|
|
Einen umfänglichen Überblick geben die Einführung von Overleaf und die Dokumentation.\footnote{Verfügbar unter \url{https://www.overleaf.com/learn/latex/Code_Highlighting_with_minted} bzw. \url{https://ctan.kako-dev.de/macros/latex/contrib/minted/minted.pdf}.}
|
|
|
|
|
\todo{Fix overflow issue in the listing}
|
|
|
|
|
|
|
|
|
|
\example{lst:minted-external-styled}{source-code-listings/minted-import-styled}{Themes und weitere Optionen}
|
|
|
|
|
\section{Configuring minted}
|
|
|
|
|
|
|
|
|
|
Optional parameters allow us to add line numbers, line breaks, and colors.
|
|
|
|
|
Moreover, there are numerous themes available (\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}
|
|
|
|
|
|
