Sync documentation and metadata with problem-specifications (#1783)

Manual interventions:

- The exercise clock had some Rust-specific stuff in `instructions.md`.
This was moved to `instructions.append.md`.
- Same with minesweeper.
- The exercise queen-attack had additions to `instructions.md` which are
not language specific. These were deleted. Upstreaming them will be
discussed in a separate channel. If the additions are eventually
upstreamed, they will find their way back into the Rust track.

[no important files changed]

exercises/practice/accumulate/.docs/instructions.md

@@ -1,9 +1,6 @@
 # Instructions
 
-Implement the `accumulate` operation, which, given a collection and an
-operation to perform on each element of the collection, returns a new
-collection containing the result of applying that operation to each element of
-the input collection.
+Implement the `accumulate` operation, which, given a collection and an operation to perform on each element of the collection, returns a new collection containing the result of applying that operation to each element of the input collection.
 
 Given the collection of numbers:
 
@@ -21,6 +18,5 @@ Check out the test suite to see the expected function signature.
 
 ## Restrictions
 
-Keep your hands off that collect/map/fmap/whatchamacallit functionality
-provided by your standard library!
+Keep your hands off that collect/map/fmap/whatchamacallit functionality provided by your standard library!
 Solve this one yourself using other basic tools instead.

exercises/practice/accumulate/.meta/config.json

@@ -32,7 +32,7 @@
   },
   "blurb": "Implement the `accumulate` operation, which, given a collection and an operation to perform on each element of the collection, returns a new collection containing the result of applying that operation to each element of the input collection.",
   "source": "Conversation with James Edward Gray II",
-  "source_url": "https://twitter.com/jeg2",
+  "source_url": "http://graysoftinc.com/",
   "custom": {
     "allowed-to-not-compile": "Stub doesn't compile because there is no type specified for _function and _closure arguments. This exercise teaches students about the use of function pointers and closures, therefore specifying the type of arguments for them would reduce learning."
   }

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:
+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:
+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:
+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!*
+_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,20 +2,18 @@
 
 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:
 
-* eggs (1)
-* peanuts (2)
-* shellfish (4)
-* strawberries (8)
-* tomatoes (16)
-* chocolate (32)
-* pollen (64)
-* cats (128)
+- eggs (1)
+- peanuts (2)
+- shellfish (4)
+- strawberries (8)
+- tomatoes (16)
+- chocolate (32)
+- pollen (64)
+- cats (128)
 
 So if Tom is allergic to peanuts and chocolate, he gets a score of 34.
 
@@ -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/allergies/.meta/config.json

@@ -35,6 +35,6 @@
     ]
   },
   "blurb": "Given a person's allergy score, determine whether or not they're allergic to a given item, and their full list of allergies.",
-  "source": "Jumpstart Lab Warm-up",
-  "source_url": "http://jumpstartlab.com"
+  "source": "Exercise by the JumpstartLab team for students at The Turing School of Software and Design.",
+  "source_url": "https://turing.edu"
 }

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/anagram/.docs/instructions.md

@@ -1,8 +1,13 @@
 # Instructions
 
-An anagram is a rearrangement of letters to form a new word.
-Given a word and a list of candidates, select the sublist of anagrams of the given word.
+An anagram is a rearrangement of letters to form a new word: for example `"owns"` is an anagram of `"snow"`.
+A word is not its own anagram: for example, `"stop"` is not an anagram of `"stop"`.
 
-Given `"listen"` and a list of candidates like `"enlists" "google"
-"inlets" "banana"` the program should return a list containing
-`"inlets"`.
+Given a target word and a set of candidate words, this exercise requests the anagram set: the subset of the candidates that are anagrams of the target.
+
+The target and candidates are words of one or more ASCII alphabetic characters (`A`-`Z` and `a`-`z`).
+Lowercase and uppercase characters are equivalent: for example, `"PoTS"` is an anagram of `"sTOp"`, but `StoP` is not an anagram of `sTOp`.
+The anagram set is the subset of the candidate set that are anagrams of the target (in any order).
+Words in the anagram set should have the same letter case as in the candidate set.
+
+Given the target `"stone"` and candidates `"stone"`, `"tones"`, `"banana"`, `"tons"`, `"notes"`, `"Seton"`, the anagram set is `"tones"`, `"notes"`, `"Seton"`.

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

@@ -1,12 +1,14 @@
 # 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:
 
 - 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.
+
+[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/atbash-cipher/.meta/config.json

@@ -35,5 +35,5 @@
   },
   "blurb": "Create an implementation of the atbash cipher, an ancient encryption system created in the Middle East.",
   "source": "Wikipedia",
-  "source_url": "http://en.wikipedia.org/wiki/Atbash"
+  "source_url": "https://en.wikipedia.org/wiki/Atbash"
 }

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/beer-song/.meta/config.json

@@ -40,5 +40,5 @@
   },
   "blurb": "Produce the lyrics to that beloved classic, that field-trip favorite: 99 Bottles of Beer on the Wall.",
   "source": "Learn to Program by Chris Pine",
-  "source_url": "http://pine.fm/LearnToProgram/?Chapter=06"
+  "source_url": "https://pine.fm/LearnToProgram/?Chapter=06"
 }

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-search/.meta/config.json

@@ -30,5 +30,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/bob/.meta/config.json

@@ -46,5 +46,5 @@
   },
   "blurb": "Bob is a lackadaisical teenager. In conversation, his responses are very limited.",
   "source": "Inspired by the 'Deaf Grandma' exercise in Chris Pine's Learn to Program tutorial.",
-  "source_url": "http://pine.fm/LearnToProgram/?Chapter=06"
+  "source_url": "https://pine.fm/LearnToProgram/?Chapter=06"
 }

exercises/practice/bowling/.docs/instructions.md

@@ -2,35 +2,30 @@
 
 Score a bowling game.
 
-Bowling is a game where players roll a heavy ball to knock down pins
-arranged in a triangle. Write code to keep track of the score
-of a game of bowling.
+Bowling is a game where players roll a heavy ball to knock down pins arranged in a triangle.
+Write code to keep track of the score of a game of bowling.
 
 ## Scoring Bowling
 
-The game consists of 10 frames. A frame is composed of one or two ball
-throws with 10 pins standing at frame initialization. There are three
-cases for the tabulation of a frame.
+The game consists of 10 frames.
+A frame is composed of one or two ball throws with 10 pins standing at frame initialization.
+There are three cases for the tabulation of a frame.
 
-* An open frame is where a score of less than 10 is recorded for the
-  frame. In this case the score for the frame is the number of pins
-  knocked down.
+- An open frame is where a score of less than 10 is recorded for the frame.
+  In this case the score for the frame is the number of pins knocked down.
 
-* A spare is where all ten pins are knocked down by the second
-  throw. The total value of a spare is 10 plus the number of pins
-  knocked down in their next throw.
+- A spare is where all ten pins are knocked down by the second throw.
+  The total value of a spare is 10 plus the number of pins knocked down in their next throw.
 
-* A strike is where all ten pins are knocked down by the first
-  throw. The total value of a strike is 10 plus the number of pins
-  knocked down in the next two throws. If a strike is immediately
-  followed by a second strike, then the value of the first strike
-  cannot be determined until the ball is thrown one more time.
+- A strike is where all ten pins are knocked down by the first throw.
+  The total value of a strike is 10 plus the number of pins knocked down in the next two throws.
+  If a strike is immediately followed by a second strike, then the value of the first strike cannot be determined until the ball is thrown one more time.
 
 Here is a three frame example:
 
-| Frame 1         | Frame 2       | Frame 3                |
-| :-------------: |:-------------:| :---------------------:|
-| X (strike)      | 5/ (spare)    | 9 0 (open frame)       |
+|  Frame 1   |  Frame 2   |     Frame 3      |
+| :--------: | :--------: | :--------------: |
+| X (strike) | 5/ (spare) | 9 0 (open frame) |
 
 Frame 1 is (10 + 5 + 5) = 20
 
@@ -40,22 +35,22 @@ Frame 3 is (9 + 0) = 9
 
 This means the current running total is 48.
 
-The tenth frame in the game is a special case. If someone throws a
-strike or a spare then they get a fill ball. Fill balls exist to
-calculate the total of the 10th frame. Scoring a strike or spare on
-the fill ball does not give the player more fill balls. The total
-value of the 10th frame is the total number of pins knocked down.
+The tenth frame in the game is a special case.
+If someone throws a spare or a strike then they get one or two fill balls respectively.
+Fill balls exist to calculate the total of the 10th frame.
+Scoring a strike or spare on the fill ball does not give the player more fill balls.
+The total value of the 10th frame is the total number of pins knocked down.
 
 For a tenth frame of X1/ (strike and a spare), the total value is 20.
 
 For a tenth frame of XXX (three strikes), the total value is 30.
 
 ## Requirements
 
-Write code to keep track of the score of a game of bowling. It should
-support two operations:
+Write code to keep track of the score of a game of bowling.
+It should support two operations:
 
-* `roll(pins : int)` is called each time the player rolls a ball.  The
-  argument is the number of pins knocked down.
-* `score() : int` is called only at the very end of the game.  It
-  returns the total score for that game.
+- `roll(pins : int)` is called each time the player rolls a ball.
+  The argument is the number of pins knocked down.
+- `score() : int` is called only at the very end of the game.
+  It returns the total score for that game.

exercises/practice/bowling/.meta/config.json

@@ -33,5 +33,5 @@
   },
   "blurb": "Score a bowling game.",
   "source": "The Bowling Game Kata from UncleBob",
-  "source_url": "http://butunclebob.com/ArticleS.UncleBob.TheBowlingGameKata"
+  "source_url": "https://web.archive.org/web/20221001111000/http://butunclebob.com/ArticleS.UncleBob.TheBowlingGameKata"
 }