latexgit.dtx

% \iffalse meta-comment
%
% Copyright (C) 2023 by Thomas Weise <http://iao.hfuu.edu.cn/5>
%
% This file may be distributed and/or modified under the conditions of the
% LaTeX Project Public License, either version 1.3 of this license or
% (at your option) any later version. The latest version of this license is in
% http://www.latex-project.org/lppl.txt.
% The license can be found at
% https://thomasweise.github.io/latexgit_tex/LICENSE.html.
% This work is author-maintained, i.e., it can only be maintained by
% Thomas Weise.
% 
% \fi
%
% \iffalse
%
%<*driver>
\ProvidesFile{latexgit.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]%
%<package>\ProvidesPackage{latexgit}[2023/12/05 0.8.1 A version with slightly improved documentation.]%
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{latexgit}[2014/06/17]
%
\usepackage{xcolor}%
\usepackage[%
colorlinks,%
breaklinks=true,%
urlcolor={blue!80!black},%
menucolor=black,%
linkcolor={red!50!black},%
bookmarks=true,%
bookmarksopen=false,%
hyperfootnotes=true,%
citecolor={blue!50!black},%
filecolor=black,%
pdfkeywords={LaTeX, package, latexgit}
]{hyperref}%
\usepackage{breakurl}%
\usepackage[square,numbers,comma,sort&compress]{natbib}%
%
\newcommand{\exampleautorefname}{Example}%
\renewcommand{\sectionautorefname}{Section}%
\renewcommand{\subsectionautorefname}{Section}%
\renewcommand{\subsubsectionautorefname}{Section}%
\usepackage{verbatim}%
\usepackage{graphicx}%
\usepackage{subcaption}%
\usepackage{afterpage}%
%
\usepackage{listings}%
\lstset{%
language=[LaTeX]TeX,%
basicstyle=\small,%
keywordstyle=\ttfamily\color{teal!90!black}\bfseries,%
morekeywords={url,verbatiminput,lstset,lstinputlisting},
classoffset=1,morekeywords={gitLoad,gitFile,gitUrl},keywordstyle=\ttfamily\bfseries\color{red!70!black},classoffset=0,%
identifierstyle=,%
commentstyle=\color{gray}\footnotesize,%
stringstyle=\ttfamily\color{red!90!black}, % typewriter type for string
numbers=left,%
numberstyle=\tiny,%
columns=fullflexible,%
frame=shadowbox,%
frameround=tttt,%
backgroundcolor=\color{black!10!yellow!5!white}%
}%
%
%
\gdef\tindex#1{\expandafter\index{#1}}%
\gdef\tbindex#1{\expandafter\index{\textbackslash#1}}%
%
\usepackage{placeins}%
%
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
%
%
\begin{document}
  \DocInput{latexgit.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \changes{0.8.0}{2023/12/04}{initial draft version}
% \changes{0.8.1}{2023/12/05}{slightly improved documentation}
%
% \GetFileInfo{latexgit.dtx}
%
% \DoNotIndex{\def,\if,\fi}
%
% \title{The \textsf{latexgit} Package}
% \author{Thomas Weise\\%
% \resizebox{0.95\textwidth}{!}{%
% \parbox{\linewidth}{%
% \centering%
% Institute of Applied Optimization\\%
% School of Artificial Intelligence and Big Data\\%
% Hefei University, Hefei 230601, Anhui, China\\%
% \href{mailto:tweise@hfuu.edu.cn}{tweise@hfuu.edu.cn} $\cdot$ \href{mailto:tweise@ustc.edu.cn}{tweise@ustc.edu.cn}%
% }}}%
% \date{\today}
%
% \renewcommand{\textfraction}{0.05}%
% \renewcommand{\topfraction}{0.85}%
% \renewcommand{\bottomfraction}{0.95}%
% \renewcommand{\floatpagefraction}{0.95}%
%
% \maketitle
%
% \begin{abstract}
% This \LaTeX\ package works in combination with the Python package
% |latexgit|.
% It offers the command |\gitLoad|\tbindex{gitLoad}, which can load a file
% from a |git|\tindex{git} repository, optionally post-process it, and then
% provide a local path to the file as macro |\gitFile|\tbindex{gitFile} and
% the URL to the original file in |\gitUrl|\tbindex{gitUrl}.
% Using the |\gitFile| macro, you can then include the file in \LaTeX\
% directly or load it as source code listing.
% The functionality is implemented by storing the |git| requests in the
% |aux|\tindex{aux} file of the project during the first
% |pdflatex|\tindex{pdflatex} pass.
% The |aux| file is then processed by the Python package which performs the
% actual git queries, stores the result in local files, and adds the resolved
% paths to the |aux| file.
% During the first |pdflatex|\tindex{pdflatex} run, |\gitFile| and |\gitUrl|
% offer dummy results.
% However, after the resolution via the Python package, in the second
% |pdflatex| run they then point to the right data.
% \end{abstract}
%
% \setcounter{tocdepth}{2}
% \tableofcontents
%
% \section{Introduction}%
%
% \subsection{Addressed Problem and Use Case}%
% Let's say you want to make teaching material in the field of computer
% science.
% In a wide variety of computer science fields, you may want to include source
% code examples in your lecture script or slides.
% The standard way is to either write some pseudo-code or program-like
% snippets.
% Usually these neither compile nor are they maintained well and they are
% often riddled with mistakes.
% That is not nice.
%
% What we want is to have snippets of ``real'' code.
% Code that we can compile, unit test, and run.
% Now such code naturally would not be sprinkled into our \LaTeX\ teaching
% material sources.
% That would be a mess to organize and maintain.
%
% A natural location for source code examples is a separate |git| repository.
% Maybe on GitHub, maybe somewhere else.
% If I wanted to do a lecture on, say, optimization algorithms, I would like to
% have the optimization algorithms
% \href{https://thomasweise.github.io/moptipy}{implemented in an actual useful fashion}.
% I would put them into a repository where I can build and test these real
% codes as a complete and separate piece of work.
%
% Then I want to use them in my lecture scripts (written in \LaTeX) as well.
% However, I do not want to \emph{copy} them there.
% I want that my lecture scripts directly reference the |git| repository with
% the real code.
% I want them to ``include'' the examples from there.
% If I change the code in the |git| repository and then re-compile my
% teaching material, these changes should automatically be reflected there.
%
% That is the use case we tackle here.
% We offer a solution to the question
%
% \begin{quote}
% \emph{``How can we include snippets of code from a separate, complex code basis
% (located in a |git| repository) into our \LaTeX\ documents?''}
% \end{quote}
%
% \subsection{Provided Functionality}%
% \label{sec:functionality}%
% It does so by offering a combination of a \LaTeX\ package (this package
% here) and a Python\index{Python} program (published at
% \url{https://pypi.org/projects/latexgit}).
% This \LaTeX\ provides the command |\gitLoad| that can load a specific file
% (its second argument) from a specific |git| repository (its first argument)
% and, optionally, pipe the file contents through a program for
% post-processing (the third argument, which can be left empty).
% Such requests are stored in the |aux| file during the first |pdflatex| pass,
% then resolved by the Python program, and their results become available in
% the second |pdflatex| pass via the commands |\gitFile| and |\gitUrl|.
%
% \section{Usage}%
% Using the package requires the following steps:
% \begin{enumerate}%
%%
% \item Obviously, both the
% \href{https://thomasweise.github.io/latexgit_tex}{\LaTeX\ package}
% \emph{and} its
% \href{https://thomasweise.github.io/latexgit_py}{Python companion}
% package must be installed (see \autoref{sec:installation}).
%%
% \item In your document, you need to load the package in the preamble
% (see \autoref{sec:loadThePackage}).%
%%
% \item Then you can make |git| queries and using the paths to files holding
% their results (see \autoref{sec:gitquery}).
%%
% \item Finally, the Python package can carry them out after the first
% |pdflatex| run and in the next |pdflatex| run, |\gitFile| and |\gitUrl| are
% defined appropriately, see \autoref{sec:pythonProgram}.
% \end{enumerate}
%
% If your \LaTeX\ document is called |article.tex|, then you have at least the
% following workflow:%
% \begin{quote}
% |pdflatex article|\\
% |python3 -m latexgit.aux article|\\
% |pdflatex article|
% \end{quote}
%
% Comprehensive examples are provided in \autoref{sec:examples}.
%
% \subsection{Installation}%
% \label{sec:installation}%
%
% \subsubsection{\LaTeX\ Package}%
% First, make sure that you have the |latexgit.sty| either installed or inside
% your document's directory.
% For this, there are several options:%
% \begin{enumerate}%
% \item You can just download the file from
% \url{https://thomasweise.github.io/latexgit_tex/latexgit.sty} directly.
% You can now copy it into the folder of your document.
%%
% \item You can download |latexgit.dtx|\tindex{latexgit.dtx} and
% |latexgit.ins|\tindex{latexgit.ins} from
% \url{https://thomasweise.github.io/latexgit_tex/latexgit.dtx} and
% \url{https://thomasweise.github.io/latexgit_tex/latexgit.ins}.
% You can then execute
% \begin{quote}%
% |pdflatex latexgit.ins|\tindex{pdflatex}
% \end{quote}%
% and you should get the style file |latexgit.sty|\tindex{latexgit.sty}.
% You can now copy it into the folder of your document.
%%
% \item Or you can download the |latexgit.tds.zip| file from
% \url{https://thomasweise.github.io/latexgit_tex/latexgit.tds.zip} and
% unpack it into your \TeX\ tree.
% If you know what that is.
% \end{enumerate}%
%
% \subsubsection{Python Package}%
% \label{sec:latexgitpy}%
% The Python\index{Python} package is available at
% \url{https://github.com/thomasWeise/latexgit_py}\index{latexgit\_py},
% \url{https://thomasweise.github.io/latexgit_py}, and
% \url{https://pypi.org/project/latexgit}.
% You can most easily install it from PyPI\index{PyPI} by doing
% \begin{quote}
% |pip install latexgit|
% \end{quote}
%
% \subsection{Loading the Package}%
% \label{sec:loadThePackage}%
% Load this package using%
% \begin{quote}
%   |\usepackage{latexgit}|
% \end{quote}
% \begin{sloppypar}%
% The package has no options or parameters.
% Loading it will automatically load the packages
% |alphalph|\index{alphalph} and |filecontents|\index{filecontents} as well,
% see \autoref{sec:implementation}.
% \end{sloppypar}%
%
% \subsection{Querying a File from a git Repository}%
% \label{sec:gitquery}%
% To query a file stored at path |thePath| inside from a |git|\tindex{git}
% repository available under URL |theUrl|, you would specify the command
% \begin{quote}
% |\gitLoad{theUrl}{theFile}{}|\tbindex{gitLoad}
% \end{quote}
% After this command is executed, a local path to the file becomes available
% in the fully-expandable command |\gitFile|\tbindex{gitFile}.
% The full URL to the file in the |git| repository, including the current
% commit id, becomes available in the fully-expandable command
% |\gitUrl|\tbindex{gitUrl}.
% Both |\gitFile| and |\gitUrl| will be overwritten every time |\gitLoad| is
% invoked.
% You can invoke |\gitLoad| any number of times.
%
% The third parameter, left empty in the above example, can specify an
% optional post-processing commend.
% If it is not left empty, this command will be executed in the
% shell\index{shell}.
% The contents of the file loaded from the |git| repository will be piped to
% the |stdin|\tindex{stdin} of the command.
% The |stdout|\tindex{stdout} of the command will be piped to a file and
% |\gitFile|\tbindex{gitFile} will then contain the path to this file
% instead.
% For example, under Linux\index{Linux}, you could use the
% \href{https://www.man7.org/linux/man-pages/man1/head.1.html}{|head|}\index{head}
% command to return only the first 5~lines of a file as follows:
% \begin{quote}
% |\gitLoad{theUrl}{theFile}{head -n 5}|\tbindex{gitLoad}
% \end{quote}
%
% \subsection{Executing the Python Package}
% \label{sec:pythonProgram}
% \begin{sloppypar}%
% During the first |pdflatex|\tindex{pdflatex} run, |\gitFile| points to an
% empty dummy file
% (|\jobname.latexgit.dummy|)\tbindex{jobname.latexgit.dummy} and
% |\gitUrl| points to |http://example.com|\index{http://example.com}.
% Both commands will only expand to useful information if the Python package
% |latexgit| is applied to the project's |aux| file.
% This works very similar to \BibTeX.
% If the name of your \TeX\ file is |myfile.tex|, then you would execute
% \end{sloppypar}%
% \begin{quote}
% |python3 -m latexgit.aux myfile|
% \end{quote}
% More specifically, the Python package processes the |aux| files, so for a
% specific |aux|\tindex{aux} file |myfile.aux|, you could also do:
% \begin{quote}
% |python3 -m latexgit.aux myfile.aux|
% \end{quote}
%
% After this, in the next pass of |pdflatex|, |\gitFile| and |\gitUrl| will
% contain the right paths and URLs.
%
% \section{Provided Macros}\label{sec:providedMacros}%
%
% Here we discuss the macros that can directly be accessed by the user to
% make use of the functionality of the |latexgit| package.
% The implementation of these macros is given in \autoref{sec:implementation}
% and several examples can be found in \autoref{sec:examples}.
%
% \DescribeMacro{\gitLoad}%
% The macro |\gitLoad|\marg{repositoryURL}\marg{path}\marg{postProcessing}
% provides a local path to a file from a |git| repository.
% \begin{itemize}%
% \item[\marg{repositoryURL}] is the URL of the |git| repository.
% It could, e.g., be \url{https://github.com/thomasWeise/latexgit\_tex} or
% \url{ssh://git@github.com/thomasWeise/latexgit\_tex} or any other valid
% repository URL.%
%
% \item[\marg{path}] is then the path to the file within the repository.
% This could be, for example, |latex/latexgit.dtx|.%
%
% \item[\marg{postProcessing}] Can either be empty, in which case the
% repository is downloaded and the the local path to the file is returned.
% It can also be shell command, e.g., |head -n 5|.
% In this case, the contents of the file are piped to |stdin|\tindex{stdin} of
% the command and the text written to the |stdout|\tindex{stdout} by the
% command is stored in a file whose path is returned.
% \end{itemize}%
%
% After invoking this command, two new commands will be defined:%
% \begin{itemize}%
% \item[\texttt{{\textbackslash}gitFile}] returns the path to the file that was loaded and/or
% post-processed.%
% \item[\texttt{{\textbackslash}gitUrl}] returns the fully URL to the file in the |git| repository
% online.
% This command works for GitHub, but it may not provide the correct URL for
% other repository types.%
% \end{itemize}%
%
% \DescribeMacro{\gitFile}%
% The macro |\gitFile| returns the path to the file with the contents of the
% latest |\gitLoad| request.
% During the first |pdflatex| pass, this will be the path to a dummy file.
% After the Python package has been applied to the |aux| file, then |\gitFile|
% will point to the proper file during the next |pdflatex| pass.
%
%
% \DescribeMacro{\gitUrl}%
% The macro |\gitUrl| returns the URL from which the file corresponding to
% the latest |\gitLoad| request was downloaded.
% This command is designed to work with GitHub.
% It will be the repository URL combine with the path of the file inside the
% repository and the commit has code.
% The Url thus points to the exact same version of the file that was
% downloaded (and optionally post-processed).
%
% During the first |pdflatex| pass, this will be \url{https://example.com}.
% After the Python package has been applied to the |aux| file, then
% |\gitUrl| will point to the proper file during the next |pdflatex| pass.
%
% \subsection{Examples}\label{sec:examples}%
%
% Here we provide a set of examples for the use of the package.
% Each example demonstrates another facet of the package and, at the same
% time, serves as test case.
% The first example given in \autoref{sec:example_1} is a Minimal Working
% Example, i.e., just provides the barest bones.
% It shows you how to import a single file from a |git| repository.
% The second example in \autoref{sec:example_2} shows you how to import
% multiple different files from different repositories (which equates to just
% using the same command multiple times) and how to use post-processors.
% The third example in \autoref{sec:example_3} shows how to create
% beautiful (to my standards) listings by including code from a |git|
% repository, post-processing it, and loading it as a |listing|.
% Finally, the fourth example in \autoref{sec:example_4} shows that you can
% also define macros for your favorite repository and post-processors to have
% a more convenient way to import files from |git|.
%
% \subsection{Minimal Working Example}%
% \label{sec:example_1}%
% This minimal working example shows how to load a file from a |git|
% repository and directly |\input|\expandafter\tbindex{input} its contents.
% The result can be seen in \autoref{ex:example_2:res}.
%
% \lstinputlisting[classoffset=2,morekeywords={A,B,C,D},keywordstyle=\ttfamily\bfseries\color{blue!90!black},classoffset=0,float,label=ex:example_1,caption={A minimal working example for using the \texttt{latexgit} package, rendered as \autoref{ex:example_1:res}. The contents of \texttt{dummy.tex} are shown in \autoref{ex:dummy_tex}.}]{examples/example_1.tex}%
%
% As you can see in \autoref{ex:example_1}, we first load the package
% |latexgit| in line~2.
% Inside the document, we define a |git| request via the |\gitLoad| command.
% This command takes the URL of a |git| repository as first parameter.
% in this case, this is \url{https://github.com/thomasWeise/latexgit_tex},
% which happens to be the URL where you can find the repository of this
% package on GitHub.
% The second parameter is a path to the file in this repository relative to
% the repository root.
% In this case, this is the path to the file |examples/dummy.tex|, whose
% contents you can find in \autoref{ex:dummy_tex}.
%
% \lstinputlisting[float,label=ex:dummy_tex,caption={The contents of the file \texttt{dummy.tex} included from \texttt{git} in \autoref{ex:example_1}.}]{examples/dummy.tex}%
%
% The third parameter shall be ignored for now.
%
% After defining the request, we can now use two commands, |\gitFile| and
% |\gitUrl|.
% In this Minimal Working Example, we shall only consider the first one.
% This command expands to a local path of a file with the contents downloaded
% from the |git| repository.
%
% Well, during the first \LaTeX\ or |pdflatex| run, it just points to a dummy
% file with the name |\jobname.latexgit.dummy|, where
% |\jobname|\tbindex{jobname} evaluates to the name of the main \LaTeX\
% document, say |article| for |article.tex|.
% At that point, the dummy file's content is a single space character followed
% by a newline.
%
% After the first |pdflatex| pass, you can apply the Python\index{Python}
% processor (see \autoref{sec:latexgitpy}) as follows:
% \begin{quote}%
% |python3 -m latexgit.aux jobname|
% \end{quote}%
% Where |jobname| shall be replaced with the main file name, again |article|
% for |article.tex|, for instance.
%
% This command then downloads the file from |git| and puts it into a path that
% can locally accessed by \LaTeX.
% Usually, it will create a folder |__git__|\tindex{\_\_git\_\_} in your
% project's directory and place the file there.
%
% Anyway, during the second \LaTeX\ or |pdflatex| pass, |\gitFile| points to a
% valid file path with actual contents.
% By doing |\input{\gitFile}|\tbindex{input}, we here include this file
% (remember, its contents are given in \autoref{ex:dummy_tex}) as if it was
% part of our normal \LaTeX\ project.
% The result of this pass is shown in \autoref{ex:example_1:res}.
%
% If this example was stored as |example_1.tex|, then it could be built via
% \begin{quote}
% |pdflatex example_1|\\
% |python3 -m latexgit.aux example_1|\\
% |pdflatex example_1|
% \end{quote}
%
% \begin{figure}%
% \centering%
% \fbox{\includegraphics[page=1,width=0.9\linewidth,trim=1.65in 9.3in 1.5in 1.6in,clip]{examples/example_1.pdf}}%
% \caption{The rendered result of \autoref{ex:example_1} (with trimmed page margins and bottom).}%
% \label{ex:example_1:res}%
% \end{figure}%
%
% If we look back at the \autoref{ex:example_1} of our main file, you will
% notice the four blue marks {\bfseries\color{blue!90!black}A},
% {\bfseries\color{blue!90!black}B}, {\bfseries\color{blue!90!black}C}, and
% {\bfseries\color{blue!90!black}D}.
% These are just normal letters, colored and emphasized for your convenience.
% I put them there so that you can see where the action takes place.
% |\gitLoad| produces no output, so ``ABC'' come out next to each other.
% |\input{\gitFile}| between {\bfseries\color{blue!90!black}C} and
% {\bfseries\color{blue!90!black}D} loads and directly includes the example
% file, so this is where its content appear.
%
% One small interesting thing is that, since we directly |\input| the file,
% its contents are interpreted as \LaTeX\ code.
% This means that you could construct a document by inputting files from
% different |git| repositories.
%
% However, this is not the envisioned use case.
% The envisioned use case is to include source codes and snippets from source
% codes as listings.
% We will show how this could be done in the next example.
%
% Side note: Our Python companion package |latexgit| downloads the |git|
% repositories into a folder called |__git__|\tindex{\_\_git\_\_} by default.
% If you do not delete the folder, the same repository will not be downloaded
% again but the downloaded copy will be used.
% This significantly increases speed and reduces bandwidth when applying the
% |latexgit| command several times.
% \clearpage%
%
% \subsection{The Second Example: Multiple Files and Post-Processing}%
% \label{sec:example_2}%
% \FloatBarrier%
% In \autoref{ex:example_2} we, use |latexgit| to download and present two
% different files from two different GitHub repositories.
% We also show how post-processing can work, once using the aforementioned
% simple |head -n 5| command available in the Linux shell and also by
% using the Python code formatting tool offered by the |latexgit| Python
% package.
% The result can be seen in \autoref{ex:example_2:res}.
% 
% \lstinputlisting[float,label=ex:example_2,caption={An example using the latexgit package, rendered as \autoref{ex:example_2:res}.}]{examples/example_2.tex}%
% \FloatBarrier%
%
% The file |example_2.tex| shown in \autoref{ex:example_2} begins by loading
% our |latexgit| package as well as package |verbatim|, which is later used
% to display the included files.
% The document creates three sections, each of which is used to display one
% imported file.
%
% The first section loads one Python source file from our Python companion
% package \href{https://thomasweise.github.io/latexgit_py}{latexgit\_py}.
% The sources of this package are available in the GitHub repository
% \url{https://github.com/thomasWeise/latexgit\_py}.
% We download the file |latexgit/utils/console.py|, which is just a small
% utility for printing log strings to the output together with a time mark.
% The full git request contains these two components.
%
% Issuing this request will set the command |\gitFile| to the local file
% containing the downloaded contents of |latexgit/utils/console.py| from the
% repository \url{https://github.com/thomasWeise/latexgit\_py}.
% The command |\gitUrl| will expand to the URL pointing to the downloaded
% \emph{version} of the file in the original repository.
% This command, at the present time, is only really valid for GitHub.
% It builds a URL relative to the original repository based on the commit ID
% that was valid when the file was downloaded from the repository.
% Therefore, the URL then points to the \emph{exact same} contents that were
% put into the file.
% Anyway, the file contents and the generated URL are displayed in
% \autoref{ex:example_2:1}.
%
% The second section of the example document queries the same file again.
% However, this time, the third parameter of |\gitLoad| is specified.
% If the third parameter is left blank, the downloaded file will be provided
% as-is.
% However, especially if we would like to include some snippets of a more
% complex source file, we sometimes do not want to have the complete original
% contents.
% In this case, we can specify a post-processing command as third parameter.
% This command will be executed in the shell\index{shell}
% The contents of the downloaded file will then be piped into the
% |stdin|\tindex{stdin} of the command and everything that the command writes
% to its |stdout|\tindex{stdout} will be collected in a file.
% |\gitFile| then returns the path to that file.
%
% Since you can provide arbitrary commands as post-processors, this allows you
% to do, well, arbitrary post-processing.
% This could include re-formatting of code or selecting only specific lines
% from the file.
% The command can have arguments, separated by spaces, allowing you to pass
% information such as line indices or other instructions to your
% post-processing command.
%
% In the example, we use the standard Linux command |head -n 5|, which writes
% the first five lines that were written to its |stdin| to its |stdout|.
%
% The resulting output in \autoref{ex:example_2:2} looks thus similar to
% \autoref{ex:example_2:1}, but only imports ths first five lines from the
% downloaded file.
%
% If this example was stored as |example_2.tex|, then it could be built via
% \begin{quote}
% |pdflatex example_2|\\
% |python3 -m latexgit.aux example_2|\\
% |pdflatex example_2|
% \end{quote}
%
% Side note: Such post-processing steps are cached by the Python companion
% package |latexgit| in the |__git__|\tindex{\_\_git\_\_} folder as well.
%
% Finally, in the third section, of \autoref{ex:example_2}, we import a file
% from the sources of our Python package for metaheuristic optimization
% (\href{https://thomasweise.github.io/moptipy}{moptipy}).
% The sources of this package are located on GitHub at
% \url{https://github.com/thomasWeise/moptipy}.
% We download the file |moptipy/api/encoding.py|, which offers a convenient
% API for implementing an \emph{encoding} which translates from the search to
% the solution space (but that would lead too far here).
% Either way, this is a file that has lots of content.
% So we want to select certain contents while ignoring other.
% We also remove all Python type hints and all comments from the source and
% then reformat it.
%
% Luckily, our |latexgit| Python package also offers a Python code formatter,
% namely the executable module \href{https://thomasweise.github.io/latexgit_py/latexgit.formatters.html#module-latexgit.formatters.python}{latexgit.formatters.python}.
% This module takes a set of parameters such as limiting |labels| that denote
% the start and end of code snippets (in this case, the label ``|book|'') to
% include as well |args| telling the system which part of the ``omittable''
% code to preserve (in this case, preserve |doc|strings and delete everything
% else that is non-essential).
% If you are interested in such post-processing, feel invited to check out
% the \href{https://thomasweise.github.io/latexgit_py}{documentation} of the
% Python companion package at \url{https://thomasweise.github.io/latexgit_py}.
% Either way, the file is downloaded, piped through this post-processor, and
% the result is included as shown in \autoref{ex:example_2:3}.
%
% \begin{figure}%
% \centering%
% \strut\hfill\strut%
% \subcaptionbox{Page 1 of the pdf compiled from \autoref{ex:example_2}.\label{ex:example_2:1}%
% }{%
% \fbox{\includegraphics[page=1,width=0.455\linewidth,trim=1.65in 5in 1.5in 1.5in,clip]{examples/example_2.pdf}}%
% }%
% \strut\hfill\strut\hfill\strut%
% \subcaptionbox{Page 2 of the pdf compiled from \autoref{ex:example_2}.\label{ex:example_2:2}%
% }{%
% \fbox{\includegraphics[page=2,width=0.455\linewidth,trim=1.65in 5in 1.5in 1.5in,clip]{examples/example_2.pdf}}%
% }%
% \strut\hfill\strut%
% \\%
% \strut\hfill\strut%
% \subcaptionbox{Page 3 of the pdf compiled from \autoref{ex:example_2}.\label{ex:example_2:3}%
% }{\parbox{\linewidth}{\centering%
% \fbox{\includegraphics[page=3,width=0.455\linewidth,trim=1.65in 5in 1.5in 1.5in,clip]{examples/example_2.pdf}}%
% }}%
% \strut\hfill\strut%
%
% \caption{The rendered result of \autoref{ex:example_2} (with trimmed page margins and bottoms).}%
% \label{ex:example_2:res}%
% \end{figure}%
%
% \FloatBarrier%
% \subsection{The Third Example: Using the \texttt{listings} Package}%
% \label{sec:example_3}%
% \FloatBarrier%
% Finally, as third example, let us show the interaction with the package
% |listings|.
% This is not much different from using the package |verbatim| in the second
% example above.
% I just wanted to show you how it looks like.
% Also, I wanted to show the intended use of |\gitUrl|:
% You can use it to put some small ``(src)'' link in the listing's caption.
% This way, you can create teaching material where every listing is linked to
% the correct version of source code online without splattering long URLs into
% your text.
% Anyway.
% The source code of the third example is given in \autoref{ex:example_3} and
% the compiled result as \autoref{ex:example_3:res}.
%
% \lstinputlisting[float,label=ex:example_3,caption={An example using the \texttt{listings} package, rendered as \autoref{ex:example_3:res}.}]{examples/example_3.tex}%
%
% \begin{figure}%
% \centering%
% \fbox{\includegraphics[page=1,width=0.9\linewidth,trim=1.4in 5.6in 1.5in 1.6in,clip]{examples/example_3.pdf}}%
% \caption{The rendered result of \autoref{ex:example_3} (with trimmed page margins and bottom).}%
% \label{ex:example_3:res}%
% \end{figure}%
%
% If this example was stored as |example_3.tex|, then it could be built via
% \begin{quote}
% |pdflatex example_3|\\
% |python3 -m latexgit.aux example_3|\\
% |pdflatex example_3|
% \end{quote}
%
% Side note: If you actually check the \href{https://thomasweise.github.io/moptipy/_modules/moptipy/algorithms/so/rls.html}{source code}
% of the RLS algorithm, which is linked to by the ``(\href{https://thomasweise.github.io/moptipy/_modules/moptipy/algorithms/so/rls.html}{src})''
% in the caption of the example and that is displayed in the example, you will
% find that it actually uses Python type hints.
% It also has a comprehensive doc-string and is commented well.
% In source code of a real project, we do want this.
% In a listing in a book, we do not.
% The post-processor command
% \begin{quote}
% |python3 -m latexgit.formatters.python --labels book|
% \end{quote}%
% only keeps the code between the labels ``|# start book|'' and
% ``|# end book|.''
% It also removes all non-essential stuff such as type hints, comments, and
% the doc-string.
% Then it re-formats the code to save space.
% Again, check out the documentation of our |latexgit| Python companion
% package at \url{https://thomasweise.github.io/latexgit_py}.
% This is the main intended use case of our package:
% Be able to have nicely documented ``real'' code and to use parts of it
% in teaching materials.
%
% \FloatBarrier%
% \subsection{The Fourth Example: Using Git Commands in Macros}%
% \label{sec:example_4}%
% \FloatBarrier%
%
% \lstinputlisting[float,label=ex:example_4,caption={An example using commands from the latexgit package in macros, rendered as \autoref{ex:example_4:res}.}]{examples/example_4.tex}%
%
% The goal of the fourth example is to show that we can also put the commands
% from our |latexgit| package into \LaTeX\ macros.
% We define a new command |\moptipySrc| with three parameters.
% \href{https://thomasweise.github.io/moptpiy}{moptipy} is a Python package
% that implements lots of metaheuristic algorithms.
% We could want to load several files from such a repository
% \url{https://github.com/thomasWeise/moptipy} and post-process and display
% them all in the same way.
% Then, it would be annoying to always do |\gitLoad|, |\lstinputlisting|,
% and spell out the post-processor each time.
% So we put all of this into a single command whose first argument is the
% label to put for the listing, whose second command is the caption to use,
% and whose third command is the path relative to the folder ``moptipy'' in
% the |git| repository.
% In \autoref{ex:example_4}, we can then simply call |\moptipySrc| and it will
% do the whole process of loading a file from the right repository,
% post-processing it, putting a floatin listing, and even putting a small
% ``(\href{https://thomasweise.github.io/moptpiy}{src})'' into the caption of
% the listing.
% The results are shown in \autoref{ex:example_4:res}% and can be obtained via
% \begin{quote}
% |pdflatex example_4|\\
% |python3 -m latexgit.aux example_4|\\
% |pdflatex example_4|
% \end{quote}
% (if the example code from \autoref{ex:example_4} was stored in a file called
% |example_4.tex|, that is.)
%
% \FloatBarrier%
%
% \begin{figure}%
% \centering%
% \strut\hfill\strut%
% \subcaptionbox{Page 1 of the pdf compiled from \autoref{ex:example_4}.\label{ex:example_4:1}%
% }{%
% \fbox{\includegraphics[page=1,width=0.455\linewidth,trim=1.65in 6.2in 1.5in 1.8in,clip]{examples/example_4.pdf}}%
% }%
% \strut\hfill\strut\hfill\strut%
% \subcaptionbox{Page 2 of the pdf compiled from \autoref{ex:example_4}.\label{ex:example_4:2}%
% }{%
% \fbox{\includegraphics[page=2,width=0.455\linewidth,trim=1.65in 3.7in 1.5in 3.7in,clip]{examples/example_4.pdf}}%
% }%
% \strut\hfill\strut%
% \caption{The rendered result of \autoref{ex:example_4} (with trimmed page margins and bottoms).}%
% \label{ex:example_4:res}%
% \end{figure}%
%
% \afterpage{\clearpage}%
%
% \clearpage%
%
%
% \StopEventually{}
%
% \section{Implementation}%
% \label{sec:implementation}%
% The names of all internal elements of the package are prefixed
% with |@latexgit@|.
% This naming convention should prevent any name clashes with other packages.
%
% Our |latexgit| package requires only one other package:%
% \begin{enumerate}%
% \item |alphalph|\index{alphalph}~\cite{O2019TAP} is required to translate
% \TeX\ counters to alphabetic series for counters that are outside of the
% range~$1\dots26$.
% Basically, for each file we include from |git|, we store the corresponding
% local path in a command of the structure |\@latexgit@pathXXX| where the
% |XXX| is an alphabetical sequence which is increasing in the form
% ``\alphalph{1},'', ``\alphalph{2},'' \dots, ``\alphalph{25},''
% ``\alphalph{26},'' ``\alphalph{27},'' \dots, ``\alphalph{51},''
% ``\alphalph{52},'' ``\alphalph{53},'' ``\alphalph{701},''
% ``\alphalph{702},''  ``\alphalph{703},''  ``\alphalph{704},'' \dots%
%
% \item |filecontents|\index{filecontents}~\cite{P2023TFP} is used to allow us
% to generate the dummy file on the fly.
% This package is obsolete for the most recent \LaTeX\ version, where it
% simply does nothing, but may help us to get our package to work on older
% systems.
% \end{enumerate}%
%    \begin{macrocode}
\RequirePackage{alphalph}%  Convert counters to alphabetical series.
\RequirePackage{filecontents}%  Allow us to create the dummy file.
%    \end{macrocode}
%
%    \begin{macrocode}
\newcount\@latexgit@counter%  The counter for the git files included.
\@latexgit@counter0\relax%    We start the counter at 0.
%
% This is the path to the dummy file.
% The dummy file is created directly below.
% The dummy file is referenced by all invocations of |\gitFile| until the
% Python package has been applied to the |.aux| file and has loaded the
% actual files.
\edef\@latexgit@dummyPath{\jobname.latexgit.dummy}%  the dummy file
%
% Create the dummy file that replaces git files before they are loaded.
% This file only has one line with one single space.
\expandafter\begin\expandafter{filecontents*}{\@latexgit@dummyPath}

\end{filecontents*}
%
% This command does nothing and is just a placeholder in the |aux| files.
\protected\gdef\@latexgit@gitFile#1#2#3{}%
%    \end{macrocode}
%
% \begin{macro}{\gitLoad}
% The macro |\gitLoad|\marg{repositoryURL}\marg{path}\marg{postProcessing}
% defines a query to a |git| repository.
% The query is stored in the |aux| file of the project and carried out by the
% Python companion package (see \autoref{sec:pythonProgram}).
% This macro will define two other macros, |\gitFile| and |\gitUrl|.
% During the first \LaTeX\ build, these macros will return a path to a dummy
% file which only has a single space character in it followed by a newline and
% the URL \url{https://example.com}, respectively.
% As said, |\gitLoad| will store all information in the |aux| file, which then
% permits the |latexgit| Python package to download (and optionally
% post-process) the actual file.
% In the second round of \LaTeX\ building, |\gitFile| and |\gitUrl| will then
% return the local path to that downloaded file and the actual URL,
% respectively.%
%
% \begin{itemize}%
% \item[\marg{repositoryURL}] is the URL of the |git| repository.
% It could, e.g., be \url{https://github.com/thomasWeise/latexgit\_tex} or
% \url{ssh://git@github.com/thomasWeise/latexgit\_tex} or any other valid
% repository URL.%
%
% \item[\marg{path}] is then the path to the file within the repository.
% This could be, for example, |latex/latexgit.dtx|.%
%
% \item[\marg{postProcessing}] Can either be empty, in which case the
% repository is downloaded and the the local path to the file is
% returned.
% It can also be shell command, e.g., |head -n 5|.
% In this case, the contents of the file are piped to |stdin| of the command
% and the text written to the |stdout| by the command is stored in a file
% whose path is returned.
% \end{itemize}%
%    \begin{macrocode}
%%
%% Define a query to load and post-process a file from a |git| repository.
%% #1 is the repository URL
%% #2 is the path to the file inside the repository
%% #3 is a command through which the file contents should be piped
%%%   (leave #3 empty to use the file as-is)
\protected\gdef\gitLoad#1#2#3{%
\edef\@latexgit@pA{#1}%  fully expand the repository URL
\edef\@latexgit@pB{#2}%  fully expand the path into the repository
\edef\@latexgit@pC{#3}%  fully expand the (optional) shell command
% Write the parameters to the aux file.
\immediate\write\@mainaux{%
\noexpand\@latexgit@gitFile{\@latexgit@pA}{\@latexgit@pB}{\@latexgit@pC}}%
% Increment the counter for command names by 1.
\advance\@latexgit@counter by 1\relax%
% We now create the name of the path command based on the structure
% |\@latexgit@pathXXX| where |XXX| is a alphabetic sequence representing
% the value of |\@latexgit@counter|
\edef\@latexgit@pathCmd{@latexgit@path\alphalph{\the\@latexgit@counter}}%
% If the path command exists, then we store it as |\gitFile|.
\expandafter\ifcsname\@latexgit@pathCmd\endcsname\relax%
\xdef\gitFile{\csname\@latexgit@pathCmd\endcsname}%
\else%
% But if it does not exist, we assign |\gitFile| to the dummy path.
\xdef\gitFile{\@latexgit@dummyPath}%
\fi%  If we get here, the |\gitFile| command holds a valid path.
% We now create the name of the url command based on the structure
% |\@latexgit@urlXXX| where |XXX| is a alphabetic sequence representing
% the value of |\@latexgit@counter|
\edef\@latexgit@urlCmd{@latexgit@url\alphalph{\the\@latexgit@counter}}%
% If the url command exists, then we store it as |\gitUrl|.
\expandafter\ifcsname\@latexgit@urlCmd\endcsname\relax%
\xdef\gitUrl{\csname\@latexgit@urlCmd\endcsname}%
\else%
% But if it does not exist, we store the example url in |\gitUrl|.
\xdef\gitUrl{http://example.com}%
\fi%  If we get here, the |\gitUrl| holds a valid URL.
}%
%    \end{macrocode}
% \end{macro}
%
%
% \begin{thebibliography}{10}
% \providecommand{\natexlab}[1]{#1}
% \providecommand{\url}[1]{\texttt{#1}}
% \expandafter\ifx\csname urlstyle\endcsname\relax
%   \providecommand{\doi}[1]{doi: #1}\else
%   \providecommand{\doi}{doi: \begingroup \urlstyle{rm}\Url}\fi
%
% \bibitem[Oberdieck(2019)]{O2019TAP}
% Heiko Oberdieck.%
% \newblock {The \textbf{alphalph}\index{alphalph} package}.%
% \newblock \emph{CTAN Comprehensive \TeX\ Archive Network}, \mbox{2019/12/09 v2.6}.%
% \newblock URL \url{https://ctan.org/pkg/alphalph}%
%
% \bibitem[Pakin(2023)]{P2023TFP}
% Scott Pakin.
% \newblock {The \textbf{filecontents} package.}%
% \newblock \emph{CTAN Comprehensive \TeX\ Archive Network}, \mbox{April 2, 2023}.%
% \newblock URL \url{https://ctan.org/pkg/filecontents}%
%
% \end{thebibliography}
% \Finale
\endinput