diff --git a/content/source-code-listings-listings.tex b/content/source-code-listings-listings.tex new file mode 100644 index 0000000..20a5563 --- /dev/null +++ b/content/source-code-listings-listings.tex @@ -0,0 +1,32 @@ +\newpage +\section{Using listings} + +\subsection{Installation} +\pkg{listings} is a \LaTeX{} package of itself and does not require any additional installation as long as the \pkg{xcolor} package is installed as well. +We can therefore jump straight into typesetting source code. + +\subsection{Defining listings} +Similar to \pkg{minted}, you can define listings using a dedicated environment (cf.\ \cref{lst:listings-environment}) and you can use another command to import source code directly from external files (cf.\ \cref{lst:listings-external}). + +\example{lst:listings-environment}{source-code-listings/listings-environment}{Exemplary source code listing} +\example{lst:listings-external}{source-code-listings/listings-import}{Including from a separate file} + +\noindent Both commands need a language specification\footnote{See this guide on Overleaf for a list of all languages: \url{https://www.overleaf.com/learn/latex/Code_listing\#Reference_guide}} as an optional parameter to apply syntax highlighting. + +\subsection{Configuring listings} +The \pkg{listings} package can also be tweaked in an almost infinite number of ways. +Numerous optional parameters give you a lot of freedom. + +Once again, Overleaf and the package documentation\footnote{Available at \url{https://www.overleaf.com/learn/latex/Code_listing\#Code_styles_and_colours} and \url{https://ctan.org/pkg/listings}, respectively.} come in handy. + +\example{lst:listings-external-styled}{source-code-listings/listings-import-styled}{Themes and further options} + +\subsection{Drawbacks and caveats} +As mentioned earlier, \pkg{listings} is not our first choice for source code listings. +Its renderings are of rather peculiar appearance. + +With some amount of configuration, we can overcome the most disturbing default settings. +Although \pkg{listings} is not shipped with any pre-defined themes, you can define your own and use them throughout your project with the \mono{lstdefinestyle} command.\footnote{Have a look at it in the package documentation. For the very impatient, here is a solarized theme for \pkg{listings}: \url{https://github.com/jez/latex-solarized}} + +The package is also a bit older than its alternative, causing \acro{UTF8} special characters to break. +If this happens to you, have a look at the \mono{literate} option of the \pkg{listings} commands. diff --git a/content/source-code-listings-minted.tex b/content/source-code-listings-minted.tex new file mode 100644 index 0000000..4e5b0f9 --- /dev/null +++ b/content/source-code-listings-minted.tex @@ -0,0 +1,75 @@ +\section{Using minted} + +\subsection{Installation} +Using \pkg{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 \sh{python --version} or \sh{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 \sh{pip install Pygments}\footnote{On some operating systems, you might have to use the command \sh{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 \pkg{minted} into your documents by adding \code{latex}{\textbackslash usepackage\{minted\}} to your preamble. + + +\subsection{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: + +\shell{pdflatex main.tex} + +\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 \sh{\%.tex} upon compilation. +Additionally, there are typically two additional options configured. +You can recognize them by the hyphen before their names (\sh{-synctex=1 -interaction=nonstopmode}). +These options are called flags and configure the program \sh{pdflatex}. +We will have to add another flag. +Place the string \sh{-shell-escape} before the file placeholder (\sh{\%.tex}): + +\shell{pdflatex -synctex=1 -interaction=nonstopmode -shell-escape \%.tex} + +\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.} \pkg{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. + +\subsection{Defining listings} +We are finally ready to marvel at the aesthetic quality of the listings \pkg{minted} produces. +You can define listings using a dedicated environment: + +\example{lst:minted-environment}{source-code-listings/minted-environment}{Exemplary 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 \code{latex}{\textbackslash inputminted} command (cf.\ \cref{lst:minted-external}). + +\example{lst:minted-external}{source-code-listings/minted-import}{Including from a separate file} + +\subsection{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} \ No newline at end of file diff --git a/content/source-code-listings.tex b/content/source-code-listings.tex index 844cb38..96d10b3 100644 --- a/content/source-code-listings.tex +++ b/content/source-code-listings.tex @@ -4,73 +4,14 @@ There are many ways in \LaTeX{} to display source code. We have come to appreciate the package \pkg{minted}, which causes some additional installation overhead, but generates very appealing source code renderings. -\section{Installation} -Using \pkg{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 \sh{python --version} or \sh{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. +However, especially on macOS, the installation of minted has caused a lot of headache in the early days of this workshop. +That's why we will also have a look at an alternative called \pkg{lstlistings}. -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/}} +\paragraph{A note on colors.} Both of these packages require you to define colors. +We can recommend using the \pkg{xcolor} package. +There are very helpful resources\footnote{If you would like to specify your own colors , these pages might help you: \url{https://www.overleaf.com/learn/latex/Using_colours_in_LaTeX} for a list of pre-defined colors in the \pkg{xcolor} package, \url{https://mmoredo.github.io/latex-color-converter/} for defining your own colors} available online such that we will not go into details here. -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: +\input{./content/source-code-listings-minted} +\input{./content/source-code-listings-listings} -\codeblock{bash}{listings/source-code-listings/python-version.sh} - -\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 \sh{pip install Pygments}\footnote{On some operating systems, you might have to use the command \sh{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 \pkg{minted} into your documents by adding \code{latex}{\textbackslash 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: - -\shell{pdflatex main.tex} - -\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 \sh{\%.tex} upon compilation. -Additionally, there are typically two additional options configured. -You can recognize them by the hyphen before their names (\sh{-synctex=1 -interaction=nonstopmode}). -These options are called flags and configure the program \sh{pdflatex}. -We will have to add another flag. -Place the string \sh{-shell-escape} before the file placeholder (\sh{\%.tex}): - -\shell{pdflatex -synctex=1 -interaction=nonstopmode -shell-escape \%.tex} - -\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.} \pkg{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 \pkg{minted} produces. -You can define listings using a dedicated environment: - -\example{lst:minted-environment}{source-code-listings/minted-environment}{Exemplary 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 \code{latex}{\textbackslash inputminted} command (cf.\ \cref{lst:minted-external}). - -\example{lst:minted-external}{source-code-listings/minted-import}{Including from a separate file} - -\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} +\todo{Are the files minted.done.tex and listings.done.tex available in the solution-free zip? They should not.} diff --git a/exercises/source-code-listings/listings.done.tex b/exercises/source-code-listings/listings.done.tex new file mode 100644 index 0000000..036ff19 --- /dev/null +++ b/exercises/source-code-listings/listings.done.tex @@ -0,0 +1,7 @@ +\lstinputlisting[ + language=Java, + numbers=left, % line numbers + showstringspaces=false, % spaces in strings + keywordstyle=\color{blue}, % keyword color + basicstyle=\ttfamily\small % overall font and size +]{exercises/source-code-listings/Source.java} \ No newline at end of file diff --git a/exercises/source-code-listings/minted.done.tex b/exercises/source-code-listings/minted.done.tex new file mode 100644 index 0000000..d5df579 --- /dev/null +++ b/exercises/source-code-listings/minted.done.tex @@ -0,0 +1,13 @@ +\usemintedstyle{native} +\definecolor{ourBackgroundColor}{rgb}{0.1,0.1,0.2} + +\inputminted[ + breaklines, % line breaks + linenos=true, % line numbers + bgcolor=ourBackgroundColor, % background 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} + +\usemintedstyle{default} \ No newline at end of file diff --git a/exercises/source-code-listings/source-code-listings.done.tex b/exercises/source-code-listings/source-code-listings.done.tex index fd037e3..1fdc073 100644 --- a/exercises/source-code-listings/source-code-listings.done.tex +++ b/exercises/source-code-listings/source-code-listings.done.tex @@ -1,26 +1,15 @@ -\usemintedstyle{native} -\definecolor{ourBackgroundColor}{rgb}{0.1,0.1,0.2} +% Show rendering with respect to the installed software +\ifthenelse{\equal{\listingsmode}{minted}}{% + \subsubsection{Minted rendering} + \input{exercises/source-code-listings/minted.done.tex} +}{% + \subsubsection{Listings rendering} + \input{exercises/source-code-listings/listings.done.tex} +} -\inputminted[ - breaklines, - linenos=true, - bgcolor=ourBackgroundColor, - firstline=5, - lastline=7, - gobble=4 -]{java}{exercises/source-code-listings/Source.java} +\subsubsection{Minted solution} +\codeblock{latex}{./exercises/source-code-listings/minted.done.tex} -\usemintedstyle{default} -\begin{minted}{latex} -\usemintedstyle{native} -\definecolor{ourBackgroundColor}{rgb}{0.1,0.1,0.2} +\subsubsection{Listings solution} +\codeblock{latex}{./exercises/source-code-listings/listings.done.tex} -\inputminted[ - breaklines, % line breaks - linenos=true, % line numbers - bgcolor=ourBackgroundColor, % background 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 f3f3f37..433f1b5 100644 --- a/exercises/source-code-listings/task.tex +++ b/exercises/source-code-listings/task.tex @@ -1,6 +1,9 @@ You will find a file called \file{Source.java} in the folder \file{exercises/source-code-listings}. We will now include it into our document and adjust its display to fit our needs. +If you have questions, consult the \pkg{minted} or \pkg{listings} package documentation. + +\section*{Minted tasks} \begin{enumerate} \item Include the file into @@ -14,7 +17,17 @@ We will now include it into our document and adjust its display to fit our needs option. (Hint: The documentation speaks of \code{latex}{gobble}.) \end{enumerate} -\noindent If you have questions, consult the minted package documentation. +\section*{Listings tasks} + +\begin{enumerate} + \item Include the file into + \file{exercises/source-code-listings/source-code-listings.tex}. + \item Activate syntax highlighting by stating the programming language Java. + \item Set the \mono{basicstyle} to a proper mono-spaced font (\mono{\textbackslash ttfamily \textbackslash small}) + \item Add line numbers. + \item Change the keyword color to blue. + \item Include only lines 5 to 7. +\end{enumerate} \exercisematerial{exercises/source-code-listings/source-code-listings} \usemintedstyle{} % Reset experiments from exercise material diff --git a/listings/source-code-listings/Test.java b/listings/source-code-listings/Test.java index 79b7c35..d0028a0 100644 --- a/listings/source-code-listings/Test.java +++ b/listings/source-code-listings/Test.java @@ -1,5 +1,5 @@ public class Test { - public static void main(/*…*/) { + public static void main(/*...*/) { System.out.println("Welcome, " + "fellow LaTeX learners!"); } diff --git a/listings/source-code-listings/listings-environment.tex b/listings/source-code-listings/listings-environment.tex new file mode 100644 index 0000000..00ea32e --- /dev/null +++ b/listings/source-code-listings/listings-environment.tex @@ -0,0 +1,3 @@ +\begin{lstlisting}[language=Haskell] + [x^2 | x <- [1..200], even x] +\end{lstlisting} \ No newline at end of file diff --git a/listings/source-code-listings/listings-import-styled.tex b/listings/source-code-listings/listings-import-styled.tex new file mode 100644 index 0000000..365e94e --- /dev/null +++ b/listings/source-code-listings/listings-import-styled.tex @@ -0,0 +1,21 @@ + +\definecolor{codegray}{rgb}{0.5,0.5,0.5} +\definecolor{codegreen}{rgb}{0.65,0.89,0.18} +\definecolor{codeyellow}{rgb}{0.9,0.86,0.45} +\definecolor{codeblue}{rgb}{0.36,0.76,0.85} +\definecolor{backcolour}{rgb}{0.1,0.1,0.2} + +\lstinputlisting[ + language=Java, + backgroundcolor=\color{backcolour}, + keywordstyle=\color{codeblue}, + identifierstyle=\color{codegreen}, + stringstyle=\color{codeyellow}, + basicstyle=\footnotesize + \ttfamily\color{white}, + commentstyle=\color{codegray}, + numberstyle=\tiny\color{codegray}, + numbers=left, + numbersep=5pt, + showstringspaces=false, +]{listings/source-code-listings/Test.java} diff --git a/listings/source-code-listings/listings-import.tex b/listings/source-code-listings/listings-import.tex new file mode 100644 index 0000000..466742f --- /dev/null +++ b/listings/source-code-listings/listings-import.tex @@ -0,0 +1,2 @@ +\lstinputlisting[language=Java] + {listings/source-code-listings/Test.java}