From ee9d97c138fa672fe80718c2b63f34a93cbafaa9 Mon Sep 17 00:00:00 2001 From: Florian Knoch Date: Wed, 23 Jun 2021 10:02:12 +0200 Subject: [PATCH] Translate the source code listings part and add note on shell escape --- content/source-code-listings.tex | 84 +++++++++++-------- .../source-code-listings.done.tex | 12 +-- exercises/source-code-listings/task.tex | 22 +++-- .../source-code-listings/minted-variants.tex | 8 +- 4 files changed, 67 insertions(+), 59 deletions(-) diff --git a/content/source-code-listings.tex b/content/source-code-listings.tex index 8cf051e..010e4d0 100644 --- a/content/source-code-listings.tex +++ b/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} diff --git a/exercises/source-code-listings/source-code-listings.done.tex b/exercises/source-code-listings/source-code-listings.done.tex index 9a12b66..7dc564a 100644 --- a/exercises/source-code-listings/source-code-listings.done.tex +++ b/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} \ No newline at end of file diff --git a/exercises/source-code-listings/task.tex b/exercises/source-code-listings/task.tex index ec3b5af..fa00f73 100644 --- a/exercises/source-code-listings/task.tex +++ b/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 - diff --git a/listings/source-code-listings/minted-variants.tex b/listings/source-code-listings/minted-variants.tex index cc81e32..6529b0b 100644 --- a/listings/source-code-listings/minted-variants.tex +++ b/listings/source-code-listings/minted-variants.tex @@ -1,5 +1,5 @@ -% Kurzschreibweise -Auch in der Kurzschreibweise erhält \mint{html}|

LaTeX im Studium

| eine eigene Zeile. +% Shorthand +Despite it is a shorthand, \mint{html}|

LaTeX im Studium

| will be rendered on its own line. -% Inline-Umgebung -Der Methodenaufruf \mintinline{java}{o.doSomething();} erscheint hingegen inline im Fließtext. \ No newline at end of file +% Inline variant +The method call \mintinline{java}{o.doSomething();} on the other hand will appear inline. \ No newline at end of file