From efdae30d72278675e5fb32d95e66077f6c4bd8d5 Mon Sep 17 00:00:00 2001 From: Florian Knoch Date: Sat, 8 Jan 2022 15:17:03 +0100 Subject: [PATCH] Add text description of the listings package --- content/source-code-listings-listings.tex | 29 +++++++ content/source-code-listings-minted.tex | 75 ++++++++++++++++++ content/source-code-listings.tex | 77 +------------------ .../listings-environment.tex | 3 + .../listings-import-styled.tex | 28 +++++++ .../source-code-listings/listings-import.tex | 1 + 6 files changed, 140 insertions(+), 73 deletions(-) create mode 100644 content/source-code-listings-listings.tex create mode 100644 content/source-code-listings-minted.tex create mode 100644 listings/source-code-listings/listings-environment.tex create mode 100644 listings/source-code-listings/listings-import-styled.tex create mode 100644 listings/source-code-listings/listings-import.tex diff --git a/content/source-code-listings-listings.tex b/content/source-code-listings-listings.tex new file mode 100644 index 0000000..9ec4ef3 --- /dev/null +++ b/content/source-code-listings-listings.tex @@ -0,0 +1,29 @@ +\section{Using listings} + +\subsection{Installation} +\pkg{listings} is a \LaTeX{} package of itself and does not require any additional installation. +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 and, unfortunately, it is not shipped with any pre-defined themes. +This makes configuration rather tedious.\footnote{Speaking of configuration, if you would like to specify your own colors, this page might help you: \url{https://mmoredo.github.io/latex-color-converter/}} + +The package is also a bit older than its alternative, causing UTF8 special characters to break. +If this happens to you, have a look at the \mono{literate} option of the \mono{lstset} command. 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 8592125..050ec15 100644 --- a/content/source-code-listings.tex +++ b/content/source-code-listings.tex @@ -3,77 +3,8 @@ 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. +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}. -\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. - -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. - - -\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} +\input{./content/source-code-listings-minted} +\input{./content/source-code-listings-listings} 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..ab6a7d3 --- /dev/null +++ b/listings/source-code-listings/listings-import-styled.tex @@ -0,0 +1,28 @@ + +\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} + +\lstdefinestyle{fswiai}{ + backgroundcolor=\color{backcolour}, + keywordstyle=\color{codeblue}, + identifierstyle=\color{codegreen}, + stringstyle=\color{codeyellow}, + basicstyle=\footnotesize\ttfamily\color{white}, + commentstyle=\color{codegray}, + numberstyle=\tiny\color{codegray}, + breakatwhitespace=false, + breaklines=true, + keepspaces=true, + numbers=left, + numbersep=5pt, + showstringspaces=false, + showtabs=false, + tabsize=1 +} + +\lstset{style=fswiai} + +\lstinputlisting[language=Java]{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..bbe49ae --- /dev/null +++ b/listings/source-code-listings/listings-import.tex @@ -0,0 +1 @@ +\lstinputlisting[language=Java]{listings/source-code-listings/Test.java}