Run configlet sync --docs on exercises` (#2334)

Author: IsaacG

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

@@ -4,5 +4,14 @@ Convert a phrase to its acronym.
 
 Techies love their TLA (Three Letter Acronyms)!
 
-Help generate some jargon by writing a program that converts a long name
-like Portable Network Graphics to its acronym (PNG).
+Help generate some jargon by writing a program that converts a long name like Portable Network Graphics to its acronym (PNG).
+
+Punctuation is handled as follows: hyphens are word separators (like whitespace); all other punctuation can be removed from the input.
+
+For example:
+
+| Input                     | Output |
+| ------------------------- | ------ |
+| As Soon As Possible       | ASAP   |
+| Liquid-crystal display    | LCD    |
+| Thank George It's Friday! | TGIF   |

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

@@ -1,73 +1,74 @@
 # Instructions
 
-Create an implementation of the affine cipher,
-an ancient encryption system created in the Middle East.
+Create an implementation of the affine cipher, an ancient encryption system created in the Middle East.
 
 The affine cipher is a type of monoalphabetic substitution cipher.
-Each character is mapped to its numeric equivalent, encrypted with
-a mathematical function and then converted to the letter relating to
-its new numeric value. Although all monoalphabetic ciphers are weak,
-the affine cypher is much stronger than the atbash cipher,
-because it has many more keys.
+Each character is mapped to its numeric equivalent, encrypted with a mathematical function and then converted to the letter relating to its new numeric value.
+Although all monoalphabetic ciphers are weak, the affine cipher is much stronger than the atbash cipher, because it has many more keys.
+
+[//]: # ' monoalphabetic as spelled by Merriam-Webster, compare to polyalphabetic '
+
+## Encryption
 
 The encryption function is:
 
-`E(x) = (ax + b) mod m`
+```text
+E(x) = (ai + b) mod m
+```
 
-- where `x` is the letter's index from 0 - length of alphabet - 1
-- `m` is the length of the alphabet. For the roman alphabet `m == 26`.
-- and `a` and `b` make the key
+Where:
 
-The decryption function is:
+- `i` is the letter's index from `0` to the length of the alphabet - 1
+- `m` is the length of the alphabet.
+  For the Roman alphabet `m` is `26`.
+- `a` and `b` are integers which make the encryption key
 
-`D(y) = a^-1(y - b) mod m`
+Values `a` and `m` must be _coprime_ (or, _relatively prime_) for automatic decryption to succeed, i.e., they have number `1` as their only common factor (more information can be found in the [Wikipedia article about coprime integers][coprime-integers]).
+In case `a` is not coprime to `m`, your program should indicate that this is an error.
+Otherwise it should encrypt or decrypt with the provided key.
 
-- where `y` is the numeric value of an encrypted letter, ie. `y = E(x)`
-- it is important to note that `a^-1` is the modular multiplicative inverse
-  of `a mod m`
-- the modular multiplicative inverse of `a` only exists if `a` and `m` are
-  coprime.
+For the purpose of this exercise, digits are valid input but they are not encrypted.
+Spaces and punctuation characters are excluded.
+Ciphertext is written out in groups of fixed length separated by space, the traditional group size being `5` letters.
+This is to make it harder to guess encrypted text based on word boundaries.
 
-To find the MMI of `a`:
+## Decryption
+
+The decryption function is:
 
-`an mod m = 1`
+```text
+D(y) = (a^-1)(y - b) mod m
+```
 
-- where `n` is the modular multiplicative inverse of `a mod m`
+Where:
 
-More information regarding how to find a Modular Multiplicative Inverse
-and what it means can be found [here.](https://en.wikipedia.org/wiki/Modular_multiplicative_inverse)
+- `y` is the numeric value of an encrypted letter, i.e., `y = E(x)`
+- it is important to note that `a^-1` is the modular multiplicative inverse (MMI) of `a mod m`
+- the modular multiplicative inverse only exists if `a` and `m` are coprime.
 
-Because automatic decryption fails if `a` is not coprime to `m` your
-program should return status 1 and `"Error: a and m must be coprime."`
-if they are not. Otherwise it should encode or decode with the
-provided key.
+The MMI of `a` is `x` such that the remainder after dividing `ax` by `m` is `1`:
 
-The Caesar (shift) cipher is a simple affine cipher where `a` is 1 and
-`b` as the magnitude results in a static displacement of the letters.
-This is much less secure than a full implementation of the affine cipher.
+```text
+ax mod m = 1
+```
 
-Ciphertext is written out in groups of fixed length, the traditional group
-size being 5 letters, and punctuation is excluded. This is to make it
-harder to guess things based on word boundaries.
+More information regarding how to find a Modular Multiplicative Inverse and what it means can be found in the [related Wikipedia article][mmi].
 
 ## General Examples
 
-- Encoding `test` gives `ybty` with the key a=5 b=7
-- Decoding `ybty` gives `test` with the key a=5 b=7
-- Decoding `ybty` gives `lqul` with the wrong key a=11 b=7
-- Decoding `kqlfd jzvgy tpaet icdhm rtwly kqlon ubstx`
-  - gives `thequickbrownfoxjumpsoverthelazydog` with the key a=19 b=13
-- Encoding `test` with the key a=18 b=13
-  - gives `Error: a and m must be coprime.`
-  - because a and m are not relatively prime
-
-## Examples of finding a Modular Multiplicative Inverse (MMI)
-
-- simple example:
-  - `9 mod 26 = 9`
-  - `9 * 3 mod 26 = 27 mod 26 = 1`
-  - `3` is the MMI of `9 mod 26`
-- a more complicated example:
-  - `15 mod 26 = 15`
-  - `15 * 7 mod 26 = 105 mod 26 = 1`
-  - `7` is the MMI of `15 mod 26`
+- Encrypting `"test"` gives `"ybty"` with the key `a = 5`, `b = 7`
+- Decrypting `"ybty"` gives `"test"` with the key `a = 5`, `b = 7`
+- Decrypting `"ybty"` gives `"lqul"` with the wrong key `a = 11`, `b = 7`
+- Decrypting `"kqlfd jzvgy tpaet icdhm rtwly kqlon ubstx"` gives `"thequickbrownfoxjumpsoverthelazydog"` with the key `a = 19`, `b = 13`
+- Encrypting `"test"` with the key `a = 18`, `b = 13` is an error because `18` and `26` are not coprime
+
+## Example of finding a Modular Multiplicative Inverse (MMI)
+
+Finding MMI for `a = 15`:
+
+- `(15 * x) mod 26 = 1`
+- `(15 * 7) mod 26 = 1`, ie. `105 mod 26 = 1`
+- `7` is the MMI of `15 mod 26`
+
+[mmi]: https://en.wikipedia.org/wiki/Modular_multiplicative_inverse
+[coprime-integers]: https://en.wikipedia.org/wiki/Coprime_integers

exercises/practice/all-your-base/.docs/instructions.md

@@ -2,31 +2,32 @@
 
 Convert a number, represented as a sequence of digits in one base, to any other base.
 
-Implement general base conversion. Given a number in base **a**,
-represented as a sequence of digits, convert it to base **b**.
+Implement general base conversion.
+Given a number in base **a**, represented as a sequence of digits, convert it to base **b**.
 
 ## Note
 
 - Try to implement the conversion yourself.
   Do not use something else to perform the conversion for you.
 
-## About [Positional Notation](https://en.wikipedia.org/wiki/Positional_notation)
+## About [Positional Notation][positional-notation]
 
-In positional notation, a number in base **b** can be understood as a linear
-combination of powers of **b**.
+In positional notation, a number in base **b** can be understood as a linear combination of powers of **b**.
 
 The number 42, _in base 10_, means:
 
-(4 _ 10^1) + (2 _ 10^0)
+`(4 * 10^1) + (2 * 10^0)`
 
 The number 101010, _in base 2_, means:
 
-(1 _ 2^5) + (0 _ 2^4) + (1 _ 2^3) + (0 _ 2^2) + (1 _ 2^1) + (0 _ 2^0)
+`(1 * 2^5) + (0 * 2^4) + (1 * 2^3) + (0 * 2^2) + (1 * 2^1) + (0 * 2^0)`
 
 The number 1120, _in base 3_, means:
 
-(1 _ 3^3) + (1 _ 3^2) + (2 _ 3^1) + (0 _ 3^0)
+`(1 * 3^3) + (1 * 3^2) + (2 * 3^1) + (0 * 3^0)`
 
 I think you got the idea!
 
 _Yes. Those three numbers above are exactly the same. Congratulations!_
+
+[positional-notation]: https://en.wikipedia.org/wiki/Positional_notation

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

@@ -2,9 +2,7 @@
 
 Given a person's allergy score, determine whether or not they're allergic to a given item, and their full list of allergies.
 
-An allergy test produces a single numeric score which contains the
-information about all the allergies the person has (that they were
-tested for).
+An allergy test produces a single numeric score which contains the information about all the allergies the person has (that they were tested for).
 
 The list of items (and their value) that were tested are:
 
@@ -24,7 +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.). 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.
+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/alphametics/.docs/instructions.md

@@ -2,8 +2,7 @@
 
 Write a function to solve alphametics puzzles.
 
-[Alphametics](https://en.wikipedia.org/wiki/Alphametics) is a puzzle where
-letters in words are replaced with numbers.
+[Alphametics][alphametics] is a puzzle where letters in words are replaced with numbers.
 
 For example `SEND + MORE = MONEY`:
 
@@ -23,10 +22,10 @@ Replacing these with valid numbers gives:
 1 0 6 5 2
 ```
 
-This is correct because every letter is replaced by a different number and the
-words, translated into numbers, then make a valid sum.
+This is correct because every letter is replaced by a different number and the words, translated into numbers, then make a valid sum.
 
-Each letter must represent a different digit, and the leading digit of
-a multi-digit number must not be zero.
+Each letter must represent a different digit, and the leading digit of a multi-digit number must not be zero.
 
 Write a function to solve alphametics puzzles.
+
+[alphametics]: https://en.wikipedia.org/wiki/Alphametics

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

@@ -1,6 +1,6 @@
 # Instructions
 
-An [Armstrong number](https://en.wikipedia.org/wiki/Narcissistic_number) is a number that is the sum of its own digits each raised to the power of the number of digits.
+An [Armstrong number][armstrong-number] is a number that is the sum of its own digits each raised to the power of the number of digits.
 
 For example:
 
@@ -10,3 +10,5 @@ For example:
 - 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.
+
+[armstrong-number]: https://en.wikipedia.org/wiki/Narcissistic_number

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

@@ -2,10 +2,8 @@
 
 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,16 +12,16 @@ Plain:  abcdefghijklmnopqrstuvwxyz
 Cipher: zyxwvutsrqponmlkjihgfedcba
 ```
 
-It is a very weak cipher because it only has one possible key, and it is
-a simple monoalphabetic 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, and punctuation is excluded. This is to make it harder to guess
-things based on word boundaries.
+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
 
 - Encoding `test` gives `gvhg`
+- Encoding `x123 yes` gives `c123b vh`
 - Decoding `gvhg` gives `test`
 - Decoding `gsvjf rxpyi ldmul cqfnk hlevi gsvoz abwlt` gives `thequickbrownfoxjumpsoverthelazydog`

exercises/practice/bank-account/.docs/instructions.md

@@ -1,27 +1,12 @@
 # Instructions
 
-Simulate a bank account supporting opening/closing, withdrawals, and deposits
-of money. Watch out for concurrent transactions!
+Simulate a bank account supporting opening/closing, withdrawals, and deposits of money.
+Watch out for concurrent transactions!
 
-A bank account can be accessed in multiple ways. Clients can make
-deposits and withdrawals using the internet, mobile phones, etc. Shops
-can charge against the account.
+A bank account can be accessed in multiple ways.
+Clients can make deposits and withdrawals using the internet, mobile phones, etc.
+Shops can charge against the account.
 
-Create an account that can be accessed from multiple threads/processes
-(terminology depends on your programming language).
+Create an account that can be accessed from multiple threads/processes (terminology depends on your programming language).
 
-It should be possible to close an account; operations against a closed
-account must fail.
-
-## Instructions
-
-Run the test file, and fix each of the errors in turn. When you get the
-first test to pass, go to the first pending or skipped test, and make
-that pass as well. When all of the tests are passing, feel free to
-submit.
-
-Remember that passing code is just the first step. The goal is to work
-towards a solution that is as readable and expressive as you can make
-it.
-
-Have fun!
+It should be possible to close an account; operations against a closed account must fail.

exercises/practice/beer-song/.docs/instructions.md

@@ -305,17 +305,3 @@ Take it down and pass it around, no more bottles of beer on the wall.
 No more bottles of beer on the wall, no more bottles of beer.
 Go to the store and buy some more, 99 bottles of beer on the wall.
 ```
-
-## For bonus points
-
-Did you get the tests passing and the code clean? If you want to, these
-are some additional things you could try:
-
-- Remove as much duplication as you possibly can.
-- Optimize for readability, even if it means introducing duplication.
-- If you've removed all the duplication, do you have a lot of
-  conditionals? Try replacing the conditionals with polymorphism, if it
-  applies in this language. How readable is it?
-
-Then please share your thoughts in a comment on the submission. Did this
-experiment make the code better? Worse? Did you learn anything from it?

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

@@ -2,29 +2,22 @@
 
 Insert and search for numbers in a binary tree.
 
-When we need to represent sorted data, an array does not make a good
-data structure.
-
-Say we have the array `[1, 3, 4, 5]`, and we add 2 to it so it becomes
-`[1, 3, 4, 5, 2]` now we must sort the entire array again! We can
-improve on this by realizing that we only need to make space for the new
-item `[1, nil, 3, 4, 5]`, and then adding the item in the space we
-added. But this still requires us to shift many elements down by one.
-
-Binary Search Trees, however, can operate on sorted data much more
-efficiently.
-
-A binary search tree consists of a series of connected nodes. Each node
-contains a piece of data (e.g. the number 3), a variable named `left`,
-and a variable named `right`. The `left` and `right` variables point at
-`nil`, or other nodes. Since these other nodes in turn have other nodes
-beneath them, we say that the left and right variables are pointing at
-subtrees. All data in the left subtree is less than or equal to the
-current node's data, and all data in the right subtree is greater than
-the current node's data.
-
-For example, if we had a node containing the data 4, and we added the
-data 2, our tree would look like this:
+When we need to represent sorted data, an array does not make a good data structure.
+
+Say we have the array `[1, 3, 4, 5]`, and we add 2 to it so it becomes `[1, 3, 4, 5, 2]`.
+Now we must sort the entire array again!
+We can improve on this by realizing that we only need to make space for the new item `[1, nil, 3, 4, 5]`, and then adding the item in the space we added.
+But this still requires us to shift many elements down by one.
+
+Binary Search Trees, however, can operate on sorted data much more efficiently.
+
+A binary search tree consists of a series of connected nodes.
+Each node contains a piece of data (e.g. the number 3), a variable named `left`, and a variable named `right`.
+The `left` and `right` variables point at `nil`, or other nodes.
+Since these other nodes in turn have other nodes beneath them, we say that the left and right variables are pointing at subtrees.
+All data in the left subtree is less than or equal to the current node's data, and all data in the right subtree is greater than the current node's data.
+
+For example, if we had a node containing the data 4, and we added the data 2, our tree would look like this:
 
       4
      /