Synced instructions and introduction files from problem specs. (#3423)

Author: BethanyG

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

@@ -2,9 +2,9 @@
 
 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,8 +15,7 @@ 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

exercises/practice/book-store/.docs/instructions.md

@@ -12,9 +12,9 @@ If you buy 4 different books, you get a 20% discount.
 
 If you buy all 5, you get a 25% discount.
 
-Note: that if you buy four books, of which 3 are different titles, you get a 10% discount on the 3 that form part of a set, but the fourth book still costs $8.
+Note that if you buy four books, of which 3 are different titles, you get a 10% discount on the 3 that form part of a set, but the fourth book still costs $8.
 
-Your mission is to write a piece of code to calculate the price of any conceivable shopping basket (containing only books of the same series), giving as big a discount as possible.
+Your mission is to write code to calculate the price of any conceivable shopping basket (containing only books of the same series), giving as big a discount as possible.
 
 For example, how much does this basket of books cost?
 
@@ -26,36 +26,36 @@ For example, how much does this basket of books cost?
 
 One way of grouping these 8 books is:
 
-- 1 group of 5 --> 25% discount (1st,2nd,3rd,4th,5th)
-- +1 group of 3 --> 10% discount (1st,2nd,3rd)
+- 1 group of 5 (1st, 2nd,3rd, 4th, 5th)
+- 1 group of 3 (1st, 2nd, 3rd)
 
 This would give a total of:
 
 - 5 books at a 25% discount
-- +3 books at a 10% discount
+- 3 books at a 10% discount
 
 Resulting in:
 
-- 5 × (8 - 2.00) = 5 × 6.00 = $30.00
-- +3 × (8 - 0.80) = 3 × 7.20 = $21.60
+- 5 × (100% - 25%) * $8 = 5 × $6.00 = $30.00, plus
+- 3 × (100% - 10%) * $8 = 3 × $7.20 = $21.60
 
-For a total of $51.60
+Which equals $51.60.
 
 However, a different way to group these 8 books is:
 
-- 1 group of 4 books --> 20% discount  (1st,2nd,3rd,4th)
-- +1 group of 4 books --> 20% discount  (1st,2nd,3rd,5th)
+- 1 group of 4 books (1st, 2nd, 3rd, 4th)
+- 1 group of 4 books (1st, 2nd, 3rd, 5th)
 
 This would give a total of:
 
 - 4 books at a 20% discount
-- +4 books at a 20% discount
+- 4 books at a 20% discount
 
 Resulting in:
 
-- 4 × (8 - 1.60) = 4 × 6.40 = $25.60
-- +4 × (8 - 1.60) = 4 × 6.40 = $25.60
+- 4 × (100% - 20%) * $8 = 4 × $6.40 = $25.60, plus
+- 4 × (100% - 20%) * $8 = 4 × $6.40 = $25.60
 
-For a total of $51.20
+Which equals $51.20.
 
 And $51.20 is the price with the biggest discount.

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

@@ -36,7 +36,7 @@ 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.
+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.

exercises/practice/darts/.docs/instructions.md

@@ -12,7 +12,7 @@ In our particular instance of the game, the target rewards 4 different amounts o
 - If the dart lands in the inner circle of the target, player earns 10 points.
 
 The outer circle has a radius of 10 units (this is equivalent to the total radius for the entire target), the middle circle a radius of 5 units, and the inner circle a radius of 1.
-Of course, they are all centered at the same point (that is, the circles are [concentric][] defined by the coordinates (0, 0).
+Of course, they are all centered at the same point — that is, the circles are [concentric][] defined by the coordinates (0, 0).
 
 Write a function that given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), returns the correct amount earned by a dart landing at that point.
 

exercises/practice/error-handling/.docs/instructions.md

@@ -2,9 +2,7 @@
 
 Implement various kinds of error handling and resource management.
 
-An important point of programming is how to handle errors and close
-resources even if errors occur.
+An important point of programming is how to handle errors and close resources even if errors occur.
 
-This exercise requires you to handle various errors. Because error handling
-is rather programming language specific you'll have to refer to the tests
-for your track to see what's exactly required.
+This exercise requires you to handle various errors.
+Because error handling is rather programming language specific you'll have to refer to the tests for your track to see what's exactly required.

exercises/practice/gigasecond/.docs/introduction.md

@@ -13,12 +13,12 @@ Then we can use metric system prefixes for writing large numbers of seconds in m
 - Perhaps you and your family would travel to somewhere exotic for two megaseconds (that's two million seconds).
 - And if you and your spouse were married for _a thousand million_ seconds, you would celebrate your one gigasecond anniversary.
 
-```exercism/note
+~~~~exercism/note
 If we ever colonize Mars or some other planet, measuring time is going to get even messier.
 If someone says "year" do they mean a year on Earth or a year on Mars?
 
 The idea for this exercise came from the science fiction novel ["A Deepness in the Sky"][vinge-novel] by author Vernor Vinge.
 In it the author uses the metric system as the basis for time measurements.
 
 [vinge-novel]: https://www.tor.com/2017/08/03/science-fiction-with-something-for-everyone-a-deepness-in-the-sky-by-vernor-vinge/
-```
+~~~~

exercises/practice/hexadecimal/.docs/instructions.md

@@ -2,7 +2,6 @@
 
 Convert a hexadecimal number, represented as a string (e.g. "10af8c"), to its decimal equivalent using first principles (i.e. no, you may not use built-in or external libraries to accomplish the conversion).
 
-On the web we use hexadecimal to represent colors, e.g. green: 008000,
-teal: 008080, navy: 000080).
+On the web we use hexadecimal to represent colors, e.g. green: 008000, teal: 008080, navy: 000080).
 
 The program should handle invalid hexadecimal strings.

exercises/practice/killer-sudoku-helper/.docs/instructions.md

@@ -56,8 +56,8 @@ The screenshots above have been generated using [F-Puzzles.com](https://www.f-pu
 
 [sudoku-rules]: https://masteringsudoku.com/sudoku-rules-beginners/
 [killer-guide]: https://masteringsudoku.com/killer-sudoku/
-[one-solution-img]: https://media.githubusercontent.com/media/exercism/v3-files/main/julia/killer-sudoku-helper/example1.png
-[four-solutions-img]: https://media.githubusercontent.com/media/exercism/v3-files/main/julia/killer-sudoku-helper/example2.png
-[not-possible-img]: https://media.githubusercontent.com/media/exercism/v3-files/main/julia/killer-sudoku-helper/example3.png
+[one-solution-img]: https://exercism-v3-icons.s3.eu-west-2.amazonaws.com/images/exercises/killer-sudoku-helper/example1.png
+[four-solutions-img]: https://exercism-v3-icons.s3.eu-west-2.amazonaws.com/images/exercises/killer-sudoku-helper/example2.png
+[not-possible-img]: https://exercism-v3-icons.s3.eu-west-2.amazonaws.com/images/exercises/killer-sudoku-helper/example3.png
 [clover-puzzle]: https://app.crackingthecryptic.com/sudoku/HqTBn3Pr6R
 [goodliffe-video]: https://youtu.be/c_NjEbFEeW0?t=1180

exercises/practice/linked-list/.docs/instructions.md

@@ -13,7 +13,7 @@ Sometimes a station gets closed down, and in that case the station needs to be r
 
 The size of a route is measured not by how far the train travels, but by how many stations it stops at.
 
-```exercism/note
+~~~~exercism/note
 The linked list is a fundamental data structure in computer science, often used in the implementation of other data structures.
 As the name suggests, it is a list of nodes that are linked together.
 It is a list of "nodes", where each node links to its neighbor or neighbors.
@@ -23,4 +23,4 @@ In a **doubly linked list** each node links to both the node that comes before,
 If you want to dig deeper into linked lists, check out [this article][intro-linked-list] that explains it using nice drawings.
 
 [intro-linked-list]: https://medium.com/basecs/whats-a-linked-list-anyway-part-1-d8b7e6508b9d
-```
+~~~~

exercises/practice/nucleotide-count/.docs/instructions.md

@@ -1,10 +1,12 @@
 # Instructions
 
-Each of us inherits from our biological parents a set of chemical instructions known as DNA that influence how our bodies are constructed. All known life depends on DNA!
+Each of us inherits from our biological parents a set of chemical instructions known as DNA that influence how our bodies are constructed.
+All known life depends on DNA!
 
 > Note: You do not need to understand anything about nucleotides or DNA to complete this exercise.
 
-DNA is a long chain of other chemicals and the most important are the four nucleotides, adenine, cytosine, guanine and thymine. A single DNA chain can contain billions of these four nucleotides and the order in which they occur is important!
+DNA is a long chain of other chemicals and the most important are the four nucleotides, adenine, cytosine, guanine and thymine.
+A single DNA chain can contain billions of these four nucleotides and the order in which they occur is important!
 We call the order of these nucleotides in a bit of DNA a "DNA sequence".
 
 We represent a DNA sequence as an ordered collection of these four nucleotides and a common way to do that is with a string of characters such as "ATTACG" for a DNA sequence of 6 nucleotides.

exercises/practice/octal/.docs/instructions.md

@@ -1,11 +1,9 @@
 # Instructions
 
-Convert an octal number, represented as a string (e.g. '1735263'), to its
-decimal equivalent using first principles (i.e. no, you may not use built-in or
-external libraries to accomplish the conversion).
+Convert an octal number, represented as a string (e.g. '1735263'), to its decimal equivalent using first principles (i.e. no, you may not use built-in or external libraries to accomplish the conversion).
 
-Implement octal to decimal conversion.  Given an octal input
-string, your program should produce a decimal output.
+Implement octal to decimal conversion.
+Given an octal input string, your program should produce a decimal output.
 
 ## Note
 

exercises/practice/pangram/.docs/instructions.md

@@ -5,4 +5,4 @@ Your task is to figure out if a sentence is a pangram.
 A pangram is a sentence using every letter of the alphabet at least once.
 It is case insensitive, so it doesn't matter if a letter is lower-case (e.g. `k`) or upper-case (e.g. `K`).
 
-For this exercise we only use the basic letters used in the English alphabet: `a` to `z`.
+For this exercise, a sentence is a pangram if it contains each of the 26 letters in the English alphabet.

exercises/practice/pangram/.docs/introduction.md

@@ -7,10 +7,10 @@ To give a comprehensive sense of the font, the random sentences should use **all
 They're running a competition to get suggestions for sentences that they can use.
 You're in charge of checking the submissions to see if they are valid.
 
-```exercism/note
+~~~~exercism/note
 Pangram comes from Greek, παν γράμμα, pan gramma, which means "every letter".
 
 The best known English pangram is:
 
 > The quick brown fox jumps over the lazy dog.
-```
+~~~~

exercises/practice/parallel-letter-frequency/.docs/instructions.md

@@ -2,7 +2,6 @@
 
 Count the frequency of letters in texts using parallel computation.
 
-Parallelism is about doing things in parallel that can also be done
-sequentially. A common example is counting the frequency of letters.
-Create a function that returns the total frequency of each letter in a
-list of texts and that employs parallelism.
+Parallelism is about doing things in parallel that can also be done sequentially.
+A common example is counting the frequency of letters.
+Create a function that returns the total frequency of each letter in a list of texts and that employs parallelism.

exercises/practice/queen-attack/.docs/instructions.md

@@ -21,5 +21,5 @@ So if you are told the white queen is at `c5` (zero-indexed at column 2, row 3)
   a b c d e f g h
 ```
 
-You are also be able to answer whether the queens can attack each other.
+You are also able to answer whether the queens can attack each other.
 In this case, that answer would be yes, they can, because both pieces share a diagonal.

exercises/practice/roman-numerals/.docs/instructions.md

@@ -36,6 +36,6 @@ In Roman numerals 1990 is MCMXC:
 2000=MM
 8=VIII
 
-Learn more about [Roman numberals on Wikipedia][roman-numerals].
+Learn more about [Roman numerals on Wikipedia][roman-numerals].
 
 [roman-numerals]: https://wiki.imperivm-romanvm.com/wiki/Roman_Numerals

exercises/practice/saddle-points/.docs/instructions.md

@@ -5,20 +5,22 @@ Your task is to find the potential trees where you could build your tree house.
 The data company provides the data as grids that show the heights of the trees.
 The rows of the grid represent the east-west direction, and the columns represent the north-south direction.
 
-An acceptable tree will be the the largest in its row, while being the smallest in its column.
+An acceptable tree will be the largest in its row, while being the smallest in its column.
 
 A grid might not have any good trees at all.
 Or it might have one, or even several.
 
 Here is a grid that has exactly one candidate tree.
 
+```text
     1  2  3  4
   |-----------
 1 | 9  8  7  8
 2 | 5  3  2  4  <--- potential tree house at row 2, column 1, for tree with height 5
 3 | 6  6  7  1
+```
 
-- Row 2 has values 5, 3, and 1. The largest value is 5.
+- Row 2 has values 5, 3, 2, and 4. The largest value is 5.
 - Column 1 has values 9, 5, and 6. The smallest value is 5.
 
 So the point at `[2, 1]` (row: 2, column: 1) is a great spot for a tree house.

exercises/practice/saddle-points/.docs/introduction.md

@@ -1,9 +1,11 @@
 # Introduction
 
-You are planning on building a tree house in the woods near your house so that you can watch the sun rise and set.
+You plan to build a tree house in the woods near your house so that you can watch the sun rise and set.
 
-You've obtained data from a local survey company that shows the heights of all the trees in each rectangular section of the map.
-You need to analyze each grid on the map to find the perfect tree for your tree house.
+You've obtained data from a local survey company that show the height of every tree in each rectangular section of the map.
+You need to analyze each grid on the map to find good trees for your tree house.
 
-The best tree will be the tallest tree compared to all the other trees to the east and west, so that you have the best possible view of the sunrises and sunsets.
-You don't like climbing too much, so the perfect tree will also be the shortest among all the trees to the north and to the south.
+A good tree is both:
+
+- taller than every tree to the east and west, so that you have the best possible view of the sunrises and sunsets.
+- shorter than every tree to the north and south, to minimize the amount of tree climbing.

exercises/practice/secret-handshake/.docs/instructions.md

@@ -43,5 +43,6 @@ jump, double blink
 
 ~~~~exercism/note
 If you aren't sure what binary is or how it works, check out [this binary tutorial][intro-to-binary].
+
 [intro-to-binary]: https://medium.com/basecs/bits-bytes-building-with-binary-13cb4289aafa
 ~~~~

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

@@ -18,11 +18,11 @@ Then you repeat the following steps:
 You keep repeating these steps until you've gone through every number in your list.
 At the end, all the unmarked numbers are prime.
 
-```exercism/note
+~~~~exercism/note
 [Wikipedia's Sieve of Eratosthenes article][eratosthenes] has a useful graphic that explains the algorithm.
 
 The tests don't check that you've implemented the algorithm, only that you've come up with the correct list of primes.
 A good first test is to check that you do not use division or remainder operations.
 
 [eratosthenes]: https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes
-```
+~~~~

exercises/practice/strain/.docs/instructions.md

@@ -1,9 +1,7 @@
 # Instructions
 
-Implement the `keep` and `discard` operation on collections. Given a collection
-and a predicate on the collection's elements, `keep` returns a new collection
-containing those elements where the predicate is true, while `discard` returns
-a new collection containing those elements where the predicate is false.
+Implement the `keep` and `discard` operation on collections.
+Given a collection and a predicate on the collection's elements, `keep` returns a new collection containing those elements where the predicate is true, while `discard` returns a new collection containing those elements where the predicate is false.
 
 For example, given the collection of numbers:
 
@@ -23,12 +21,9 @@ While your discard operation should produce:
 
 Note that the union of keep and discard is all the elements.
 
-The functions may be called `keep` and `discard`, or they may need different
-names in order to not clash with existing functions or concepts in your
-language.
+The functions may be called `keep` and `discard`, or they may need different names in order to not clash with existing functions or concepts in your language.
 
 ## Restrictions
 
-Keep your hands off that filter/reject/whatchamacallit functionality
-provided by your standard library!  Solve this one yourself using other
-basic tools instead.
+Keep your hands off that filter/reject/whatchamacallit functionality provided by your standard library!
+Solve this one yourself using other basic tools instead.

exercises/practice/sum-of-multiples/.docs/instructions.md

@@ -7,12 +7,12 @@ The points awarded depend on two things:
 - The level (a number) that the player completed.
 - The base value of each magical item collected by the player during that level.
 
-The energy points are awarded according to the following rules:  
+The energy points are awarded according to the following rules:
 
 1. For each magical item, take the base value and find all the multiples of that value that are less than the level number.
 2. Combine the sets of numbers.
 3. Remove any duplicates.
-4. Calculate the sum of all the numbers that are left.  
+4. Calculate the sum of all the numbers that are left.
 
 Let's look at an example:
 
@@ -24,4 +24,4 @@ To calculate the energy points earned by the player, we need to find all the uni
 - Multiples of 5 less than 20: `{5, 10, 15}`
 - Combine the sets and remove duplicates: `{3, 5, 6, 9, 10, 12, 15, 18}`
 - Sum the unique multiples: `3 + 5 + 6 + 9 + 10 + 12 + 15 + 18 = 78`
-- Therefore, the player earns **78** energy points for completing level 20 and finding the two magical items with base values of 3 and 5
+- Therefore, the player earns **78** energy points for completing level 20 and finding the two magical items with base values of 3 and 5.