getting started: install python

thomasWeise · thomasWeise · commit d893df3b885c · 2024-06-21T13:41:05.000+08:00
diff --git a/notation/notation.sty b/notation/notation.sty
@@ -1,3 +1,5 @@
 %
+\RequirePackage{notation/software}%
 \RequirePackage{notation/sources}%
+\RequirePackage{notation/terms}%
 %
diff --git a/notation/software.sty b/notation/software.sty
@@ -0,0 +1,49 @@
+%%
+%% Access to Source Codes
+%%
+%
+\protected\gdef\softwareStyle#1{\textrm{#1}}%
+%
+\newglossaryentry{python}{%
+name={\softwareStyle{Python}},
+sort={Python},
+description={The \href{https://python.org/}{\softwareStyle{Python}} programming language, i.e., what you will learn about in this book.}
+}%
+\protected\gdef\python{\gls{python}}%
+%
+\xdef\pythonVersion{3.10}%
+\protected\gdef\pythonWithVersion{\softwareStyle{\python~\pythonVersion}}%
+%
+\newglossaryentry{ubuntu}{%
+name={\softwareStyle{Ubuntu}},
+sort={Ubuntu},
+description={%
+\href{https://ubuntu.com/}{\softwareStyle{Ubuntu}} is a variant of the open source operating system \linux. %
+We recommend that you use this operating system to follow this class, for software development, and for research. %
+If you are in China, you can download it from \expandafter{\ubuntuDownloadUrl}.%
+}%
+}%
+\protected\gdef\ubuntu{\gls{ubuntu}}%
+\xdef\ubuntuDownloadUrl{https://mirrors.ustc.edu.cn/ubuntu-releases/}%
+%
+\newglossaryentry{linux}{%
+name={\softwareStyle{Linux}},
+sort={Linux},
+description={%
+\href{https://www.linux.org/}{\softwareStyle{Linux}} is an open source operating system, i.e., a free alternative for \windows. %
+Its variant \ubuntu\ is particularly easy to use and install. %
+We recommend using it for this course, for software development, and for research.%
+}%
+}%
+\protected\gdef\linux{\gls{linux}}%
+%
+\newglossaryentry{windows}{%
+name={\softwareStyle{Windows}},
+sort={Windows},
+description={%
+\href{https://www.microsoft.com/windows/}{\softwareStyle{Microsoft Windows}} is a commerical proprietary operating system. %
+It is widely spread, but we recommend using a \linux\ variant such as \ubuntu\ for software development and for our course.%
+}%
+}%
+\protected\gdef\windows{\gls{windows}}%
+%
diff --git a/notation/terms.sty b/notation/terms.sty
@@ -0,0 +1,16 @@
+%%
+%% Access to Source Codes
+%%
+%
+%
+\newglossaryentry{terminal}{%
+name={terminal},
+plural={terminals},
+description={%
+A terminal is a text-based window where you can enter commands and execute them by pressing \keys{\return}. %
+Knowing what a terminal is and how to use it is very essential in any programming- or system administration-related task. %
+If you want to open a terminal under \windows, you can press \keys{\OSwin + R}, type in \bashil{cmd}, and hit \keys{\return}, as shown, e.g., in \cpageref{fig:installingPythonWindows01openTerminal}. %
+Under \ubuntu\ \linux, \keys{\ctrl+\Alt+T} opens a terminal.%
+}
+}%
+%
diff --git a/styles/floats.sty b/styles/floats.sty
@@ -0,0 +1,12 @@
+%%
+%% Figure and Table tools.
+%%
+%
+\RequirePackage{subfig}%
+%
+\protected\gdef\tightbox#1{\bgroup%
+\fboxsep=0pt%
+\fboxrule=0.5pt%
+\mbox{\fcolorbox{black}{listing-background}{\mbox{#1}}}%
+\egroup}%
+%
diff --git a/styles/href.sty b/styles/href.sty
@@ -20,3 +20,4 @@ bookmarksdepth=3%
 \renewcommand{\subsubsectionautorefname}{Section}%
 \renewcommand{\chapterautorefname}{Chapter}%
 %
+%
diff --git a/styles/keys.sty b/styles/keys.sty
@@ -0,0 +1,13 @@
+%%
+%% Keyboard keys.
+%%
+%
+\RequirePackage[os=win]{menukeys}%
+\renewmenumacro{\keys}[+]{shadowedroundedkeys}%
+%
+%% see https://tex.stackexchange.com/questions/387952
+\RequirePackage{fontawesome}%
+\tw@make@key@box{OS@mac}{\faApple}%
+\tw@make@key@box{OS@win}{\faWindows}%
+\tw@make@key@macro*{\OS}%
+%
diff --git a/styles/listing.sty b/styles/listing.sty
@@ -85,19 +85,25 @@ literate=%
 \mbox{\fcolorbox{listing-rule}{listing-background}{\mbox{#1}}}%
 \egroup}%
 %
-%% print some code inline
+%% print some Python code inline
 %% #1 the optional args
 %% #2 the code to be printed inline
-\gdef\codeil#1{%
+\gdef\pythonil#1{%
 \@inlinelistingbox{\lstinline[style=python_style]$#1$}}%
 %
+%% print some Bash code inline
+%% #1 the optional args
+%% #2 the code to be printed inline
+\gdef\bashil#1{%
+\@inlinelistingbox{\lstinline[language=bash]$#1$}}%
+%
 \newlength\@lstbasicstylesheight%
 \settoheight{\@lstbasicstylesheight}{\mbox{\bgroup\@lstbasicstyle{s}\egroup}}%
 %
-%% print some code inline with an 's' added for plural
+%% print some Python code inline with an 's' added for plural
 %% #1 the optional args
 %% #2 the code to be printed inline
-\gdef\codeils#1{%
+\gdef\pythons#1{%
 \@inlinelistingbox{\lstinline[style=python_style]$#1$\resizebox{!}{\@lstbasicstylesheight}{\color{darkgray}s}}}%
 %
 %%
diff --git a/styles/styles.sty b/styles/styles.sty
@@ -12,7 +12,11 @@
 \RequirePackage{styles/colors}%
 \RequirePackage{styles/bibliography}%
 \RequirePackage{styles/tables}%
+\RequirePackage{styles/floats}%
+\RequirePackage{styles/keys}%
+%
 \RequirePackage{styles/href}%
+%
 \RequirePackage{styles/latexgit}%
 \RequirePackage{styles/listing}%
 \RequirePackage{styles/glossary}%
diff --git a/text/back/backmatter.tex b/text/back/backmatter.tex
@@ -11,5 +11,6 @@
 %\printRulesOfThumb%
 %\printsymbols%
 %\printacronyms%
+\printglossaries%
 \printbibliography%
 %
diff --git a/text/main/basics/basics.tex b/text/main/basics/basics.tex
@@ -0,0 +1,12 @@
+\hsection{Basics}%
+%
+In this part of the book, we will gain the following abilities:%
+%
+\begin{itemize}%
+\item read, write, and execute simple \python\ programs%
+\item use some tools to help us looking for errors%
+\end{itemize}%
+%
+\hinput{gettingStarted}{gettingStarted.tex}%
+\endhsection%
+%
diff --git a/text/main/basics/gettingStarted/gettingStarted.tex b/text/main/basics/gettingStarted/gettingStarted.tex
@@ -0,0 +1,8 @@
+\hsection{Getting Started}%
+%
+This course should be a practical course, so we should get started with practical things right away.
+%
+\hinput{installingPython}{installingPython}%
+%
+\endhsection%
+%
diff --git a/text/main/basics/gettingStarted/installingPython/installingPython.tex b/text/main/basics/gettingStarted/installingPython/installingPython.tex
@@ -0,0 +1,18 @@
+\hsection{Installing Python}%
+In order to learn and use \python, we first need to install it.
+There are two major versions of \python\ out there: \python~\softwareStyle{2} and \python~\softwareStyle{3}.
+Our course focuses entirely on \python~\softwareStyle{3}.
+We assume that you have installed \pythonWithVersion\ or newer.
+Hopefully, you could figure out how to do that by yourself -- but we will at least provide some quick guide here as well.
+Help can be found at the following resources:%
+%
+\begin{itemize}%
+\item Python Downloads at \url{https://www.python.org/downloads/}%
+\item the Python 3 Installation \& Setup Guide at \url{https://realpython.com/installing-python/}%
+\end{itemize}%
+%
+\hinput{installingPythonWindows}{installingPythonWindows}%
+\hinput{pythonUnderUbuntu}{pythonUnderUbuntu}%
+%
+\endhsection%
+%
diff --git a/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows.tex b/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows.tex
@@ -0,0 +1,65 @@
+\hsection{Installing Python~3 under Microsoft Windows}%
+%
+\begin{figure}%
+\centering%
+\subfloat[][Opening the \gls{terminal} under \windows: \keys{\OSwin + R}, \bashil{cmd}, \keys{\return}.]{%
+\label{fig:installingPythonWindows01openTerminal}%
+\tightbox{\includegraphics[height=2.8cm]{\currentDir/installingPythonWindows01openTerminal}}%
+}%
+\hfill%
+%
+\subfloat[][Trying to get the \python\ version via \bashil{python3 --version}, but it is not installed.%
+\label{fig:installingPythonWindows02pythonVersion}]{%
+\tightbox{\includegraphics[height=2.8cm]{\currentDir/installingPythonWindows02pythonVersion}}%
+}%
+%
+\hfill%
+%
+\subfloat[][Installing it by typing \bashil{python3} and hitting \keys{\return}.%
+\label{fig:installingPythonWindows03python}]{%
+\tightbox{\includegraphics[height=2.8cm]{\currentDir/installingPythonWindows03python}}%
+}%
+%
+\\[10pt]%
+%
+\subfloat[][The install screen, where we click \keys{Get}.%
+\label{fig:installingPythonWindows04installGet}]{%
+\tightbox{\includegraphics[width=0.485\linewidth]{\currentDir/installingPythonWindows04installGet}}%
+}%
+\hfill%
+%
+\subfloat[][The install screen, downloading \python.%
+\label{fig:installingPythonWindows05downloading}]{%
+\tightbox{\includegraphics[width=0.485\linewidth]{\currentDir/installingPythonWindows05downloading}}%
+}%
+%
+\\[10pt]%
+%
+\subfloat[][The installation is finished.%
+\label{fig:installingPythonWindows06finished}]{%
+\tightbox{\includegraphics[height=4cm]{\currentDir/installingPythonWindows06finished}}%
+}%
+%
+\hfill%
+%
+\subfloat[][And the \bashil{python3 --version} command now works in the terminal.%
+\label{fig:installingPythonWindows07pythonVersion}]{%
+\tightbox{\includegraphics[height=4cm]{\currentDir/installingPythonWindows07pythonVersion}}%
+}%
+%
+\caption{Cropped screenshots of the installation steps for \python\ on \windows.}%
+\label{fig:installPythonWindows}%
+\end{figure}%
+%
+Example installation steps for \python\ on \windows\ (version~10) are sketched in \cref{fig:installPythonWindows}.
+First, you would open a \gls{terminal} using \keys{\OSwin + R}, type in \bashil{cmd}, and hit \keys{\return}, as shown in \cref{fig:installingPythonWindows01openTerminal}.
+If \python\ is installed, then typing \bashil{python3 --version} in the terminal and hitting \keys{\return} would print the version of the \python\ installation.
+If it is not installed, however, then \windows\ will print a message informing you that \python\ is not yet installed and that you can reach the web installer by just typing \bashil{python3} (and hitting \keys{\return}, of course).0
+We do this in \cref{fig:installingPythonWindows03python}, which leads us to the installation screen (\cref{fig:installingPythonWindows04installGet}), where we need to press the \keys{Get} button.
+This will then download (\cref{fig:installingPythonWindows05downloading}) and install \python.
+When this process is completed, the screen just shows nothing (\cref{fig:installingPythonWindows06finished}).
+If we go back to the \gls{terminal} and again try \bashil{python3 --version}, it will now work and print the version of our \python\ installation.
+In our case, this is version~\softwareStyle{3.12}.%
+%
+\endhsection%
+%
diff --git a/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows01openTerminal.png b/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows01openTerminal.png
diff --git a/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows02pythonVersion.png b/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows02pythonVersion.png
diff --git a/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows03python.png b/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows03python.png
diff --git a/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows04installGet.png b/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows04installGet.png
diff --git a/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows05downloading.png b/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows05downloading.png
diff --git a/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows06finished.png b/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows06finished.png
diff --git a/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows07pythonVersion.png b/text/main/basics/gettingStarted/installingPython/installingPythonWindows/installingPythonWindows07pythonVersion.png
diff --git a/text/main/basics/gettingStarted/installingPython/pythonUnderUbuntu/pythonUnderUbuntu.tex b/text/main/basics/gettingStarted/installingPython/pythonUnderUbuntu/pythonUnderUbuntu.tex
@@ -0,0 +1,15 @@
+\hsection{Python under Ubuntu}%
+%
+\begin{figure}%
+\centering%
+\includegraphics[width=0.7\linewidth]{\currentDir/ubuntuTerminalPythonVersion}%
+\caption{Under \ubuntu\ \linux~\softwareStyle{22.04}, typing \bashil{python3 --version} in a \gls{terminal} and hitting return yields version~\softwareStyle{3.10}.}%
+\label{fig:ubuntuTerminalPythonVersion}%
+\end{figure}%
+%
+Under \ubuntu\ \linux, \python~\softwareStyle{3} is already pre-installed.
+You can open a \gls{terminal}, type \bashil{python3 --version}, hit \keys{\return}, and get the result illustrated in \cref{fig:ubuntuTerminalPythonVersion}:%
+My system has \python\ version~\softwareStyle{3.10} installed.%
+%
+\endhsection%
+%
diff --git a/text/main/basics/gettingStarted/installingPython/pythonUnderUbuntu/ubuntuTerminalPythonVersion.pdf b/text/main/basics/gettingStarted/installingPython/pythonUnderUbuntu/ubuntuTerminalPythonVersion.pdf
diff --git a/text/main/introduction/introduction.tex b/text/main/introduction/introduction.tex
@@ -35,7 +35,7 @@
 Maybe some of the libraries you use get outdated and need to be replaced?
 There are several reasonable situations in which a totally different person may need to work, read, modify, and improve \emph{your} code.
 
-Or maybe you are a researcher, using \texttt{Python} to implement some algorithm and to run an experiment.
+Or maybe you are a researcher, using \python\ to implement some algorithm and to run an experiment.
 In order to make your experiments and results replicable, you would probably want to publish your algorithm implementation together with the results.
 This only makes sense if your code is at least a bit readable.
 
@@ -50,7 +50,10 @@
 One may  hope that, as one of the very first things, surgery students in medical school are taught to wash their hands before performing surgery.
 Hence, we will teach you how to write clean, well-documented, and properly tested programs.
 Right from the start.
-Such that all of your code will be reusable, readable, clear, clean, and beautiful.%
+Such that all of your code will be reusable, readable, clear, clean, and beautiful.
+
+As a result, this will be a course which is very practice centered.
+Our goal is to get familiar with programming, with the programming language \python, and with the tools and ecosystem surrounding it.%
 %
 \endhsection\endhsection%
 %
diff --git a/text/main/mainmatter.tex b/text/main/mainmatter.tex
@@ -3,4 +3,5 @@
 \bookmarksetup{startatroot}%
 %
 \hinput{introduction}{introduction.tex}%
+\hinput{basics}{basics.tex}%
 %

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
`1`	`1`	`%`
	`2`	`+\RequirePackage{notation/software}%`
`2`	`3`	`\RequirePackage{notation/sources}%`
	`4`	`+\RequirePackage{notation/terms}%`
`3`	`5`	`%`
Original file line number	Diff line number	Diff line change
`@@ -20,3 +20,4 @@ bookmarksdepth=3%`
`20`	`20`	`\renewcommand{\subsubsectionautorefname}{Section}%`
`21`	`21`	`\renewcommand{\chapterautorefname}{Chapter}%`
`22`	`22`	`%`
	`23`	`+%`
Original file line number	Diff line number	Diff line change
`@@ -11,5 +11,6 @@`
`11`	`11`	`%\printRulesOfThumb%`
`12`	`12`	`%\printsymbols%`
`13`	`13`	`%\printacronyms%`
	`14`	`+\printglossaries%`
`14`	`15`	`\printbibliography%`
`15`	`16`	`%`