new texgit version and steps towards better listings api

Author: thomasWeise

bookbase

@@ -1,18 +1,23 @@
 \hsection{Scripts}%
 %
-\gitBash{\programmingWithPythonCodeRepo}{_scripts_/mypy.sh}{bash:mypy}{%
+\gitLoad{lst:bash:mypy}{\programmingWithPythonCodeRepo}{_scripts_/mypy.sh}{}%
+\listingBash{bash:mypy}{%
 A \bash\ script for executing \mypy, which prints the command line and the exit code; see \cref{ut:mypy}.}%
 %
-\gitBash{\programmingWithPythonCodeRepo}{_scripts_/ruff.sh}{bash:ruff}{%
+\gitLoad{lst:bash:ruff}{\programmingWithPythonCodeRepo}{_scripts_/ruff.sh}{}%
+\listingBash{bash:ruff}{%
 A \bash\ script for executing \ruff, which prints the command line and the exit code; see \cref{ut:ruff}.}%
 %
-\gitBash{\programmingWithPythonCodeRepo}{_scripts_/pylint.sh}{bash:pylint}{%
+\gitLoad{lst:bash:pylint}{\programmingWithPythonCodeRepo}{_scripts_/pylint.sh}{}%
+\listingBash{bash:pylint}{%
 A \bash\ script for executing \pylint, which prints the command line and the exit code; see \cref{ut:pylint}.}%
 %
-\gitBash{\programmingWithPythonCodeRepo}{_scripts_/pytest.sh}{bash:pytest}{%
+\gitLoad{lst:bash:pytest}{\programmingWithPythonCodeRepo}{_scripts_/pytest.sh}{}%
+\listingBash{bash:pytest}{%
 A \bash\ script for executing test cases with \pytest, which prints the command line and the exit code; see \cref{ut:pytest}.}%
 %
-\gitBash{\programmingWithPythonCodeRepo}{_scripts_/pytest_doctest.sh}{bash:pytest_doctest}{%
+\gitLoad{lst:bash:pytest_doctest}{\programmingWithPythonCodeRepo}{_scripts_/pytest_doctest.sh}{}%
+\listingBash{bash:pytest_doctest}{%
 A \bash\ script for executing \pglspl{doctest} with \pytest, which prints the command line and the exit code; see \cref{ut:doctest}.}%
 %
 Here we provide some scripts that are used within this book.

text/back/scripts.tex

@@ -68,4 +68,5 @@ \chapter*{Preface}%
 %
 \strut\vfill\strut%
 This book was built using the following software:%
-\gitOutputWithStyle{}{}{text/front/preface/dependencyVersions.sh}{versions}{}{text_style}%
+\gitExec{exec:versions}{}{}{text/front/preface/dependencyVersions.sh}%
+\lstinputlisting[style=text_style]{\gitFile{exec:versions}}%

text/front/preface/preface.tex

@@ -1,8 +1,9 @@
 \hsection{Dictionaries}%
 \label{sec:dictionaries}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{dicts_1.py}{--args format}{dicts:dicts_1}{%
-An example of using dictionaries in \python.}%
+\gitLoadAndExecPython{dicts:dicts_1}{}{collections}{dicts_1.py}{}%
+\listingPythonAndOutput{dicts:dicts_1}{dicts_1.py}{%
+An example of using dictionaries in \python.}{}%
 %
 Dictionaries in \python\ are containers that store key-value pairs.
 The value associated with a given key is accessed via the \pythonil{[...]}\pythonIdx{[\idxdots]}-based indexing.

text/main/basics/collections/dictionaries/dictionaries.tex

@@ -7,14 +7,17 @@
 \hsection{Basic Functionality and Examples}%
 \label{sec:lists:basicFunctions}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{lists_1.py}{--args format}{lists:lists_1}{%
-A first example for using lists in \python: creating, indexing, printing of and appending elements and other lists to lists.}%
+\gitLoadAndExecPython{lists:lists_1}{}{collections}{lists_1.py}{}%
+\listingPythonAndOutput{lists:lists_1}{lists_1.py}{%
+A first example for using lists in \python:~creating, indexing, printing of and appending elements and other lists to lists.}{}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{lists_2.py}{--args format}{lists:lists_2}{%
-A second example of using lists in \python: inserting and deleting elements, sorting and reversing lists.}%
+\gitLoadAndExecPython{lists:lists_2}{}{collections}{lists_2.py}{}%
+\listingPythonAndOutput{lists:lists_2}{lists_2.py}{%
+A second example of using lists in \python: inserting and deleting elements, sorting and reversing lists.}{}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{lists_3.py}{--args format}{lists:lists_3}{%
-A third example of using lists in \python: slicing, adding, and multiplying lists.}%
+\gitLoadAndExecPython{lists:lists_3}{}{collections}{lists_3.py}{}%
+\listingPythonAndOutput{lists:lists_3}{lists_3.py}{%
+A third example of using lists in \python: slicing, adding, and multiplying lists.}{}%
 %
 In \cref{lst:lists:lists_1}, we provide some first examples for using lists.
 A list can be defined by simply writing its contents, separated by~\pythonilIdx{,} inside square brackets~\pythonil{[...]}\pythonIdx{[\idxdots]}.
@@ -143,17 +146,19 @@
 \hsection{An Example of Errors and a new Tool}%
 \label{sec:listExampleForErrorsAndRuff}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{lists_error.py}{--args format}{lists:lists_error}{%
-A program processing lists which exhibits some subtle errors and inefficiencies.}
-
+\gitLoadAndExecPython{lists:lists_error}{}{collections}{lists_error.py}{}%
+\listingPythonAndOutput{lists:lists_error}{lists_error.py}{%
+A program processing lists which exhibits some subtle errors and inefficiencies.}{}%
+%
 Now, in the previous chapter, we learned that static code analysis tools can help us to discover subtle problems in our programs.
 Obviously, when dealing with more complex datastructures like lists, there are also more potential problems, more mistakes that one could make.
 Let us look at the very short example \cref{lst:lists:lists_error}.
 The program consists of only two lines, \pythonil{my_list: list[str] = list([1, 2, 3])} and \pythonil{print(my_list)}.
 It does not have any \emph{error} in the strict sense.
 We can execute it just fine and it will produce the output \textil{[1, 2, 3]} as shown in \cref{exec:lists:lists_error}.
 
-\gitOutputTool{\programmingWithPythonCodeRepo}{.}{_scripts_/mypy.sh collections lists_error.py}{lists:lists_error:mypy}{%
+\gitExec{exec:lists:lists_error:mypy}{\programmingWithPythonCodeRepo}{.}{_scripts_/mypy.sh collections lists_error.py}%
+\listingToolOutput{lists:lists_error:mypy}{%
 The results of static type checking with \mypy\ of the program given in \cref{lst:lists:lists_error}.}
 
 However, upon closer inspection, we discover some issues.
@@ -179,7 +184,8 @@
 We provide a script for using \ruff\ with a reasonable default configuration in \cref{lst:bash:ruff} on \cpageref{lst:bash:ruff}.%
 }%
 %
-\gitOutputTool{\programmingWithPythonCodeRepo}{.}{_scripts_/ruff.sh collections lists_error.py}{lists:lists_error:ruff}{%
+\gitExec{exec:lists:lists_error:ruff}{\programmingWithPythonCodeRepo}{.}{_scripts_/ruff.sh collections lists_error.py}%
+\listingToolOutput{lists:lists_error:ruff}{%
 The results of linting with \ruff\ of the program given in \cref{lst:lists:lists_error}. (We used the script given in \cref{lst:bash:ruff} on \cpageref{lst:bash:ruff} to apply \ruff.)}%
 %
 Let us apply \ruff\ to the program \textil{lists_error.py} given in \cref{lst:lists:lists_error}, which produces the output \cref{exec:lists:lists_error:ruff}.
@@ -199,8 +205,9 @@
 It basically creates a list via \pythonil{[1, 2, 3]} and then immediately makes a copy of it via the \pythonilIdx{list} function wrapped around the list specification.
 We can leave this outer call to \pythonil{list} away.
 
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{lists_fixed.py}{--args format}{lists:lists_fixed}{%
-The corrected version of~\cref{lst:lists:lists_error}, taking into account the information given by \mypy\ in \cref{exec:lists:lists_error:mypy} and \ruff\ in \cref{exec:lists:lists_error:ruff}.}%
+\gitLoadAndExecPython{lists:lists_fixed}{}{collections}{lists_fixed.py}{}%
+\listingPythonAndOutput{lists:lists_fixed}{lists_fixed.py}{%
+The corrected version of~\cref{lst:lists:lists_error}, taking into account the information given by \mypy\ in \cref{exec:lists:lists_error:mypy} and \ruff\ in \cref{exec:lists:lists_error:ruff}.}{}%
 %
 %
 In \cref{lst:lists:lists_fixed} we implement the three recommendations from the two tools.
@@ -220,10 +227,12 @@
 %
 \FloatBarrier%
 %
-\gitOutputTool{\programmingWithPythonCodeRepo}{.}{_scripts_/mypy.sh collections lists_fixed.py}{lists:lists_fixed:mypy}{%
+\gitExec{exec:lists:lists_fixed:mypy}{\programmingWithPythonCodeRepo}{.}{_scripts_/mypy.sh collections lists_fixed.py}%
+\listingToolOutput{lists:lists_fixed:mypy}{%
 The results of static type checking with \mypy\ of the program given in \cref{lst:lists:lists_fixed}.}%
 %
-\gitOutputTool{\programmingWithPythonCodeRepo}{.}{_scripts_/ruff.sh collections lists_fixed.py}{lists:lists_fixed:ruff}{%
+\gitExec{exec:lists:lists_fixed:ruff}{\programmingWithPythonCodeRepo}{.}{_scripts_/ruff.sh collections lists_fixed.py}%
+\listingToolOutput{lists:lists_fixed:ruff}{%
 The results of static type checking with \ruff\ of the program given in \cref{lst:lists:lists_fixed}.}
 
 Well, this was only a two-line program.

text/main/basics/collections/lists/lists.tex

@@ -1,13 +1,15 @@
 \hsection{Sets}%
 \label{sec:sets}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{sets_1.py}{--args format}{sets:sets_1}{%
+\gitLoadAndExecPython{sets:sets_1}{}{collections}{sets_1.py}{}%
+\listingPythonAndOutput{sets:sets_1}{sets_1.py}{%
 A first example of using sets in \python: creating, modifying, and converting sets. %
-Since sets are unordered, printing them can yield a different result each time a program is executed (see \cref{bp:setsUnordered}).}%
+Since sets are unordered, printing them can yield a different result each time a program is executed (see \cref{bp:setsUnordered}).}{}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{sets_2.py}{--args format}{sets:sets_2}{%
-A second example of using sets in \python: creating sets and set operations (as illustrated in \cref{fig:setOperations}). %
-Since sets are unordered, printing them can yield a different result each time a program is executed (see \cref{bp:setsUnordered}).}%
+\gitLoadAndExecPython{sets:sets_2}{}{collections}{sets_2.py}{}%
+\listingPythonAndOutput{sets:sets_2}{sets_2.py}{%
+A second example of using sets in \python: creating sets and set operations~(as illustrated in \cref{fig:setOperations}). %
+Since sets are unordered, printing them can yield a different result each time a program is executed~(see \cref{bp:setsUnordered}).}{}%
 %
 \begin{figure}%
 \centering%

text/main/basics/collections/sets/sets.tex

@@ -1,16 +1,19 @@
 \hsection{Tuples}%
 \label{sec:tuples}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{tuples_1.py}{--args format}{tuples:tuples_1}{%
-A first example of using tuples in \python: creating, indexing, and printing of tuples.}%
+\gitLoadAndExecPython{tuples:tuples_1}{}{collections}{tuples_1.py}{}%
+\listingPythonAndOutput{tuples:tuples_1}{tuples_1.py}{%
+A first example of using tuples in \python:~creating, indexing, and printing of tuples.}{}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{collections}{tuples_2.py}{--args format}{tuples:tuples_2}{%
-A second example of using tuples in \python: tuples with elements of different types and tuple unpacking.}%
+\gitLoadAndExecPython{tuples:tuples_2}{}{collections}{tuples_2.py}{}%
+\listingPythonAndOutput{tuples:tuples_2}{tuples_2.py}{%
+A second example of using tuples in \python:~tuples with elements of different types and tuple unpacking.}{}%
 %
 \gitPythonAndErrorOutput{\programmingWithPythonCodeRepo}{collections}{tuples_3.py}{--args format}{tuples:tuples_3}{%
-A third example of using tuples in \python: testing the immutability property.}%
+A third example of using tuples in \python:~testing the immutability property.}%
 %
-\gitOutputTool{\programmingWithPythonCodeRepo}{.}{_scripts_/mypy.sh collections tuples_3.py}{tuples:tuples_3:mypy}{%
+\gitExec{exec:tuples:tuples_3:mypy}{\programmingWithPythonCodeRepo}{.}{_scripts_/mypy.sh collections tuples_3.py}%
+\listingToolOutput{tuples:tuples_3:mypy}{%
 The results of static type checking with \mypy\ of the program given in \cref{lst:tuples:tuples_3}.}%
 %
 \pythonIdx{tuple}%

text/main/basics/collections/tuples/tuples.tex

@@ -6,8 +6,9 @@
 This program should just print \inQuotes{Hello World!} to the text output and then exit.
 It therefore will consist of the single statement \pythonil{print("Hello World!")}, as illustrated in \cref{lst:very_first_program}.
 
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{veryFirstProject}{very_first_program.py}{--args format}{very_first_program}{%
-Our very first \python\ program, which just prints \inQuotes{Hello World!}}%
+\gitLoadAndExecPython{very_first_program}{}{veryFirstProject}{very_first_program.py}{}%
+\listingPythonAndOutput{very_first_program}{very_first_program.py}{%
+Our very first \python\ program, which just prints \inQuotes{Hello World!}}{}%
 %
 \begin{figure}%
 \centering%

text/main/basics/gettingStarted/firstProgram/firstProgram.tex

@@ -6,8 +6,9 @@
 Here, \pythonil{name} is the name of the variable and \pythonil{value} be the value that we want to assign to that name.%
 %
 \hsection{A Simple Example of Variable Assignment and Comments in the Code}%
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{variables}{assignment.py}{--args format}{variables:assignment}{%
-A \python\ program showing some examples for variable assignments.}%
+\gitLoadAndExecPython{variables:assignment}{}{variables}{assignment.py}{}%
+\listingPythonAndOutput{variables:assignment}{assignment.py}{%
+A \python\ program showing some examples for variable assignments.}{}%
 %
 \begin{figure}[tb]%
 \centering%
@@ -203,7 +204,7 @@
 
 Now this is a very coarse approximation of~\numberPi.
 We can get closer to the actual ratio if we would use more edges, i.e., higher values of~$e$.
-The ingenious idea of LIU Hui is to use $e$\nobreakdashes-gons with~$e=3*2^n$.
+The ingenious idea of LIU Hui~(刘徽) is to use $e$\nobreakdashes-gons with~$e=3*2^n$.
 For $n=1$, we get the hexagon with $e=6$.
 For $n=2$, we double the edges and have a dodecagon with $e=12$~edges.
 But how do we get the edge length~\liuhuist\ of this dodecagon?
@@ -232,8 +233,9 @@
 \pi_{2e} &= \frac{e}{2} s_{2e}\label{eq:liuhui:approx}%
 \end{align}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{variables}{pi_liu_hui.py}{--args format}{variables:pi_liu_hui}{%
-A \python\ program showing several steps of the approximation of~\numberPi\ using the method of LIU Hui.}%
+\gitLoadAndExecPython{variables:pi_liu_hui}{}{variables}{pi_liu_hui.py}{}%
+\listingPythonAndOutput{variables:pi_liu_hui}{file}{%
+A \python\ program showing several steps of the approximation of~\numberPi\ using the method of LIU Hui~(刘徽).}{}%
 %
 \begin{figure}[tb]%
 \centering%

text/main/basics/variables/assignment/assignment.tex

@@ -21,11 +21,13 @@
 \label{fig:variables:equalityAndIdentity}%
 \end{figure}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{variables}{identity_1.py}{--args format}{variables:identity_1}{%
-An example of the difference between equality and identity\pythonIdx{sqrt}.}%
+\gitLoadAndExecPython{variables:identity_1}{}{variables}{identity_1.py}{}%
+\listingPythonAndOutput{variables:identity_1}{identity_1.py}{%
+An example of the difference between equality and identity\pythonIdx{sqrt}.}{}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{variables}{identity_2.py}{--args format}{variables:identity_2}{%
-An second example of the difference between equality and identity.}%
+\gitLoadAndExecPython{variables:identity_2}{}{variables}{identity_2.py}{}%
+\listingPythonAndOutput{variables:identity_2}{identity_2.py}{%
+An second example of the difference between equality and identity.}{}%
 %
 We use variables to references objects in memory.
 When we compare two variables, we actually compare the objects they reference.

text/main/basics/variables/identity/identity.tex

@@ -1,7 +1,8 @@
 \hsection{Multiple Assignments and Value Swapping}%
 %
-\gitPythonAndOutput{\programmingWithPythonCodeRepo}{variables}{multi_and_swap.py}{--args format}{variables:multi_and_swap}{%
-A \python\ program assigning multiple values to multiple variables and using the same method to swap variable values.}%
+\gitLoadAndExecPython{variables:multi_and_swap}{}{variables}{multi_and_swap.py}{}%
+\listingPythonAndOutput{variables:multi_and_swap}{multi_and_swap.py}{%
+A \python\ program assigning multiple values to multiple variables and using the same method to swap variable values.}{}%
 %
 Let us return to the topic of variables and assignments.
 In \python, we can assign values to multiple variables at once.