From bd81c29a70977ca567fef878d2587ca29269ac74 Mon Sep 17 00:00:00 2001
From: Radovan Bast <bast@users.noreply.github.com>
Date: Sun, 1 Sep 2024 16:43:52 +0200
Subject: [PATCH] minor updates in motivation

---
 content/motivation.md | 42 ++++++++++++++++++++++--------------------
 1 file changed, 22 insertions(+), 20 deletions(-)

diff --git a/content/motivation.md b/content/motivation.md
index 60c0e11c..10f7410d 100644
--- a/content/motivation.md
+++ b/content/motivation.md
@@ -1,13 +1,13 @@
 # Motivation
 
-```{objectives}
+:::{objectives}
 - Make sure nobody leaves the workshop without starting to use some form of version control.
 - Discuss the reasons why we advocate distributed version control.
-```
+:::
 
-```{instructor-note}
+:::{instructor-note}
 - 15 min discussion/demonstration
-```
+:::
 
 
 ## Git is all about keeping track of changes
@@ -15,21 +15,21 @@
 We will learn how to keep track of changes first in the web browser.
 Below are screenshots of **tracked changes with Git**
 (from this [example repository](https://github.com/bast/runtest/commits/main/runtest/run.py)):
-```{figure} img/git-log-github.png
+:::{figure} img/git-log-github.png
 :alt: Screenshot of a git log on GitHub
 :width: 80%
 :class: with-border
 
 Web browser, GitHub view
-```
+:::
 Later also using the terminal or the editor
 (the same [example repository](https://github.com/bast/runtest/commits/main/runtest/run.py)):
-```{figure} img/git-log-terminal.png
+:::{figure} img/git-log-terminal.png
 :alt: Screenshot of a git log in terminal
 :width: 80%
 
 The same as above, but the terminal view
-```
+:::
 
 
 ## Why do we need to keep track of versions?
@@ -73,13 +73,13 @@ same time.**
   - Different people can work on the same code/project without interfering
   - You can experiment with an idea and discard it if it turns out to be a bad idea
 
-```{figure} img/gopher/gophers.png
+:::{figure} img/gopher/gophers.png
 :alt: Branching explained with a gopher
 :width: 100%
 
 Image created using <https://gopherize.me/>
 ([inspiration](https://twitter.com/jay_gee/status/703360688618536960)).
-```
+:::
 
 - **Collaboration**: review, compare, share, discuss
 
@@ -98,13 +98,13 @@ you get the same results now?**
 With version control we can "annotate" code
 ([browse this example online](https://github.com/networkx/networkx/blame/main/networkx/algorithms/boundary.py)):
 
-```{figure} img/git-annotate.png
+:::{figure} img/git-annotate.png
 :alt: Example of a git-annotated code with code and history side-by-side
 :width: 100%
 :class: with-border
 
 Example of a git-annotated code with code and history side-by-side.
-```
+:::
 
 
 ## Talking about code
@@ -116,13 +116,13 @@ Which of these two is more practical?
   Oh! But make sure you use the version from August 2023."
 - Or I can send you a [permalink](https://github.com/NordicHPC/sonar/blob/75daafc86582feb06299d6a47c82112f39888152/src/util.rs#L40-L44):
 
-```{figure} img/code-portion.png
+:::{figure} img/code-portion.png
 :alt: Screen-shot of a code portion
 :width: 100%
 :class: with-border
 
 Permalink that points to a code portion.
-```
+:::
 
 
 ## What we typically like to snapshot
@@ -135,11 +135,11 @@ Permalink that points to a code portion.
 - Website sources
 - Data
 
-````{discussion}
+::::{discussion}
   In this example somebody tried to keep track of versions without a version
   control system tool like Git.  Discuss the following directory listing. What
   possible problems do you anticipate with this kind of "version control":
-  ```shell
+  ```text
   myproject-2019.zip
   myproject-2020-February.zip
   myproject-2021-August.zip
@@ -149,14 +149,15 @@ Permalink that points to a code portion.
   myproject-2023-09-21-myversion.zip
   myproject-2023-09-21-newfeature.zip
   ...
+  (100 more files like these)
   ```
 
-  ```{solution}
+  :::{solution}
   - Giving a version to a collaborator and merging changes later with own
     changes sounds like lots of work.
   - What if you discover a bug and want to know since when the bug existed?
-  ```
-````
+  :::
+::::
 
 
 ## Difficulties of version control
@@ -164,7 +165,8 @@ Permalink that points to a code portion.
 Despite the benefits, let's be honest, there are some difficulties:
 
 - One more thing to learn (it's probably worth it and will save you more time in the long run; basic career skill).
-- Difficult if your collaborators don't want to use it (in the worst case, you can version control on your side and email them versions).
+- Difficult if your collaborators don't want to use it (in the worst case, you
+  can version control **on your side** and email them versions).
 - Advanced things can be difficult, but basics are often enough (ask others for help when needed).