latex/latex-skript
5
0
Fork 0
Code Issues 2 Pull Requests Releases 2 Wiki Activity

Add text description of the listings package

Browse Source
This commit is contained in:
Knoch 2022-01-08 15:17:03 +01:00
parent 6d6e7e6ab9
commit efdae30d72
6 changed files with 140 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
content/source-code-listings-listings.tex Normal file
View File

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

75
content/source-code-listings-minted.tex Normal file
View File

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

77
content/source-code-listings.tex
View File

@ -3,77 +3,8 @@
There are many ways in \LaTeX{} to display source code. 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. 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} \input{./content/source-code-listings-minted}
Using \pkg{minted} requires a working installation of the programming language Python 3 (henceforth referred to as Python). \input{./content/source-code-listings-listings}
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}

3
listings/source-code-listings/listings-environment.tex Normal file
View File

@ -0,0 +1,3 @@
\begin{lstlisting}[language=Haskell]
[x^2 | x <- [1..200], even x]
\end{lstlisting}

28
listings/source-code-listings/listings-import-styled.tex Normal file
View File

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

1
listings/source-code-listings/listings-import.tex Normal file
View File

@ -0,0 +1 @@
\lstinputlisting[language=Java]{listings/source-code-listings/Test.java}