Translate the source code listings part and add note on shell escape

content/source-code-listings.tex

@@ -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}

exercises/source-code-listings/source-code-listings.done.tex

@@ -16,11 +16,11 @@
 \definecolor{ourBackgroundColor}{rgb}{0.1,0.1,0.2}
 
 \inputminted[
-  breaklines, % Zeilenumbrüche
-  linenos=true, % Zeilennummerierung
-  bgcolor=ourBackgroundColor, % Hintergrundfarbe
-  firstline=5, % erste Zeile
-  lastline=7, % letzte Zeile
-  gobble=4 % Leerzeichen entfernen
+  breaklines, % line breaks
+  linenos=true, % line numbers
+  bgcolor=ourBackgroundColor, % bbackground color
+  firstline=5, % first line to be included
+  lastline=7, % last line to be included
+  gobble=4 % remove leading spaces
 ]{java}{exercises/source-code-listings/Source.java}
 \end{minted}

exercises/source-code-listings/task.tex

@@ -1,19 +1,17 @@
-Im Ordner \mintinline{text}{exercises/source-code-listings} findet ihr eine Datei namens \mintinline{text}{Source.java}.
-Wir werden diese im Folgenden in unser Dokument einbinden und das Aussehen unseren Wünschen anpassen.
+You will find a file called \mintinline{text}{Source.java} in the folder \mintinline{text}{exercises/source-code-listings}.
+We will now include it into our document and adjust its display to fit our needs.
 
 \begin{enumerate}
-  \item Bindet die Datei an dieser Stelle ein.
-  \item Aktiviert Syntax-Highlighting durch Angabe der Sprache Java.
-  \item Lasst LaTeX zu lange Zeilen automatisch umbrechen.
-  \item Die Zeilen sollen nummeriert sein.
-  \item Nutzt das Theme \mintinline{latex}|native|.
-  \item Dieses Theme ist für einen dunklen Hintergrund optimiert. Ändert die Hintergrundfarbe des Themes zu dunkelblau.
-  \item Bindet jetzt ausschließlich die Zeilen 5 bis 7 ein.
-  \item Entfernt die Leerzeichen am Anfang der Zeilen durch Angabe der richtigen Option. (Hinweis: Die Dokumentation spricht hier von \mintinline{latex}|gobble|.)
+  \item Include the file into \mintinline{text}{exercises/source-code-listings/source-code-listings.tex}.
+  \item Activate syntax highlighting by stating the programming language Java.
+  \item Add line breaks and line numbers.
+  \item Use the theme \mintinline{latex}|native|.
+  \item This theme is optimized for a dark background. Change the background color to dark blue.
+  \item Include only lines 5 to 7.
+  \item Delete the spaces at the beginning of the lines by using a suitable option. (Hint: The documentation speaks of \mintinline{latex}|gobble|.)
 \end{enumerate}
 
-Konsultiert bei Fragen die Dokumentation des Paketes Minted.
+\noindent If you have questions, consult the minted package documentation.
 
 \exercisematerial{exercises/source-code-listings/source-code-listings}
 \usemintedstyle{} % Reset experiments from exercise material
-

listings/source-code-listings/minted-variants.tex

@@ -1,5 +1,5 @@
-% Kurzschreibweise
-Auch in der Kurzschreibweise erhält \mint{html}|<h2>LaTeX im Studium</h2>| eine eigene Zeile.
+% Shorthand
+Despite it is a shorthand, \mint{html}|<h2>LaTeX im Studium</h2>| will be rendered on its own line.
 
-% Inline-Umgebung
-Der Methodenaufruf \mintinline{java}{o.doSomething();} erscheint hingegen inline im Fließtext.
+% Inline variant
+The method call \mintinline{java}{o.doSomething();} on the other hand will appear inline.