Regenerate README files based on current problem specification descriptions

exercises/affine-cipher/README.md

@@ -2,43 +2,43 @@
 
 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.
- 
+
 the encryption function is:
- 
+
   `E(x) = (ax + 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
- 
+
 the decryption function is:
- 
+
   `D(y) = a^-1(y - b) mod m`
   -  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.
- 
+
 To find the MMI of `a`:
 
   `an mod m = 1`
   -  where `n` is the modular multiplicative inverse of `a mod m`
 
 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) 
+and what it means can be found [here.](https://en.wikipedia.org/wiki/Modular_multiplicative_inverse)
 
 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 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.
@@ -48,7 +48,7 @@ size being 5 letters, and punctuation is excluded. This is to make it
 harder to guess things based on word boundaries.
 
 ## 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

exercises/darts/.meta/hints.md

@@ -0,0 +1,4 @@
+
+This particular exercise, since it deals with floating point arithmetic, is
+natural to rely on external tools (see below). As an extra challenging
+challenge, find a way to implement this with plain bash.

exercises/darts/README.md

@@ -16,7 +16,11 @@ The outer circle has a radius of 10 units (This is equivalent to the total radiu
 
 Write a function that given a point in the target (defined by its `real` cartesian coordinates `x` and `y`), returns the correct amount earned by a dart landing in that point.
 
-This particular exercise, since it deals with floating point arithmetic, is natural to rely on external tools (see below). As an extra challenging challenge, find a way to implement this with plain bash.
+This particular exercise, since it deals with floating point arithmetic, is
+natural to rely on external tools (see below). As an extra challenging
+challenge, find a way to implement this with plain bash.
+
+
 
 Run the tests with:
 

exercises/isbn-verifier/README.md

@@ -41,6 +41,7 @@ Now, it's even trickier since the check digit of an ISBN-10 may be 'X' (represen
 
 * Generate valid ISBN, maybe even from a given starting ISBN.
 
+
 Run the tests with:
 
 ```bash

exercises/luhn/README.md

@@ -19,27 +19,27 @@ are disallowed.
 ## Example 1: valid credit card number
 
 ```text
-4539 1488 0343 6467
+4539 3195 0343 6467
 ```
 
 The first step of the Luhn algorithm is to double every second digit,
 starting from the right. We will be doubling
 
 ```text
-4_3_ 1_8_ 0_4_ 6_6_
+4_3_ 3_9_ 0_4_ 6_6_
 ```
 
 If doubling the number results in a number greater than 9 then subtract 9
 from the product. The results of our doubling:
 
 ```text
-8569 2478 0383 3437
+8569 6195 0383 3437
 ```
 
 Then sum all of the digits:
 
 ```text
-8+5+6+9+2+4+7+8+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!

exercises/raindrops/README.md

@@ -1,21 +1,19 @@
 # Raindrops
 
-Convert a number to a string, the contents of which depend on the number's factors.
+Your task is to convert a number into a string that contains raindrop sounds corresponding to certain potential factors. A factor is a number that evenly divides into another number, leaving no remainder. The simplest way to test if a one number is a factor of another is to use the [modulo operation](https://en.wikipedia.org/wiki/Modulo_operation).
 
-- If the number has 3 as a factor, output 'Pling'.
-- If the number has 5 as a factor, output 'Plang'.
-- If the number has 7 as a factor, output 'Plong'.
-- If the number does not have 3, 5, or 7 as a factor,
-  just pass the number's digits straight through.
+The rules of `raindrops` are that if a given number:
+
+- has 3 as a factor, add 'Pling' to the result.
+- has 5 as a factor, add 'Plang' to the result.
+- has 7 as a factor, add 'Plong' to the result.
+- _does not_ have any of 3, 5, or 7 as a factor, the result should be the digits of the number.
 
 ## Examples
 
-- 28's factors are 1, 2, 4, **7**, 14, 28.
-  - In raindrop-speak, this would be a simple "Plong".
-- 30's factors are 1, 2, **3**, **5**, 6, 10, 15, 30.
-  - In raindrop-speak, this would be a "PlingPlang".
-- 34 has four factors: 1, 2, 17, and 34.
-  - In raindrop-speak, this would be "34".
+- 28 has 7 as a factor, but not 3 or 5, so the result would be "Plong".
+- 30 has both 3 and 5 as factors, but not 7, so the result would be "PlingPlang".
+- 34 is not factored by 3, 5, or 7, so the result would be "34".
 
 
 Run the tests with:
@@ -36,7 +34,7 @@ BATS_RUN_SKIPPED=true bats raindrops_test.sh
 
 ## Source
 
-A variation on a famous interview question intended to weed out potential candidates. [http://jumpstartlab.com](http://jumpstartlab.com)
+A variation on FizzBuzz, a famous technical interview question that is intended to weed out potential candidates. That question is itself derived from Fizz Buzz, a popular children's game for teaching division. [https://en.wikipedia.org/wiki/Fizz_buzz](https://en.wikipedia.org/wiki/Fizz_buzz)
 
 
 ## External utilities

exercises/resistor-color-duo/README.md

@@ -4,9 +4,10 @@ If you want to build something using a Raspberry Pi, you'll probably use _resist
 
 * Each resistor has a resistance value.
 * Resistors are small - so small in fact that if you printed the resistance value on them, it would be hard to read.
-To get around this problem, manufacturers print color-coded bands onto the resistors to denote their resistance values. Each band acts as a digit of a number. For example, if they printed a brown band (value 1) followed by a green band (value 5), it would translate to the number 15.
+To get around this problem, manufacturers print color-coded bands onto the resistors to denote their resistance values. Each band has a position and a numeric value. For example, if they printed a brown band (value 1) followed by a green band (value 5), it would translate to the number 15.
+
+In this exercise you are going to create a helpful program so that you don't have to remember the values of the bands. The program will take color names as input and output a two digit number, even if the input is more than two colors!
 
-In this exercise, you are going to create a helpful program so that you don't have to remember the values of the bands. The program will take two colors as input, and output the correct number.
 
 The band colors are encoded as follows:
 
@@ -21,6 +22,11 @@ The band colors are encoded as follows:
 - Grey: 8
 - White: 9
 
+From the example above:
+brown-green should return 15
+brown-green-violet should return 15 too, ignoring the third color.
+
+
 
 Run the tests with:
 

exercises/scrabble-score/README.md

@@ -1,6 +1,6 @@
 # Scrabble Score
 
-Given a word, compute the scrabble score for that word.
+Given a word, compute the Scrabble score for that word.
 
 ## Letter Values
 

exercises/space-age/README.md

@@ -2,9 +2,9 @@
 
 Given an age in seconds, calculate how old someone would be on:
 
-   - Earth: orbital period 365.25 Earth days, or 31557600 seconds
    - Mercury: orbital period 0.2408467 Earth years
    - Venus: orbital period 0.61519726 Earth years
+   - Earth: orbital period 1.0 Earth years, 365.25 Earth days, or 31557600 seconds
    - Mars: orbital period 1.8808158 Earth years
    - Jupiter: orbital period 11.862615 Earth years
    - Saturn: orbital period 29.447498 Earth years

exercises/two-bucket/README.md

@@ -23,9 +23,9 @@ Example:
 Bucket one can hold up to 7 liters, and bucket two can hold up to 11 liters. Let's say bucket one, at a given step, is holding 7 liters, and bucket two is holding 8 liters (7,8). If you empty bucket one and make no change to bucket two, leaving you with 0 liters and 8 liters respectively (0,8), that counts as one "move". Instead, if you had poured from bucket one into bucket two until bucket two was full, leaving you with 4 liters in bucket one and 11 liters in bucket two (4,11), that would count as only one "move" as well.
 
 To conclude, the only valid moves are:
-- pouring from one bucket to another
-- emptying one bucket and doing nothing to the other
-- filling one bucket and doing nothing to the other
+- pouring from either bucket to another
+- emptying either bucket and doing nothing to the other
+- filling either bucket and doing nothing to the other
 
 Written with <3 at [Fullstack Academy](http://www.fullstackacademy.com/) by Lindsay Levine.
 

exercises/two-fer/README.md

@@ -5,10 +5,10 @@
 Given a name, return a string with the message:
 
 ```text
-One for X, one for me.
+One for name, one for me.
 ```
 
-Where X is the given name.
+Where "name" is the given name.
 
 However, if the name is missing, return the string:
 
@@ -18,9 +18,9 @@ One for you, one for me.
 
 Here are some examples:
 
-|Name    |String to return 
+|Name    |String to return
 |:-------|:------------------
-|Alice   |One for Alice, one for me. 
+|Alice   |One for Alice, one for me.
 |Bob     |One for Bob, one for me.
 |        |One for you, one for me.
 |Zaphod  |One for Zaphod, one for me.

exercises/variable-length-quantity/README.md

@@ -38,21 +38,41 @@ Run the tests with:
 bats variable_length_quantity_test.sh
 ```
 
-After the first test(s) pass, continue by commenting out or removing the `skip` annotations prepending other tests.
+After the first test(s) pass, continue by commenting out or removing the
+`[[ $BATS_RUN_SKIPPED == true ]] || skip` 
+annotations prepending other tests.
+
+To run all tests, including the ones with `skip` annotations, run:
+
+```bash
+BATS_RUN_SKIPPED=true bats variable_length_quantity_test.sh
+```
 
 ## Source
 
 A poor Splice developer having to implement MIDI encoding/decoding. [https://splice.com](https://splice.com)
 
 
 ## External utilities
-`Bash` is a language to write scripts that works closely with various system utilities,
-like [`sed`](https://www.gnu.org/software/sed/), [`awk`](https://www.gnu.org/software/gawk/), [`date`](https://www.gnu.org/software/coreutils/manual/html_node/date-invocation.html) and even other programming languages, like [`Python`](https://www.python.org/).
-This track does not restrict the usage of these utilities, and as long as your solution is portable
-between systems and does not require installing third party applications, feel free to use them to solve the exercise.
+`Bash` is a language to write "scripts" -- programs that can call
+external tools, such as
+[`sed`](https://www.gnu.org/software/sed/),
+[`awk`](https://www.gnu.org/software/gawk/),
+[`date`](https://www.gnu.org/software/coreutils/manual/html_node/date-invocation.html)
+and even programs written in other programming languages, 
+like [`Python`](https://www.python.org/).
+This track does not restrict the usage of these utilities, and as long
+as your solution is portable between systems and does not require
+installation of third party applications, feel free to use them to solve
+the exercise.
 
-For an extra challenge, if you would like to have a better understanding of the language,
-try to re-implement the solution in pure `Bash`, without using any external tools.
+For an extra challenge, if you would like to have a better understanding
+of the language, try to re-implement the solution in pure `Bash`,
+without using any external tools. Note that there are some types of
+problems that bash cannot solve, such as performing floating point
+arithmetic and manipulating dates: for those, you must call out to an
+external tool.
 
 ## Submitting Incomplete Solutions
-It's possible to submit an incomplete solution so you can see how others have completed the exercise.
+It's possible to submit an incomplete solution so you can see how others
+have completed the exercise.

exercises/word-count/README.md

@@ -1,14 +1,33 @@
 # Word Count
 
-Given a phrase, count the occurrences of each word in that phrase.
+Given a phrase, count the occurrences of each _word_ in that phrase.
 
-For example for the input `"olly olly in come free"`
+For the purposes of this exercise you can expect that a _word_ will always be one of:
+
+1. A _number_ composed of one or more ASCII digits (ie "0" or "1234") OR
+2. A _simple word_ composed of one or more ASCII letters (ie "a" or "they") OR
+3. A _contraction_ of two _simple words_ joined by a single apostrophe (ie "it's" or "they're")
+
+When counting words you can assume the following rules:
+
+1. The count is _case insensitive_ (ie "You", "you", and "YOU" are 3 uses of the same word)
+2. The count is _unordered_; the tests will ignore how words and counts are ordered
+3. Other than the apostrophe in a _contraction_ all forms of _punctuation_ are ignored
+4. The words can be separated by _any_ form of whitespace (ie "\t", "\n", " ")
+
+For example, for the phrase `"That's the password: 'PASSWORD 123'!", cried the Special Agent.\nSo I fled.` the count would be:
 
 ```text
-olly: 2
-in: 1
-come: 1
-free: 1
+that's: 1
+the: 2
+password: 2
+123: 1
+cried: 1
+special: 1
+agent: 1
+so: 1
+i: 1
+fled: 1
 ```