Sync docs and metadata

Author: IsaacG

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

@@ -20,7 +20,7 @@ Where:
 
 - `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`.
+  For the Latin alphabet `m` is `26`.
 - `a` and `b` are integers which make up the encryption key.
 
 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]).

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

@@ -58,7 +58,7 @@ The position information encoding is calculated as follows:
 
 ### Decimal number on the display
 
-16
+8
 
 ### Actual eggs in the coop
 

exercises/practice/luhn/.docs/instructions.md

@@ -1,6 +1,6 @@
 # Instructions
 
-Determine whether a credit card number is valid according to the [Luhn formula][luhn].
+Determine whether a number is valid according to the [Luhn formula][luhn].
 
 The number will be provided as a string.
 
@@ -10,54 +10,59 @@ Strings of length 1 or less are not valid.
 Spaces are allowed in the input, but they should be stripped before checking.
 All other non-digit characters are disallowed.
 
-### Example 1: valid credit card number
+## Examples
 
-```text
-4539 3195 0343 6467
-```
+### Valid credit card number
 
-The first step of the Luhn algorithm is to double every second digit, starting from the right.
-We will be doubling
+The number to be checked is `4539 3195 0343 6467`.
+
+The first step of the Luhn algorithm is to start at the end of the number and double every second digit, beginning with the second digit from the right and moving left.
 
 ```text
 4539 3195 0343 6467
 ↑ ↑  ↑ ↑  ↑ ↑  ↑ ↑  (double these)
 ```
 
-If doubling the number results in a number greater than 9 then subtract 9 from the product.
-The results of our doubling:
+If the result of doubling a digit is greater than 9, we subtract 9 from that result.
+We end up with:
 
 ```text
 8569 6195 0383 3437
 ```
 
-Then sum all of the digits:
+Finally, we sum all digits.
+If the sum is evenly divisible by 10, the original number is valid.
 
 ```text
-8+5+6+9+6+1+9+5+0+3+8+3+3+4+3+7 = 80
+8 + 5 + 6 + 9 + 6 + 1 + 9 + 5 + 0 + 3 + 8 + 3 + 3 + 4 + 3 + 7 = 80
 ```
 
-If the sum is evenly divisible by 10, then the number is valid.
-This number is valid!
+80 is evenly divisible by 10, so number `4539 3195 0343 6467` is valid!
+
+### Invalid Canadian SIN
+
+The number to be checked is `066 123 468`.
 
-### Example 2: invalid credit card number
+We start at the end of the number and double every second digit, beginning with the second digit from the right and moving left.
 
 ```text
-8273 1232 7352 0569
+066 123 478
+ ↑  ↑ ↑  ↑  (double these)
 ```
 
-Double the second digits, starting from the right
+If the result of doubling a digit is greater than 9, we subtract 9 from that result.
+We end up with:
 
 ```text
-7253 2262 5312 0539
+036 226 458
 ```
 
-Sum the digits
+We sum the digits:
 
 ```text
-7+2+5+3+2+2+6+2+5+3+1+2+0+5+3+9 = 57
+0 + 3 + 6 + 2 + 2 + 6 + 4 + 5 + 8 = 36
 ```
 
-57 is not evenly divisible by 10, so this number is not valid.
+36 is not evenly divisible by 10, so number `066 123 478` is not valid!
 
 [luhn]: https://en.wikipedia.org/wiki/Luhn_algorithm

exercises/practice/luhn/.docs/introduction.md

@@ -2,10 +2,10 @@
 
 At the Global Verification Authority, you've just been entrusted with a critical assignment.
 Across the city, from online purchases to secure logins, countless operations rely on the accuracy of numerical identifiers like credit card numbers, bank account numbers, transaction codes, and tracking IDs.
-The Luhn algorithm is a simple checksum formula used to ensure these numbers are valid and error-free.
+The Luhn algorithm is a simple checksum formula used to help identify mistyped numbers.
 
 A batch of identifiers has just arrived on your desk.
 All of them must pass the Luhn test to ensure they're legitimate.
-If any fail, they'll be flagged as invalid, preventing errors or fraud, such as incorrect transactions or unauthorized access.
+If any fail, they'll be flagged as invalid, preventing mistakes such as incorrect transactions or failed account verifications.
 
 Can you ensure this is done right? The integrity of many services depends on you.

exercises/practice/meetup/.docs/instructions.md

@@ -2,7 +2,7 @@
 
 Your task is to find the exact date of a meetup, given a month, year, weekday and week.
 
-There are five week values to consider: `first`, `second`, `third`, `fourth`, `last`, `teenth`.
+There are six week values to consider: `first`, `second`, `third`, `fourth`, `last`, `teenth`.
 
 For example, you might be asked to find the date for the meetup on the first Monday in January 2018 (January 1, 2018).
 

exercises/practice/phone-number/.docs/instructions.md

@@ -1,6 +1,6 @@
 # Instructions
 
-Clean up user-entered phone numbers so that they can be sent SMS messages.
+Clean up phone numbers so that they can be sent SMS messages.
 
 The **North American Numbering Plan (NANP)** is a telephone numbering system used by many countries in North America like the United States, Canada or Bermuda.
 All NANP-countries share the same international country code: `1`.

exercises/practice/sieve/.docs/instructions.md

@@ -6,37 +6,96 @@ A prime number is a number larger than 1 that is only divisible by 1 and itself.
 For example, 2, 3, 5, 7, 11, and 13 are prime numbers.
 By contrast, 6 is _not_ a prime number as it not only divisible by 1 and itself, but also by 2 and 3.
 
-To use the Sieve of Eratosthenes, you first create a list of all the numbers between 2 and your given number.
-Then you repeat the following steps:
+To use the Sieve of Eratosthenes, first, write out all the numbers from 2 up to and including your given number.
+Then, follow these steps:
 
-1. Find the next unmarked number in your list (skipping over marked numbers).
+1. Find the next unmarked number (skipping over marked numbers).
    This is a prime number.
 2. Mark all the multiples of that prime number as **not** prime.
 
-You keep repeating these steps until you've gone through every number in your list.
+Repeat the steps until you've gone through every number.
 At the end, all the unmarked numbers are prime.
 
 ~~~~exercism/note
-The tests don't check that you've implemented the algorithm, only that you've come up with the correct list of primes.
-To check you are implementing the Sieve correctly, a good first test is to check that you do not use division or remainder operations.
+The Sieve of Eratosthenes marks off multiples of each prime using addition (repeatedly adding the prime) or multiplication (directly computing its multiples), rather than checking each number for divisibility.
+
+The tests don't check that you've implemented the algorithm, only that you've come up with the correct primes.
 ~~~~
 
 ## Example
 
 Let's say you're finding the primes less than or equal to 10.
 
-- List out 2, 3, 4, 5, 6, 7, 8, 9, 10, leaving them all unmarked.
+- Write out 2, 3, 4, 5, 6, 7, 8, 9, 10, leaving them all unmarked.
+
+  ```text
+  2 3 4 5 6 7 8 9 10
+  ```
+
 - 2 is unmarked and is therefore a prime.
   Mark 4, 6, 8 and 10 as "not prime".
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] 9 [10]
+  ↑
+  ```
+
 - 3 is unmarked and is therefore a prime.
   Mark 6 and 9 as not prime _(marking 6 is optional - as it's already been marked)_.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+    ↑
+  ```
+
 - 4 is marked as "not prime", so we skip over it.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+       ↑
+  ```
+
 - 5 is unmarked and is therefore a prime.
   Mark 10 as not prime _(optional - as it's already been marked)_.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+          ↑
+  ```
+
 - 6 is marked as "not prime", so we skip over it.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+             ↑
+  ```
+
 - 7 is unmarked and is therefore a prime.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+                ↑
+  ```
+
 - 8 is marked as "not prime", so we skip over it.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+                   ↑
+  ```
+
 - 9 is marked as "not prime", so we skip over it.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+                       ↑
+  ```
+
 - 10 is marked as "not prime", so we stop as there are no more numbers to check.
 
-You've examined all numbers and found 2, 3, 5, and 7 are still unmarked, which means they're the primes less than or equal to 10.
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+                           ↑
+  ```
+
+You've examined all the numbers and found that 2, 3, 5, and 7 are still unmarked, meaning they're the primes less than or equal to 10.

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

@@ -1,66 +1,40 @@
 # Instructions
 
-Implement a simple shift cipher like Caesar and a more secure substitution cipher.
+Create an implementation of the [Vigenère cipher][wiki].
+The Vigenère cipher is a simple substitution cipher.
 
-## Step 1
+## Cipher terminology
 
-"If he had anything confidential to say, he wrote it in cipher, that is, by so changing the order of the letters of the alphabet, that not a word could be made out.
-If anyone wishes to decipher these, and get at their meaning, he must substitute the fourth letter of the alphabet, namely D, for A, and so with the others."
-—Suetonius, Life of Julius Caesar
+A cipher is an algorithm used to encrypt, or encode, a string.
+The unencrypted string is called the _plaintext_ and the encrypted string is called the _ciphertext_.
+Converting plaintext to ciphertext is called _encoding_ while the reverse is called _decoding_.
 
-Ciphers are very straight-forward algorithms that allow us to render text less readable while still allowing easy deciphering.
-They are vulnerable to many forms of cryptanalysis, but Caesar was lucky that his enemies were not cryptanalysts.
+In a _substitution cipher_, each plaintext letter is replaced with a ciphertext letter which is computed with the help of a _key_.
+(Note, it is possible for replacement letter to be the same as the original letter.)
 
-The Caesar Cipher was used for some messages from Julius Caesar that were sent afield.
-Now Caesar knew that the cipher wasn't very good, but he had one ally in that respect: almost nobody could read well.
-So even being a couple letters off was sufficient so that people couldn't recognize the few words that they did know.
+## Encoding details
 
-Your task is to create a simple shift cipher like the Caesar Cipher.
-This image is a great example of the Caesar Cipher:
+In this cipher, the key is a series of lowercase letters, such as `"abcd"`.
+Each letter of the plaintext is _shifted_ or _rotated_ by a distance based on a corresponding letter in the key.
+An `"a"` in the key means a shift of 0 (that is, no shift).
+A `"b"` in the key means a shift of 1.
+A `"c"` in the key means a shift of 2, and so on.
 
-![Caesar Cipher][img-caesar-cipher]
+The first letter of the plaintext uses the first letter of the key, the second letter of the plaintext uses the second letter of the key and so on.
+If you run out of letters in the key before you run out of letters in the plaintext, start over from the start of the key again.
 
-For example:
+If the key only contains one letter, such as `"dddddd"`, then all letters of the plaintext are shifted by the same amount (three in this example), which would make this the same as a rotational cipher or shift cipher (sometimes called a Caesar cipher).
+For example, the plaintext `"iamapandabear"` would become `"ldpdsdqgdehdu"`.
 
-Giving "iamapandabear" as input to the encode function returns the cipher "ldpdsdqgdehdu".
-Obscure enough to keep our message secret in transit.
+If the key only contains the letter `"a"` (one or more times), the shift distance is zero and the ciphertext is the same as the plaintext.
 
-When "ldpdsdqgdehdu" is put into the decode function it would return the original "iamapandabear" letting your friend read your original message.
+Usually the key is more complicated than that, though!
+If the key is `"abcd"` then letters of the plaintext would be shifted by a distance of 0, 1, 2, and 3.
+If the plaintext is `"hello"`, we need 5 shifts so the key would wrap around, giving shift distances of 0, 1, 2, 3, and 0.
+Applying those shifts to the letters of `"hello"` we get `"hfnoo"`.
 
-## Step 2
+## Random keys
 
-Shift ciphers quickly cease to be useful when the opposition commander figures them out.
-So instead, let's try using a substitution cipher.
-Try amending the code to allow us to specify a key and use that for the shift distance.
+If no key is provided, generate a key which consists of at least 100 random lowercase letters from the Latin alphabet.
 
-Here's an example:
-
-Given the key "aaaaaaaaaaaaaaaaaa", encoding the string "iamapandabear"
-would return the original "iamapandabear".
-
-Given the key "ddddddddddddddddd", encoding our string "iamapandabear"
-would return the obscured "ldpdsdqgdehdu"
-
-In the example above, we've set a = 0 for the key value.
-So when the plaintext is added to the key, we end up with the same message coming out.
-So "aaaa" is not an ideal key.
-But if we set the key to "dddd", we would get the same thing as the Caesar Cipher.
-
-## Step 3
-
-The weakest link in any cipher is the human being.
-Let's make your substitution cipher a little more fault tolerant by providing a source of randomness and ensuring that the key contains only lowercase letters.
-
-If someone doesn't submit a key at all, generate a truly random key of at least 100 lowercase characters in length.
-
-## Extensions
-
-Shift ciphers work by making the text slightly odd, but are vulnerable to frequency analysis.
-Substitution ciphers help that, but are still very vulnerable when the key is short or if spaces are preserved.
-Later on you'll see one solution to this problem in the exercise "crypto-square".
-
-If you want to go farther in this field, the questions begin to be about how we can exchange keys in a secure way.
-Take a look at [Diffie-Hellman on Wikipedia][dh] for one of the first implementations of this scheme.
-
-[img-caesar-cipher]: https://upload.wikimedia.org/wikipedia/commons/thumb/4/4a/Caesar_cipher_left_shift_of_3.svg/320px-Caesar_cipher_left_shift_of_3.svg.png
-[dh]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange
+[wiki]: https://en.wikipedia.org/wiki/Vigen%C3%A8re_cipher

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

@@ -17,7 +17,7 @@
       ".meta/example.sh"
     ]
   },
-  "blurb": "Implement a simple shift cipher like Caesar and a more secure substitution cipher.",
+  "blurb": "Implement the Vigenère cipher, a simple substitution cipher.",
   "source": "Substitution Cipher at Wikipedia",
   "source_url": "https://en.wikipedia.org/wiki/Substitution_cipher"
 }