style(sw dev1): fix indent, improve listings

style/definitions.sty

@@ -13,9 +13,9 @@
 \newcommand{\todo}[1]{\textcolor{red}{TODO: #1} \noindent}
 
 \newcommand{\latin}[1]{\textit{#1}}
-\newcommand{\ie}{\latin{i.e.}~}
-\newcommand{\eg}{\latin{e.g.}~}
-\newcommand{\etal}{\latin{et~al.}~}
+\newcommand{\ie}{\latin{i.e.}, }
+\newcommand{\eg}{\latin{e.g.}, }
+\newcommand{\etal}{\latin{et~al.} }
 
 % --- Code & software names, ---------------------------------------------------
 \newcommand\matlab{\textsc{Matlab}\xspace}

workshops/software_development/good_practices_slides.tex

@@ -69,6 +69,7 @@ sectionstyle=style2
   belowskip=1em,
 }
 \newcommand\lst[1]{\lstinline[basicstyle=\ttfamily\normalsize]{#1}}
+\newcommand\lstcmd[1]{\lstinline[basicstyle=\ttfamily\normalsize\color{ulgBlueGreen}]{#1}}
 \newcommand\lstmat[1]{\lstinline[language=matlab]{#1}}
 \newcommand\lstpy[1]{\lstinline[language=python]{#1}}
 
@@ -82,6 +83,7 @@ sectionstyle=style2
 \addbibresource{Workshop-SwDev1.bib}
 
 \usepackage{menukeys}
+\renewmenumacro{\directory}{pathswithfolder} % default: paths
 \newcommand\greencheck{\textcolor{ulgGreen}{\faCheckCircle}}
 \newcommand\redcross{\textcolor{ulgRed}{\faTimesCircle}}
 \newcommand\advancedicon{\Large{\textcolor{ulgOrange}{\faSpaceShuttle}}}

workshops/software_development/sections/filesystem.tex

@@ -42,11 +42,29 @@
       \item Path
     \end{itemize}
 
-	\note[item]{The file system is hierarchical: data is organized following a tree structure.}
-	\note[item]{A directory is an object able to contain other directories and files (e.g., \lst{Master1\_ADP}).}
-	\note[item]{A file is an object that can contain data (e.g., \lst{compute\_wing.m}). A file is identified by its name, and the data it contains is organized using a given format. To help a user to readily identify the format, the filename is usually given a extension, but the extension does not define the format.}
-	\note[item]{A link is special type of file that points to another file or even to a directory (e.g., \lst{matlab.lnk} points to \lst{matlab.exe}).}
-	\note[item]{A path defines the location of an object (e.g. \lst{C:/Program Files/MATLAB/matlab.exe}). They can be absolute and start from the root of the file system, or relative and start from the current location in the data tree. Note that path format depends on operating system (mainly separators).}
+    \note[item]{The file system is hierarchical: data is organized following a
+      tree structure.
+      \begin{itemize}
+        \item A \textbf{directory} is an object able to contain other
+          directories and files \\
+          (\eg \directory{Master1\_ADP}).
+        \item A \textbf{file} is an object that can contain data (\eg
+          \lst{compute\_wing.m}). A file is identified by its name, and the data
+          it contains is organized using a given format. To help a user to
+          readily identify the format, the filename is usually given a
+          extension, but the extension does not define the format.
+        \item A \textbf{link} is a special type of file that points to another
+          file or even to a directory\\
+          (\eg \lst{matlab.lnk} points to \lst{matlab.exe}).
+        \item A \textbf{path} defines the location of an object. They can be
+          absolute and start from the root of the file system (\eg
+          \directory{C:/Program Files/MATLAB/matlab.exe}) , or relative and
+          start from the current location in the data tree\\
+          (\eg \directory{./Documents/Master1\_ADP/compute\_wing.m}). \\
+          Note that the path format depends on operating system (mainly
+          separators).
+      \end{itemize}
+    }
 
   \end{columns}
 \end{frame}
@@ -57,11 +75,11 @@
   \framesubtitle{\insertsubsectionhead}
   Environment variable
   \begin{itemize}
-    \item Pair of name/value that affects the way a process (program) behaves.
+    \item Pair of name/value that affects the way a process (program) behaves
   \end{itemize}
-  When developing, the most important one is often the \lst{PATH} variable.
+  When developing, the most important one is often the \lst{PATH} variable
   \begin{itemize}
-    \item Tells the program where to look for files to read/execute.
+    \item Tells the program where to look for files to read/execute
     \begin{lstlisting}[language=bash,frame=single, linewidth=0.6\textwidth]
 # Windows
 set PATH=C:\\Program\ Files;C:\\Windows
@@ -94,13 +112,14 @@ addpath(genpath('.')
   from \matlab's path.}
 
   \note[item]{You can also add permanently some directories to \matlab path by
-    browsing to the \lst{Set path} option the \lst{Home} tab. This is useful for
-    small libraries that you reuse often. But do not forget to include them
-  explicitly to a project if you need to share it !}
+    browsing to \\
+   \menu{Home>Set path}. This is useful for small libraries that you
+    reuse often. But do not forget to include them explicitly to a project if
+  you need to share it (or send it to for grading)!}
 
-  \note[item]{The base \matlab folder (found in \lst{/Documents/Matlab}) is by
-    default in \matlab's path. This means that any function that you place there
-  will be accessible by all projects.}
+  \note[item]{The base \matlab folder (found in \directory{Documents/Matlab}) is
+    by default in \matlab's path. This means that any function that you place
+  there will be accessible by all projects.}
 
 
 \end{frame}
@@ -122,8 +141,18 @@ addpath(genpath('.')
     \end{itemize}
   \end{columns}
 
-  \note[item]{The file system can be browsed using the graphical user interface or a terminal. Commands must be used to navigate the files using a terminal. On UNIX-based systems, \lst{cd} changes the directory, \lst{mkdir} creates a directory, and \lst{rm} removes a file or a directory.}
-  \note[item]{Environment variables are inherited when opening a terminal session. The variables defined during the session are local and will disappear when the session is closed. }
+  \note[item]{The file system can be browsed using the graphical user interface
+    or a terminal. Commands must be used to navigate the files using a terminal.
+    On UNIX-based systems, \lstcmd{cd} changes the directory, \lstcmd{mkdir}
+  creates a directory, and \lstcmd{rm} removes a file or a directory.}
+
+  \note[item]{The current directory is abbreviated with '\lstcmd{.}', while the
+    parent directory is abbreviated with '\lstcmd{..}'. So to move up in the
+  filesystem, you just need to type '\lstcmd{cd ..}'.}
+
+  \note[item]{Environment variables are inherited when opening a terminal
+    session. The variables defined during the session are local and will
+  disappear when the session is closed. }
 
 \end{frame}
 
@@ -145,9 +174,16 @@ C:\\Program\ Files\\MATLAB\\matlab.exe compute_wing.m
       \end{itemize}
   \end{itemize}
   \vfill
-  
-  \note[item]{A process is usually executed using a command/arguments pair. In the given example, the command is (the path to) \lst{matlab.exe} and the argument is (the path to) the script file \lst{compute\_wing}.}
-  \note[item]{The environment must always be configured properly before a process can be executed. This is done either by installing the software to default locations, or by using scripts that modify the environment permanently or temporarily. For example, on windows, \matlab is usually installed in \lst{Program Files} which is in the variable \lst{PATH} by default, so that it can be called from anywhere in the file system.}
+
+  \note[item]{A process is usually executed using a command/arguments pair. In
+    the given example, the command is (the path to) \lst{matlab.exe} and the
+  argument is (the path to) the script file \lst{compute\_wing}.}
+  \note[item]{The environment must always be configured properly before a
+    process can be executed. This is done either by installing the software to
+    default locations, or by using scripts that modify the environment
+    permanently or temporarily. For example, on windows, \matlab is usually
+    installed in \directory{Program Files} which is in the variable \lst{PATH}
+  by default, so that it can be called from anywhere in the file system.}
 
 \end{frame}
 
@@ -191,6 +227,25 @@ $C:\Users\Thomas\Documents\Work\ADP> my_aircraft.m
 
   \end{lstlisting}
 
-  \note[item]{In the present example, the data tree on the left is similar to what can be found on any Windows computer, and contains \matlab installed at the default location. The tree on the right has been customized by the user \lst{Thomas} according to his needs. It contains a directory \lst{Codes}, where he placed the several libraries that he developed, and a directory \lst{Work}, where he placed the scripts that actually call the library and use them to compute data for the relevant projects. This data structure allows to make a clear difference between 1) the stable software developed by external organizations, 2) the codes or libraries developed by the user, and 3) the script and the results related to a project. The set of three commands provided in the example allows to execute the script \lst{my\_aircraft.m} according to the scenario described above.}
+  \note[item]{In the present example, the data tree on the left is similar to
+    what can be found on any Windows computer, and contains \matlab installed at
+    the default location.\\
+    The tree on the right has been customized by the user \lst{Thomas} according
+    to his needs. It contains a directory \directory{Codes}, where he placed the
+    several libraries that he developed, and a directory \directory{Work}, where
+    he placed the scripts that actually call the library and use them to compute
+  data for the relevant projects.}
+
+  \note[item]{This data structure allows to make a clear difference between
+    \begin{itemize}
+      \item the stable software developed by external organizations,
+      \item the codes or libraries developed by the user,
+      \item the script and the results related to a project. The set of three
+        commands provided in the example allows to execute the script
+        \lst{my\_aircraft.m} according to the scenario described above.
+    \end{itemize}
+  }
+
+
 
 \end{frame}

workshops/software_development/sections/layout.tex

@@ -24,7 +24,7 @@
     \item Keep lines short (80-120 cols)
   \end{itemize}
   \note[item]{As always \textbf{be consistent}!}
-  \note[item]{\matlab: Preferences > Editor > Tab}
+  \note[item]{\matlab: \menu{Preferences > Editor > Tab}}
   \note[item]{\matlab smart indent: \keys{\ctrl + I} (or \keys{\cmd + I} on Mac)}
   \note[item]{Layout also involves deciding between double or single quotes
     (\lst{"}, \lst{'}).\\

workshops/software_development/sections/organization.tex

@@ -56,10 +56,10 @@
 
     \column{0.6\textwidth}
     \begin{itemize}
-      \item \lst{src} folder is where the code is
-      \item \lst{doc} folder only for big projects
-      \item \lst{bin} folder if compiled binaries
-      \item \lst{scripts} folder if additional scripts
+      \item \directory{src} folder is where the code is
+      \item \directory{doc} folder only for big projects
+      \item \directory{bin} folder if compiled binaries
+      \item \directory{scripts} folder if additional scripts
     \end{itemize}
   \end{columns}
 
@@ -115,11 +115,11 @@
 
     \column{0.55\textwidth}
     \begin{itemize}
-      \item The files in the root of \lst{src} are the ones the user is supposed
+      \item The files in the root of \directory{src} are the ones the user is supposed
         to interact with
-      \item \lst{utils} is for small functions you wrote specifically for your
+      \item \directory{utils} is for small functions you wrote specifically for your
         code
-      \item \lst{libs} is for general libraries\\
+      \item \directory{libs} is for general libraries\\
         also called 'package' in \matlab
     \end{itemize}
   \end{columns}
@@ -146,10 +146,11 @@
       \begin{itemize}
         \item In theory, each independent function should be accompanied by a
           specific test function. That verifies its execution.
-        \item In the \lst{test} directory, \lst{utils} is for specific very
+        \item In the \directory{test} directory, \directory{utils} is for specific very
           basic utilities used in the tests.
         \item In \matlab, using \lstmat{runstests('tests')} will run all
-          functions starting with \lst{test\_} in the \lst{tests} directory.
+          functions starting with \lst{test\_} in the \\
+          \directory{tests} directory.
       \end{itemize}
     \end{columns}