improved documentation

thomasWeise · Dec 5, 2023 · bb7d92b · bb7d92b
1 parent f7cf8ef
commit bb7d92b
Show file tree

Hide file tree

Showing 4 changed files with 99 additions and 17 deletions.
diff --git a/Makefile b/Makefile
@@ -96,6 +96,13 @@ build_examples: extract python_dependencies
 	rm example_3.aux &&\
 	rm example_3.latexgit.dummy &&\
 	rm example_3.out &&\
+	pdflatex example_4.tex &&\
+	python3 -m latexgit.aux example_4 &&\
+	pdflatex example_4.tex &&\
+	rm example_4.log &&\
+	rm example_4.aux &&\
+	rm example_4.latexgit.dummy &&\
+	rm example_4.out &&\
 	rm latexgit.sty &&\
 	cd .. &&\
 	echo "$(NOW): Finished building the examples."

diff --git a/examples/example_3.tex b/examples/example_3.tex
@@ -1,22 +1,14 @@
 \documentclass{article}%
 \usepackage{latexgit}% use our package
-\usepackage{verbatim}% for loading a file verbatim
 \usepackage{xcolor}% to be able to use colors
 \usepackage[colorlinks]{hyperref}%  for printing the URL
 \usepackage{listings}% importing external code
-\lstset{%
-language=Python,%
-basicstyle=\small\ttfamily,%
+\lstset{language=Python,basicstyle=\small\ttfamily,%
 keywordstyle=\ttfamily\color{teal!90!black}\bfseries,%
-identifierstyle=,%
-commentstyle=\color{gray}\footnotesize,%
+identifierstyle=,commentstyle=\color{gray}\footnotesize,%
 stringstyle=\ttfamily\color{red!90!black},%
-numbers=left,%
-numberstyle=\tiny,%
-frame=shadowbox,%
-frameround=tttt,%
-backgroundcolor=\color{black!10!yellow!5!white}%
-}%
+numbers=left,numberstyle=\tiny,frame=shadowbox,frameround=tttt,%
+backgroundcolor=\color{black!10!yellow!5!white}}%
 \begin{document}%
 %
 Behold the beautiful \autoref{l}.%

diff --git a/examples/example_4.tex b/examples/example_4.tex
@@ -0,0 +1,25 @@
+\documentclass{article}%
+\usepackage{latexgit}% use our package
+\usepackage{xcolor}% to be able to use colors
+\usepackage[colorlinks]{hyperref}%  for printing the URL
+\usepackage{listings}% importing external code
+\lstset{language=Python,basicstyle=\small\ttfamily,%
+keywordstyle=\ttfamily\color{teal!90!black}\bfseries,%
+identifierstyle=,commentstyle=\color{gray}\footnotesize,%
+stringstyle=\ttfamily\color{red!90!black},%
+numbers=left,numberstyle=\tiny,frame=shadowbox,frameround=tttt,%
+backgroundcolor=\color{black!10!yellow!5!white}}%
+%
+\gdef\moptipySrc#1#2#3{%
+\gitLoad{https://github.com/thomasWeise/moptipy}{moptipy/#3}{%
+python3 -m latexgit.formatters.python --labels book}%
+\lstinputlisting[float,label={#1},caption={#2~(\href{\gitUrl}{src})}]{\gitFile}}
+%
+\begin{document}%
+%
+Behold the beautiful \autoref{a} and \autoref{b}.%
+%
+\moptipySrc{a}{Randomized Sampling}{algorithms/random_sampling.py}
+\moptipySrc{b}{Randomized Local Search}{algorithms/so/rls.py}
+%
+\end{document}%
diff --git a/latexgit.dtx b/latexgit.dtx
@@ -19,7 +19,7 @@
 \ProvidesFile{latexgit.dtx}
 %</driver>
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]%
-%<package>\ProvidesPackage{latexgit}[2023/11/17 0.8.0 The first public version.]%
+%<package>\ProvidesPackage{latexgit}[2023/12/05 0.8.1 A version with slightly improved documentation.]%
 %
 %<*driver>
 \documentclass{ltxdoc}
@@ -56,7 +56,7 @@ pdfkeywords={LaTeX, package, latexgit}
 language=[LaTeX]TeX,%
 basicstyle=\small,%
 keywordstyle=\ttfamily\color{teal!90!black}\bfseries,%
-morekeywords={url,verbatiminput},
+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,%
@@ -104,7 +104,8 @@ backgroundcolor=\color{black!10!yellow!5!white}%
 %   Grave accent  \`     Left brace    \{     Vertical bar  \|
 %   Right brace   \}     Tilde         \~}
 %
-% \changes{v0.8.0}{2023/12/04}{Initial Draft Version}
+% \changes{0.8.0}{2023/12/04}{initial draft version}
+% \changes{0.8.1}{2023/12/05}{slightly improved documentation}
 %
 % \GetFileInfo{latexgit.dtx}
 %
@@ -418,9 +419,12 @@ backgroundcolor=\color{black!10!yellow!5!white}%
 % 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.
-% Finally, the third example in \autoref{sec:example_3} shows how to create
+% 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}%
@@ -708,7 +712,61 @@ backgroundcolor=\color{black!10!yellow!5!white}%
 % 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%