Sync docs and metadata

exercises/practice/acronym/.docs/instructions.md

@@ -10,8 +10,8 @@ Punctuation is handled as follows: hyphens are word separators (like whitespace)
 
 For example:
 
-|Input|Output|
-|-|-|
-|As Soon As Possible|ASAP|
-|Liquid-crystal display|LCD|
-|Thank George It's Friday!|TGIF|
+| Input                     | Output |
+| ------------------------- | ------ |
+| As Soon As Possible       | ASAP   |
+| Liquid-crystal display    | LCD    |
+| Thank George It's Friday! | TGIF   |

exercises/practice/allergies/.docs/instructions.md

@@ -22,6 +22,6 @@ Now, given just that score of 34, your program should be able to say:
 - Whether Tom is allergic to any one of those allergens listed above.
 - All the allergens Tom is allergic to.
 
-Note: a given score may include allergens **not** listed above (i.e.  allergens that score 256, 512, 1024, etc.).
+Note: a given score may include allergens **not** listed above (i.e. allergens that score 256, 512, 1024, etc.).
 Your program should ignore those components of the score.
 For example, if the allergy score is 257, your program should only report the eggs (1) allergy.

exercises/practice/armstrong-numbers/.docs/instructions.md

@@ -5,9 +5,9 @@ An [Armstrong number][armstrong-number] is a number that is the sum of its own d
 For example:
 
 - 9 is an Armstrong number, because `9 = 9^1 = 9`
-- 10 is *not* an Armstrong number, because `10 != 1^2 + 0^2 = 1`
+- 10 is _not_ an Armstrong number, because `10 != 1^2 + 0^2 = 1`
 - 153 is an Armstrong number, because: `153 = 1^3 + 5^3 + 3^3 = 1 + 125 + 27 = 153`
-- 154 is *not* an Armstrong number, because: `154 != 1^3 + 5^3 + 4^3 = 1 + 125 + 64 = 190`
+- 154 is _not_ an Armstrong number, because: `154 != 1^3 + 5^3 + 4^3 = 1 + 125 + 64 = 190`
 
 Write some code to determine whether a number is an Armstrong number.
 

exercises/practice/atbash-cipher/.docs/instructions.md

@@ -1,6 +1,6 @@
 # Instructions
 
-Create an implementation of the atbash cipher, an ancient encryption system created in the Middle East.
+Create an implementation of the Atbash cipher, an ancient encryption system created in the Middle East.
 
 The Atbash cipher is a simple substitution cipher that relies on transposing all the letters in the alphabet such that the resulting alphabet is backwards.
 The first letter is replaced with the last letter, the second with the second-last, and so on.

exercises/practice/atbash-cipher/.meta/config.json

@@ -25,7 +25,7 @@
       ".meta/example.h"
     ]
   },
-  "blurb": "Create an implementation of the atbash cipher, an ancient encryption system created in the Middle East.",
+  "blurb": "Create an implementation of the Atbash cipher, an ancient encryption system created in the Middle East.",
   "source": "Wikipedia",
   "source_url": "https://en.wikipedia.org/wiki/Atbash"
 }

exercises/practice/binary-search-tree/.meta/config.json

@@ -24,6 +24,5 @@
     ]
   },
   "blurb": "Insert and search for numbers in a binary tree.",
-  "source": "Josh Cheek",
-  "source_url": "https://twitter.com/josh_cheek"
+  "source": "Josh Cheek"
 }

exercises/practice/binary-search/.docs/instructions.md

@@ -11,7 +11,7 @@ Binary search only works when a list has been sorted.
 
 The algorithm looks like this:
 
-- Find the middle element of a *sorted* list and compare it with the item we're looking for.
+- Find the middle element of a _sorted_ list and compare it with the item we're looking for.
 - If the middle element is our item, then we're done!
 - If the middle element is greater than our item, we can eliminate that element and all the elements **after** it.
 - If the middle element is less than our item, we can eliminate that element and all the elements **before** it.

exercises/practice/binary/.docs/instructions.md

@@ -20,7 +20,7 @@ A number 23 in base 10 notation can be understood as a linear combination of pow
 - The rightmost digit gets multiplied by 10^0 = 1
 - The next number gets multiplied by 10^1 = 10
 - ...
-- The *n*th number gets multiplied by 10^*(n-1)*.
+- The nth number gets multiplied by 10^_(n-1)_.
 - All these values are summed.
 
 So: `23 => 2*10^1 + 3*10^0 => 2*10 + 3*1 = 23 base 10`

exercises/practice/circular-buffer/.docs/instructions.md

@@ -4,39 +4,55 @@ A circular buffer, cyclic buffer or ring buffer is a data structure that uses a
 
 A circular buffer first starts empty and of some predefined length.
 For example, this is a 7-element buffer:
-<!-- prettier-ignore -->
-    [ ][ ][ ][ ][ ][ ][ ]
+
+```text
+[ ][ ][ ][ ][ ][ ][ ]
+```
 
 Assume that a 1 is written into the middle of the buffer (exact starting location does not matter in a circular buffer):
-<!-- prettier-ignore -->
-    [ ][ ][ ][1][ ][ ][ ]
+
+```text
+[ ][ ][ ][1][ ][ ][ ]
+```
 
 Then assume that two more elements are added — 2 & 3 — which get appended after the 1:
-<!-- prettier-ignore -->
-    [ ][ ][ ][1][2][3][ ]
+
+```text
+[ ][ ][ ][1][2][3][ ]
+```
 
 If two elements are then removed from the buffer, the oldest values inside the buffer are removed.
 The two elements removed, in this case, are 1 & 2, leaving the buffer with just a 3:
-<!-- prettier-ignore -->
-    [ ][ ][ ][ ][ ][3][ ]
+
+```text
+[ ][ ][ ][ ][ ][3][ ]
+```
 
 If the buffer has 7 elements then it is completely full:
-<!-- prettier-ignore -->
-    [5][6][7][8][9][3][4]
+
+```text
+[5][6][7][8][9][3][4]
+```
 
 When the buffer is full an error will be raised, alerting the client that further writes are blocked until a slot becomes free.
 
 When the buffer is full, the client can opt to overwrite the oldest data with a forced write.
 In this case, two more elements — A & B — are added and they overwrite the 3 & 4:
-<!-- prettier-ignore -->
-    [5][6][7][8][9][A][B]
+
+```text
+[5][6][7][8][9][A][B]
+```
 
 3 & 4 have been replaced by A & B making 5 now the oldest data in the buffer.
 Finally, if two elements are removed then what would be returned is 5 & 6 yielding the buffer:
-<!-- prettier-ignore -->
-    [ ][ ][7][8][9][A][B]
+
+```text
+[ ][ ][7][8][9][A][B]
+```
 
 Because there is space available, if the client again uses overwrite to store C & D then the space where 5 & 6 were stored previously will be used not the location of 7 & 8.
 7 is still the oldest element and the buffer is once again full.
-<!-- prettier-ignore -->
-    [C][D][7][8][9][A][B]
+
+```text
+[C][D][7][8][9][A][B]
+```

exercises/practice/clock/.meta/config.json

@@ -25,6 +25,5 @@
     ]
   },
   "blurb": "Implement a clock that handles times without dates.",
-  "source": "Pairing session with Erin Drummond",
-  "source_url": "https://twitter.com/ebdrummond"
+  "source": "Pairing session with Erin Drummond"
 }

exercises/practice/complex-numbers/.docs/instructions.md

@@ -1,29 +1,100 @@
 # Instructions
 
-A complex number is a number in the form `a + b * i` where `a` and `b` are real and `i` satisfies `i^2 = -1`.
+A **complex number** is expressed in the form `z = a + b * i`, where:
 
-`a` is called the real part and `b` is called the imaginary part of `z`.
-The conjugate of the number `a + b * i` is the number `a - b * i`.
-The absolute value of a complex number `z = a + b * i` is a real number `|z| = sqrt(a^2 + b^2)`. The square of the absolute value `|z|^2` is the result of multiplication of `z` by its complex conjugate.
+- `a` is the **real part** (a real number),
 
-The sum/difference of two complex numbers involves adding/subtracting their real and imaginary parts separately:
-`(a + i * b) + (c + i * d) = (a + c) + (b + d) * i`,
-`(a + i * b) - (c + i * d) = (a - c) + (b - d) * i`.
+- `b` is the **imaginary part** (also a real number), and
 
-Multiplication result is by definition
-`(a + i * b) * (c + i * d) = (a * c - b * d) + (b * c + a * d) * i`.
+- `i` is the **imaginary unit** satisfying `i^2 = -1`.
 
-The reciprocal of a non-zero complex number is
-`1 / (a + i * b) = a/(a^2 + b^2) - b/(a^2 + b^2) * i`.
+## Operations on Complex Numbers
 
-Dividing a complex number `a + i * b` by another `c + i * d` gives:
-`(a + i * b) / (c + i * d) = (a * c + b * d)/(c^2 + d^2) + (b * c - a * d)/(c^2 + d^2) * i`.
+### Conjugate
 
-Raising e to a complex exponent can be expressed as `e^(a + i * b) = e^a * e^(i * b)`, the last term of which is given by Euler's formula `e^(i * b) = cos(b) + i * sin(b)`.
+The conjugate of the complex number `z = a + b * i` is given by:
 
-Implement the following operations:
+```text
+zc = a - b * i
+```
 
-- addition, subtraction, multiplication and division of two complex numbers,
-- conjugate, absolute value, exponent of a given complex number.
+### Absolute Value
 
-Assume the programming language you are using does not have an implementation of complex numbers.
+The absolute value (or modulus) of `z` is defined as:
+
+```text
+|z| = sqrt(a^2 + b^2)
+```
+
+The square of the absolute value is computed as the product of `z` and its conjugate `zc`:
+
+```text
+|z|^2 = z * zc = a^2 + b^2
+```
+
+### Addition
+
+The sum of two complex numbers `z1 = a + b * i` and `z2 = c + d * i` is computed by adding their real and imaginary parts separately:
+
+```text
+z1 + z2 = (a + b * i) + (c + d * i)
+        = (a + c) + (b + d) * i
+```
+
+### Subtraction
+
+The difference of two complex numbers is obtained by subtracting their respective parts:
+
+```text
+z1 - z2 = (a + b * i) - (c + d * i)
+        = (a - c) + (b - d) * i
+```
+
+### Multiplication
+
+The product of two complex numbers is defined as:
+
+```text
+z1 * z2 = (a + b * i) * (c + d * i)
+        = (a * c - b * d) + (b * c + a * d) * i
+```
+
+### Reciprocal
+
+The reciprocal of a non-zero complex number is given by:
+
+```text
+1 / z = 1 / (a + b * i)
+      = a / (a^2 + b^2) - b / (a^2 + b^2) * i
+```
+
+### Division
+
+The division of one complex number by another is given by:
+
+```text
+z1 / z2 = z1 * (1 / z2)
+        = (a + b * i) / (c + d * i)
+        = (a * c + b * d) / (c^2 + d^2) + (b * c - a * d) / (c^2 + d^2) * i
+```
+
+### Exponentiation
+
+Raising _e_ (the base of the natural logarithm) to a complex exponent can be expressed using Euler's formula:
+
+```text
+e^(a + b * i) = e^a * e^(b * i)
+              = e^a * (cos(b) + i * sin(b))
+```
+
+## Implementation Requirements
+
+Given that you should not use built-in support for complex numbers, implement the following operations:
+
+- **addition** of two complex numbers
+- **subtraction** of two complex numbers
+- **multiplication** of two complex numbers
+- **division** of two complex numbers
+- **conjugate** of a complex number
+- **absolute value** of a complex number
+- **exponentiation** of _e_ (the base of the natural logarithm) to a complex number

exercises/practice/darts/.docs/instructions.md

@@ -1,11 +1,13 @@
 # Instructions
 
-Write a function that returns the earned points in a single toss of a Darts game.
+Calculate the points scored in a single toss of a Darts game.
 
 [Darts][darts] is a game where players throw darts at a [target][darts-target].
 
 In our particular instance of the game, the target rewards 4 different amounts of points, depending on where the dart lands:
 
+![Our dart scoreboard with values from a complete miss to a bullseye](https://assets.exercism.org/images/exercises/darts/darts-scoreboard.svg)
+
 - If the dart lands outside the target, player earns no points (0 points).
 - If the dart lands in the outer circle of the target, player earns 1 point.
 - If the dart lands in the middle circle of the target, player earns 5 points.
@@ -14,10 +16,16 @@ In our particular instance of the game, the target rewards 4 different amounts o
 The outer circle has a radius of 10 units (this is equivalent to the total radius for the entire target), the middle circle a radius of 5 units, and the inner circle a radius of 1.
 Of course, they are all centered at the same point — that is, the circles are [concentric][] defined by the coordinates (0, 0).
 
-Write a function that given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), returns the correct amount earned by a dart landing at that point.
+Given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), calculate the correct score earned by a dart landing at that point.
+
+## Credit
+
+The scoreboard image was created by [habere-et-dispertire][habere-et-dispertire] using [Inkscape][inkscape].
 
 [darts]: https://en.wikipedia.org/wiki/Darts
 [darts-target]: https://en.wikipedia.org/wiki/Darts#/media/File:Darts_in_a_dartboard.jpg
 [concentric]: https://mathworld.wolfram.com/ConcentricCircles.html
 [cartesian-coordinates]: https://www.mathsisfun.com/data/cartesian-coordinates.html
 [real-numbers]: https://www.mathsisfun.com/numbers/real-numbers.html
+[habere-et-dispertire]: https://exercism.org/profiles/habere-et-dispertire
+[inkscape]: https://en.wikipedia.org/wiki/Inkscape

exercises/practice/darts/.meta/config.json

@@ -18,6 +18,6 @@
       ".meta/example.h"
     ]
   },
-  "blurb": "Write a function that returns the earned points in a single toss of a Darts game.",
+  "blurb": "Calculate the points scored in a single toss of a Darts game.",
   "source": "Inspired by an exercise created by a professor Della Paolera in Argentina"
 }

exercises/practice/eliuds-eggs/.docs/introduction.md

@@ -12,36 +12,54 @@ The position information encoding is calculated as follows:
 2. Convert the number from binary to decimal.
 3. Show the result on the display.
 
-Example 1:
+## Example 1
+
+![Seven individual nest boxes arranged in a row whose first, third, fourth and seventh nests each have a single egg.](https://assets.exercism.org/images/exercises/eliuds-eggs/example-1-coop.svg)
 
 ```text
-Chicken Coop:
  _ _ _ _ _ _ _
 |E| |E|E| | |E|
+```
+
+### Resulting Binary
+
+![1011001](https://assets.exercism.org/images/exercises/eliuds-eggs/example-1-binary.svg)
+
+```text
+ _ _ _ _ _ _ _
+|1|0|1|1|0|0|1|
+```
 
-Resulting Binary:
- 1 0 1 1 0 0 1
+### Decimal number on the display
 
-Decimal number on the display:
 89
 
-Actual eggs in the coop:
+### Actual eggs in the coop
+
 4
+
+## Example 2
+
+![Seven individual nest boxes arranged in a row where only the fourth nest has an egg.](https://assets.exercism.org/images/exercises/eliuds-eggs/example-2-coop.svg)
+
+```text
+ _ _ _ _ _ _ _
+| | | |E| | | |
 ```
 
-Example 2:
+### Resulting Binary
+
+![0001000](https://assets.exercism.org/images/exercises/eliuds-eggs/example-2-binary.svg)
 
 ```text
-Chicken Coop:
- _ _ _ _ _ _ _ _
-| | | |E| | | | |
+ _ _ _ _ _ _ _
+|0|0|0|1|0|0|0|
+```
 
-Resulting Binary:
- 0 0 0 1 0 0 0 0
+### Decimal number on the display
 
-Decimal number on the display:
 16
 
-Actual eggs in the coop:
+### Actual eggs in the coop
+
 1
-```