\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{Pawandeep, How to install Python in Windows?. Tutorialspoint. March 10, 2021. Available at 
\url{https://www.tutorialspoint.com/how-to-install-python-in-windows}. 
Windows users will have to adjust the system path during the installation process. 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: 

\shell{python -{}-version \\ Python 3.8.5}

\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 Pdf\LaTeX{} label.
The file that is to be compiled will replace the placeholder \sh{\%.tex} upon compilation.
Typically, there are two additional options configured.
You can recognize them by the hyphen before their names (\sh{-synctex=1} and \sh{-interaction=\allowbreak{}nonstopmode}).
These options are called flags and they 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:

% Render listing directly, if minted is available.
% Otherwise, include pre-rendered images.
\ifthenelse{\equal{\listingsmode}{minted}}{%
  \example{lst:minted-environment}{source-code-listings/minted-environment}{Exemplary source code listing}
  }{%
  \Example{lst:minted-environment}{source-code-listings/minted-environment}{source-code-listings/minted-environment_crop}{Exemplary source code listing}
}

% Render listing directly, if minted is available.
% Otherwise, include pre-rendered images.
\ifthenelse{\equal{\listingsmode}{minted}}{%
  \example{lst:minted-variants}{source-code-listings/minted-variants}{Shorthand and inline listing}
  }{%
  \Example{lst:minted-variants}{source-code-listings/minted-variants}{source-code-listings/minted-variants_crop}{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}).

% Render listing directly, if minted is available.
% Otherwise, include pre-rendered images.
\ifthenelse{\equal{\listingsmode}{minted}}{%
  \example{lst:minted-external}{source-code-listings/minted-import}{Including from a separate file}
  }{%
  \Example{lst:minted-external}{source-code-listings/minted-import}{source-code-listings/minted-import_crop}{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.

% Render listing directly, if minted is available.
% Otherwise, include pre-rendered images.
\ifthenelse{\equal{\listingsmode}{minted}}{%
  \example{lst:minted-external-styled}{source-code-listings/minted-import-styled}{Themes and further options}
  }{%
  \Example{lst:minted-external-styled}{source-code-listings/minted-import-styled}{source-code-listings/minted-import-styled_crop}{Themes and further options}
}
