diff -rN -u old-darcs-book/en/01-introduction.md new-darcs-book/en/01-introduction.md
--- old-darcs-book/en/01-introduction.md	2024-11-24 01:55:07.625889315 +0000
+++ new-darcs-book/en/01-introduction.md	2024-11-24 01:55:07.625889315 +0000
@@ -6,10 +6,16 @@
 
 So, you want to learn version control, or more specifically, you want to learn
 `darcs`? That's great! I hope this book will give you an interesting perspective
-on how to manage your projects and enable to work with other people all around
-the world. I want to encourage you to follow along with the examples and play
-around with them a bit. Things sometimes happen to make a lot more sense when
-you type them yourself and see things happening right in front of you.
+on how to manage your projects and enables you to work with other people all
+around the world. I want to encourage you to follow along with the examples I
+present in this book and play around with them a bit. Things sometimes happen to
+make a lot more sense when you type them yourself and see things happening right
+in front of you. If you haven't used any kind of version control before I hope
+this book empowers and equips you with new tools that help you to manage your
+projects and improve your collaborations. If you have using traditional
+centralized version control systems as well as other distributed systems I hope
+this book gives you a new perspective on how things can be done differently
+since `darcs` tackles version control in a refreshingly unique way.
 
 In this book I will assume that you are using a Unix or Unix-like
 operating system.
@@ -28,7 +34,7 @@
 
 Ever had to write an imported document over an extended period of time? Then you
 probably know how this works. You start with `important.txt` and a
-couple of weeks you end up with a folder full of files like this
+couple of weeks you end up with a folder full of files like this:
 
 ```
 -rw-r--r--   1 raichoo  raichoo   19182 Jun  7 23:23 important.txt
@@ -67,71 +73,77 @@
 your project? Now here is where the distributed part comes in. Everyone working
 with you on a project has a complete copy of that projects history on their
 computer, so you don't even need to be online to have access to all of that
-information, and they can make their own changes to it and share those with you.
-Nifty huh? We say that every party has their own copy of the project's
-**repository**. That's not always the case, there are so called **centralized
-version control systems** like `svn` where you only have the most recent
-revision of the project our your machine. To access older ones you need to be
-able to access a server.
+information. Your collaborators can make their own changes to the project and
+share those with you. Nifty huh? We say that every party has their own copy of
+the project's **repository**. That's not always the case, there are so called
+**centralized version control systems** like `svn` where you only have the most
+recent revision of the project our your machine. To access older ones you need
+to be able to access a server.
 
 Why `darcs`?
 ------------
 
 In the world of DVCS `darcs` is a pretty unique animal. Most version control
-systems take a **snapshot** of your work and each snapshot depends on a previous
-snapshot. `darcs` doesn't do that. Instead `darcs` keeps track of what actually
-changes. We call that this approach **patch based** and it has some cool effects
-when working with multiple people on a single project.
+systems take a **snapshot** of your work and each snapshot depends on one or
+more previous snapshots. `darcs` doesn't do that. Instead `darcs` keeps track of
+what actually changes. We call that this approach **patch based** and it has
+some cool effects when working with multiple people on a single project.
 
 Let's compare that snapshot based approach with the way `darcs` does it so you
 can see what I mean.
 
 I'm working with my friends tauli and jeanny on a project. tauli has written
-some great code (let's call that patch A) and jeanny has provided some awesome
-illustrations (let's call that patch B) and I want to pull their patches into my
-local copy of the project. gimbar, another friend of mine, wants to do the same
-to their copy.
-
-First, let's look at the snapshot based approach and we are using a tool called
-`git` to illustrate this. If you don't fully understand what's happening here,
-that's fine. It's not necessary to use `darcs` efficiently.
+some great code (let's call that patch `some code`) and jeanny has provided some
+awesome illustrations (let's call that patch `graphics`). I want to pull their
+patches into my local copy of the project. gimbar, another friend of mine, wants
+to do the same to their copy.
+
+First, let's look at the snapshot based approach. We are using a popular tool
+called `git` to illustrate this. If you don't fully understand what's happening
+here, that's fine. It's not necessary to use `darcs` efficiently.
 
 In the beginning gimbar and I both are on the same snapshot which I have
-suggestively called "previous work". Both our repositories look like this.
+suggestively called "previous work". Both our repositories look like this. `git`
+calls its snapshots **commits** and it uniquely identifies them with a 40-digits
+long hexadecimal number, in this example our commit `previous work` would be
+identified by the hash `85b41da2f0a273c6691ee56b13dfe3590d4d0418`.
 
 ```
 commit 85b41da2f0a273c6691ee56b13dfe3590d4d0418
-Author: raichoo
+Author: raichoo@example.com
 Date:   Tue Jun 26 18:58:52 2018 +0200
 
     previous work
 ```
 
 gimbar then pulls in jeanny's and then tauli's patches. gimbar now has the
-following patches in their repository.
+following patches in their repository. It now consists of our `previous work`
+snapshot and then adds jeanny's and tauli's changes on top of that. `git` also
+adds a `Merge` due to the fact how snapshot based version control systems work.
+This is what will cause us problems later.
 
 ```
 commit fd9d393916a76bf716d4af6485556182aaaab5a2
 Merge: c083eb1 425b39d
-Author: gimbar
+Author: gimbar@example.com
 Date:   Tue Jun 26 19:00:37 2018 +0200
 
     Merge
 
 commit 425b39d34417584427ed47218803056974afdfd8
-Author: tauli
+Author: tauli@example.com
 Date:   Tue Jun 26 18:59:53 2018 +0200
 
     some code
 
 commit c083eb19fab5f67694d3dc18e283dcc56798a0aa
-Author: jeanny
+Author: jeanny@example.com
 Date:   Tue Jun 26 18:59:42 2018 +0200
 
     graphics
 
 commit 85b41da2f0a273c6691ee56b13dfe3590d4d0418
-Author: raichoo
+Author: raichoo@example.com
 Date:   Tue Jun 26 18:58:52 2018 +0200
 
     previous work
@@ -145,25 +157,25 @@
 ```
 commit 48f2fa962e67f7bbb12d1f4d6d3b823e1905b16c
 Merge: 425b39d c083eb1
-Author: raichoo
+Author: raichoo@example.com
 Date:   Tue Jun 26 19:00:14 2018 +0200
 
     Merge
 
 commit 425b39d34417584427ed47218803056974afdfd8
-Author: jeanny
+Author: jeanny@example.com
 Date:   Tue Jun 26 18:59:53 2018 +0200
 
     graphics
 
 commit c083eb19fab5f67694d3dc18e283dcc56798a0aa
-Author: tauli
+Author: tauli@example.com
 Date:   Tue Jun 26 18:59:42 2018 +0200
 
     some code
 
 commit 85b41da2f0a273c6691ee56b13dfe3590d4d0418
-Author: raichoo
+Author: raichoo@example.com
 Date:   Tue Jun 26 18:58:52 2018 +0200
 
     previous work
@@ -172,9 +184,8 @@
 
 `git` created those *Merge* patches for us, but they are quite different for
 gimbar and me. They have a different author, a different timestamp and most
-importantly, they have a different hash which is an alpha numeric identifier
-that uniquely identifies a snapshot. Now we have to coordinate how we proceed
-because we are not working on the same snapshot anymore.
+importantly, they have a different commit hash. Now we have to coordinate how we
+proceed because we are not working on the same snapshot anymore.
 
 In the snapshot based approach we end up with both of our repositories in
 different states even though both of us pulled in the same patches, we just have
@@ -184,8 +195,71 @@
 consists of a set of changes and these changes are represented by a patch. The
 order in which we pull them in does not matter. So in the above example gimbar
 and I end up with our repositories being in the same state even though we have
-pulled in the changes in a different order. This approach is great when working
-together with a couple of people because all of them can mix and match and in
-the end we don't need to do extra work to bring everything back together.
+pulled in the changes in a different order. Let's take a look at the same
+example but this time using `darcs`.
+
+As before we start with some `previous work` and we want to base our upcoming
+work on this. Just like `git` `darcs` is using a 40-digit hexadecimal number to
+uniquely identify patches (for the curious, `darcs` internally uses SHA-256 to
+hash the contents of files).
+
+```
+patch 1354819f7c0c26ca865820ad26e184dbcdbde752
+Author: raichoo@example.com
+Date:   Mon Jul  2 19:35:59 CEST 2018
+  * previous work
+```
+
+As before gimbar will first pull in jeanny's and then tauli's changes, bringing
+our repository into the following state.
+
+```
+patch 90865492c33c9aa5e87ffeb2501095a1772d1248
+Author: tauli@example.com
+Date:   Mon Jul  2 19:41:15 CEST 2018
+  * some code
+
+patch e0d0cfa5cee7882d9a4cb5b6032a22b38114f045
+Author: jeanny@example.com
+Date:   Mon Jul  2 19:40:10 CEST 2018
+  * graphics
+
+patch 1354819f7c0c26ca865820ad26e184dbcdbde752
+Author: raichoo@example.com
+Date:   Mon Jul  2 19:35:59 CEST 2018
+  * previous work
+```
+
+Doesn't look that different, except there is no `Merge` patch like there would
+be in `git`. Even better, when I pull those changes in in reversed order I'm
+going to end up with a repository state that looks like this.
+
+```
+patch e0d0cfa5cee7882d9a4cb5b6032a22b38114f045
+Author: jeanny@example.com
+Date:   Mon Jul  2 19:40:10 CEST 2018
+  * graphics
+
+patch 90865492c33c9aa5e87ffeb2501095a1772d1248
+Author: tauli@example.com
+Date:   Mon Jul  2 19:41:15 CEST 2018
+  * some code
+
+patch 1354819f7c0c26ca865820ad26e184dbcdbde752
+Author: raichoo@example.com
+Date:   Mon Jul  2 19:35:59 CEST 2018
+  * previous work
+```
+
+"But hey! You might now have the same patches but they are in reverse order?
+Doesn't that mean the mine an gimbar's repository are different?", I hear you
+say. That's one of the beautiful things about `darcs` and what makes it so
+fundamentally different from other version control systems, even though the
+patches have been applied in reverse order, for `darcs` both of our repositories
+are in the same state.
+
+This approach is great when working together with a couple of people because all
+of them can mix and match just to their liking and in the end we don't need to
+do extra work to bring everything back together.
 
 Of course I've been using `darcs` to write this book. :)