minor updates in motivation

content/motivation.md

@@ -1,35 +1,35 @@
 # 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
 
 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,22 +149,24 @@ 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
 
 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).