95 lines
6.4 KiB
TeX
95 lines
6.4 KiB
TeX
\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 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:
|
|
|
|
% 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}
|
|
} |