latex-wochenende/slides/chapter-10.en.md

@slide(layout=chapter-slide)

@title
Source code listings

@slide(layout=content-only)

@title
Our options

@content
There are two popular ways to display source code in a LaTeX document.

* ++ **`minted`** renders **very pretty** source code listings, but it requires some **extra configuration** and might not work on every operating system.
* ++ **`listings`** is an **easy-to-use** (but not as pretty) option for those having troubles with `minted`.

++ Their commands are very similar.

@slide(layout=content-and-preview)

@title
Installation <span class="emoji">🖥️</span>

@content
`minted` requires the Python programming language. As soon as **[Python is installed](https://www.python.org/)**, we can download the corresponding Python package **[`Pygments`](http://pygments.org/)** using a command prompt:

``` {.lang-sh .hljs}
pip install Pygments
```

Add the LaTeX packages for `minted` or `listings` and we are good to go:

``` {.lang-tex .hljs}
\usepackage{minted}
\usepackage{listings}
```

@preview
![](svg/chapter-10/minted-overview-english-crop.svg){ .thin-padding }

@slide(layout=content-only)

@title
Compiler settings

@content
<div class="box warning">
  We need to pass the additional flag `--shell-escape` to our compiler in order to use `minted`.<br />
  <strong>Do this only for documents you trust!</strong>
</div>

In TeXstudio, go to **`Options → Configure TeXstudio → Commands`** (`TeXstudio → Settings` on macOS) and add the flag in the PdfLaTeX row before `%.tex`:

<code>pdflatex -synctex=1 -interaction=nonstopmode **\-\-shell-escape** %.tex</code>


@slide(layout=content-only)

@title
A note on our script

@content
Our exercise material allows you to choose between `minted` and `listings`. 
By default, we use `listings`. 
To activate `minted`, create a file called `listings-mode.tex` in the project's root directory and add the following line:

```{.lang-tex .hljs}
\newcommand\listingsmode{minted}
```

After compiling again, your listings should be rendered by `minted`. 


@slide(layout=content-and-preview-with-category)

@category
minted

@title
In-situ listings

@content
++ Within a dedicated environment:

``` {.lang-tex .hljs .fragment}
\section*{Haskell Magic}
Squares of all even % …
\begin{minted}{haskell}
[x^2 | x <- [1..200], even x]
\end{minted}
```

++ Directly inline:

``` {.lang-tex .hljs .fragment}
\section*{An HTML Example}
A headline is denoted the following way:
\mint{html}|<h2>LaTeX at University</h2>|
```

@preview
![](svg/chapter-10/minted-haskell-english-crop.svg)


@slide(layout=content-and-preview-with-category)

@category
minted

@title
External source code

@content
We can avoid redundancy by including source code directly from its source file.

``` {.lang-tex .hljs}
\section*{Simple Java Application}
\inputminted{java}{Test.java}
```

``` {.lang-java .hljs data-sourcefile="Test.java"}
public class Test {
    public static void main(/*…*/) {
        System.out.println(/*…*/);
    }
}
```

@preview
![](svg/chapter-10/minted-java-english-crop.svg)


@slide(layout=content-only-with-category)

@category
minted

@title
Themes and styles

@content
Optional parameters allow us to activate line numbers, automated line breaks, and syntax highlighting based on numerous color schemes.

``` {.lang-tex .hljs}
\usemintedstyle{monokai}
\begin{minted}[
linenos=true,
breaklines=true,
]{javascript}
    % ...
\end{minted}
```

<span class="emoji">🔗</span> **[introduction](https://www.overleaf.com/learn/latex/Code_Highlighting_with_minted)** and **[official documentation](https://ctan.kako-dev.de/macros/latex/contrib/minted/minted.pdf)**


@slide(layout=content-and-preview-with-category)

@category
listings

@title
In-situ listings

@content
Within a dedicated environment:

``` {.lang-tex .hljs}
\section*{Haskell Magic}
Squares of all even % …
\begin{lstlisting}[language=Haskell]
[x^2 | x <- [1..200], even x]
\end{lstlisting}
```

The `listings` package does not provide an inline command.

@preview
![](svg/chapter-10/listings-haskell-english-crop.svg)


@slide(layout=content-and-preview-with-category)

@category
listings

@title
External source code

@content
Conveniently, also `listings` offers an import command:

``` {.lang-tex .hljs}
\section*{Simple Java Application}
\lstinputlisting[language=Java]{Test.java}
```

``` {.lang-java .hljs data-sourcefile="Test.java"}
public class Test {
    public static void main(/*…*/) {
        System.out.println(/*…*/);
    }
}
```

@preview
![](svg/chapter-10/listings-java-english-crop.svg)


@slide(layout=content-only-with-category)

@category
listings

@title
Themes and styles

@content
`listings` does not provide any themes by default, but can be configured extensively.

``` {.lang-tex .hljs}
\begin{lstlisting}[
    language=Java,
    basicstyle=\footnotesize\ttfamily,
    breaklines=true,
    keywordstyle=\color{ForestGreen},
    commentstyle=\color{DarkGray},
    literate={ö}{{\"o}}1
]
% …
\end{lstlisting}
```

Have a look at the `\lstset` command for creating your own themes.


@slide(layout=content-only-with-category)

@category
listings

@title
Further resources

@content
* [introduction](https://www.overleaf.com/learn/latex/Code_listing#Reference_guide) to the package
* official [documentation](https://www.overleaf.com/learn/latex/Code_listing#Reference_guide)
* [`xcolor` package](https://www.overleaf.com/learn/latex/Using_colours_in_LaTeX) for colors
* two [solarized themes](https://github.com/jez/latex-solarized) for `listings`


@slide(layout=task)

@task-number
10

@title
Listings with `minted`

@content
* In the directory `exercises/source-code-listings` you can find a file named `Source.java`.
* **Include** it in the file `source-code-listings.tex`. (Keep in mind that the file path is relative to the main LaTeX document, i.&thinsp;e., to `main.tex`.)
* Activate **syntax highlighting** by stating the programming language Java.
* **Number** the code lines and add **line breaks**.
* Use the **theme** `native`.
* Change the **background colour** to dark blue. 
* Now only include **lines 5 to 7**.
* Delete the **spaces** at the beginning of the lines. (Hint: The documentation speaks of `autogobble`).

If you have questions, try to consult the documentation of the `minted` package.

@slide(layout=task)

@task-number
10

@title
Listings with `listings`

@content
* In the directory `exercises/source-code-listings` you can find a file named `Source.java`.
* **Include** it in the file `source-code-listings.tex`. (Keep in mind that the file path is relative to the main LaTeX document, i.&thinsp;e., to `main.tex`.)
* Activate **syntax highlighting** by stating the programming language Java.
* **Number** the code lines.
* Set the `basicstyle` to a proper mono-spaced font (`\ttfamily \small`)
* Change the **keyword color** to blue.
* Don't show special characters for **spaces in strings**.

If you have questions, try to consult the documentation of the `listings` package.