Sync docs and metadata

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

@@ -1,4 +1,4 @@
-# Description
+# Instructions
 
 Convert a phrase to its acronym.
 
@@ -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/acronym/.meta/config.json

@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "blurb": "Convert a phrase to its acronym.",
+  "blurb": "Convert a long phrase to its acronym.",
   "source": "Julien Vanier",
   "source_url": "https://github.com/monkbroc"
 }

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,11 +1,9 @@
-# Description
+# 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.
+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.
 
 An Atbash cipher for the Latin alphabet would be as follows:
 
@@ -14,13 +12,12 @@ Plain:  abcdefghijklmnopqrstuvwxyz
 Cipher: zyxwvutsrqponmlkjihgfedcba
 ```
 
-It is a very weak cipher because it only has one possible key, and it is
-a simple mono-alphabetic substitution cipher. However, this may not have
-been an issue in the cipher's time.
+It is a very weak cipher because it only has one possible key, and it is a simple mono-alphabetic substitution cipher.
+However, this may not have been an issue in the cipher's time.
 
-Ciphertext is written out in groups of fixed length, the traditional group size
-being 5 letters, leaving numbers unchanged, and punctuation is excluded.
+Ciphertext is written out in groups of fixed length, the traditional group size being 5 letters, leaving numbers unchanged, and punctuation is excluded.
 This is to make it harder to guess things based on word boundaries.
+All text will be encoded as lowercase letters.
 
 ## Examples
 

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

@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "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/.docs/instructions.md

@@ -1,36 +1,29 @@
 # Instructions
 
-Implement a binary search algorithm. Do not use any COBOL proprietary
-search routines (eg. SEARCH).
+Your task is to implement a binary search algorithm.
 
-Searching a sorted collection is a common task. A dictionary is a sorted
-list of word definitions. Given a word, one can find its definition. A
-telephone book is a sorted list of people's names, addresses, and
-telephone numbers. Knowing someone's name allows one to quickly find
-their telephone number and address.
+A binary search algorithm finds an item in a list by repeatedly splitting it in half, only keeping the half which contains the item we're looking for.
+It allows us to quickly narrow down the possible locations of our item until we find it, or until we've eliminated all possible locations.
 
-If the list to be searched contains more than a few items (a dozen, say)
-a binary search will require far fewer comparisons than a linear search,
-but it imposes the requirement that the list be sorted.
+~~~~exercism/caution
+Binary search only works when a list has been sorted.
+~~~~
 
-In computer science, a binary search or half-interval search algorithm
-finds the position of a specified input value (the search "key") within
-an array sorted by key value.
+The algorithm looks like this:
 
-In each step, the algorithm compares the search key value with the key
-value of the middle element of the array.
+- 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.
+- If every element of the list has been eliminated then the item is not in the list.
+- Otherwise, repeat the process on the part of the list that has not been eliminated.
 
-If the keys match, then a matching element has been found and its index,
-or position, is returned.
+Here's an example:
 
-Otherwise, if the search key is less than the middle element's key, then
-the algorithm repeats its action on the sub-array to the left of the
-middle element or, if the search key is greater, on the sub-array to the
-right.
+Let's say we're looking for the number 23 in the following sorted list: `[4, 8, 12, 16, 23, 28, 32]`.
 
-If the remaining array to be searched is empty, then the key cannot be
-found in the array and a special "not found" indication is returned.
-
-A binary search halves the number of items to check with each iteration,
-so locating an item (or determining its absence) takes logarithmic time.
-A binary search is a dichotomic divide and conquer search algorithm.
+- We start by comparing 23 with the middle element, 16.
+- Since 23 is greater than 16, we can eliminate the left half of the list, leaving us with `[23, 28, 32]`.
+- We then compare 23 with the new middle element, 28.
+- Since 23 is less than 28, we can eliminate the right half of the list: `[23]`.
+- We've found our item.

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

@@ -0,0 +1,13 @@
+# Introduction
+
+You have stumbled upon a group of mathematicians who are also singer-songwriters.
+They have written a song for each of their favorite numbers, and, as you can imagine, they have a lot of favorite numbers (like [0][zero] or [73][seventy-three] or [6174][kaprekars-constant]).
+
+You are curious to hear the song for your favorite number, but with so many songs to wade through, finding the right song could take a while.
+Fortunately, they have organized their songs in a playlist sorted by the title — which is simply the number that the song is about.
+
+You realize that you can use a binary search algorithm to quickly find a song given the title.
+
+[zero]: https://en.wikipedia.org/wiki/0
+[seventy-three]: https://en.wikipedia.org/wiki/73_(number)
+[kaprekars-constant]: https://en.wikipedia.org/wiki/6174_(number)

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

@@ -8,7 +8,7 @@
     ],
     "test": [
       "tst/binary-search/binary-search.cut"
-    ], 
+    ],
     "example": [
       ".meta/proof.ci.cob"
     ],
@@ -19,5 +19,5 @@
   },
   "blurb": "Implement a binary search algorithm.",
   "source": "Wikipedia",
-  "source_url": "http://en.wikipedia.org/wiki/Binary_search_algorithm"
+  "source_url": "https://en.wikipedia.org/wiki/Binary_search_algorithm"
 }

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

@@ -1,10 +1,10 @@
-# Description
+# Instructions
 
 Convert a binary number, represented as a string (e.g. '101010'), to its decimal equivalent using first principles.
 
-Implement binary to decimal conversion. Given a binary input
-string, your program should produce a decimal output. The
-program should handle invalid inputs.
+Implement binary to decimal conversion.
+Given a binary input string, your program should produce a decimal output.
+The program should handle invalid inputs.
 
 ## Note
 
@@ -15,13 +15,12 @@ program should handle invalid inputs.
 
 Decimal is a base-10 system.
 
-A number 23 in base 10 notation can be understood
-as a linear combination of powers of 10:
+A number 23 in base 10 notation can be understood as a linear combination of powers of 10:
 
 - 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

@@ -1,51 +1,58 @@
-# Description
+# Instructions
 
-A circular buffer, cyclic buffer or ring buffer is a data structure that
-uses a single, fixed-size buffer as if it were connected end-to-end.
+A circular buffer, cyclic buffer or ring buffer is a data structure that uses a single, fixed-size buffer as if it were connected end-to-end.
 
-A circular buffer first starts empty and of some predefined length. For
-example, this is a 7-element buffer:
-<!-- prettier-ignore -->
-    [ ][ ][ ][ ][ ][ ][ ]
+A circular buffer first starts empty and of some predefined length.
+For example, this is a 7-element buffer:
 
-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
+[ ][ ][ ][ ][ ][ ][ ]
+```
 
-Then assume that two more elements are added — 2 & 3 — which get
-appended after the 1:
-<!-- prettier-ignore -->
-    [ ][ ][ ][1][2][3][ ]
+Assume that a 1 is written into the middle of the buffer (exact starting location does not matter in a circular buffer):
 
-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
+[ ][ ][ ][1][ ][ ][ ]
+```
+
+Then assume that two more elements are added — 2 & 3 — which get appended after the 1:
+
+```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:
+
+```text
+[ ][ ][ ][ ][ ][3][ ]
+```
 
 If the buffer has 7 elements then it is completely full:
-<!-- prettier-ignore -->
-    [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]
-
-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]
-
-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
+[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:
+
+```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:
+
+```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.
+
+```text
+[C][D][7][8][9][A][B]
+```

exercises/practice/circular-buffer/.meta/config.json

@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "blurb": "A circular buffer, cyclic buffer or ring buffer is a data structure that uses a single, fixed-size buffer as if it were connected end-to-end.",
+  "blurb": "A data structure that uses a single, fixed-size buffer as if it were connected end-to-end.",
   "source": "Wikipedia",
   "source_url": "https://en.wikipedia.org/wiki/Circular_buffer"
 }