Merge pull request #167 from BNAndras/sync-docs-and-metadata

Sync docs and metadata

Author: kapitaali

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

@@ -1,4 +1,4 @@
-# Description
+# Instructions
 
 Convert a phrase to its acronym.
 
@@ -10,8 +10,8 @@ Punctuation is handled as follows: hyphens are word separators (like whitespace)
 
 For example:
 
-|Input|Output|
-|-|-|
-|As Soon As Possible|ASAP|
-|Liquid-crystal display|LCD|
-|Thank George It's Friday!|TGIF|
+| Input                     | Output |
+| ------------------------- | ------ |
+| As Soon As Possible       | ASAP   |
+| Liquid-crystal display    | LCD    |
+| Thank George It's Friday! | TGIF   |

exercises/practice/acronym/.meta/config.json

@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "blurb": "Convert a phrase to its acronym.",
+  "blurb": "Convert a long phrase to its acronym.",
   "source": "Julien Vanier",
   "source_url": "https://github.com/monkbroc"
 }

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

@@ -22,6 +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.).
+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/anagram/.docs/instructions.md

@@ -1,13 +1,12 @@
 # Instructions
 
-Your task is to, given a target word and a set of candidate words, to find the subset of the candidates that are anagrams of the target.
+Given a target word and one or more candidate words, your task is to find the candidates that are anagrams of the target.
 
 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"`.
 
-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.
+The target word and candidate words are made up 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 words you need to find should be taken from the candidate words, using the same letter case.
 
-Given the target `"stone"` and candidates `"stone"`, `"tones"`, `"banana"`, `"tons"`, `"notes"`, `"Seton"`, the anagram set is `"tones"`, `"notes"`, `"Seton"`.
+Given the target `"stone"` and the candidate words `"stone"`, `"tones"`, `"banana"`, `"tons"`, `"notes"`, and `"Seton"`, the anagram words you need to find are `"tones"`, `"notes"`, and `"Seton"`.

exercises/practice/anagram/.meta/config.json

@@ -14,6 +14,13 @@
     ],
     "example": [
       ".meta/proof.ci.cob"
+    ],
+    "invalidator": [
+      "test.ps1",
+      "test.sh",
+      "bin/fetch-cobolcheck",
+      "bin/fetch-cobolcheck.ps1",
+      "config.properties"
     ]
   },
   "blurb": "Given a word and a list of possible anagrams, select the correct sublist.",

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

@@ -5,9 +5,9 @@ An [Armstrong number][armstrong-number] is a number that is the sum of its own d
 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.
 

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

@@ -1,11 +1,9 @@
-# Description
+# Instructions
 
-Create an implementation of the atbash cipher, an ancient encryption system created in the Middle East.
+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,13 +12,12 @@ Plain:  abcdefghijklmnopqrstuvwxyz
 Cipher: zyxwvutsrqponmlkjihgfedcba
 ```
 
-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.
+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, leaving numbers unchanged, and punctuation is excluded.
+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
 

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

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

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

@@ -1,36 +1,29 @@
 # Instructions
 
-Implement a binary search algorithm. Do not use any COBOL proprietary
-search routines (eg. SEARCH).
+Your task is to implement a binary search algorithm.
 
-Searching a sorted collection is a common task. A dictionary is a sorted
-list of word definitions. Given a word, one can find its definition. A
-telephone book is a sorted list of people's names, addresses, and
-telephone numbers. Knowing someone's name allows one to quickly find
-their telephone number and address.
+A binary search algorithm finds an item in a list by repeatedly splitting it in half, only keeping the half which contains the item we're looking for.
+It allows us to quickly narrow down the possible locations of our item until we find it, or until we've eliminated all possible locations.
 
-If the list to be searched contains more than a few items (a dozen, say)
-a binary search will require far fewer comparisons than a linear search,
-but it imposes the requirement that the list be sorted.
+~~~~exercism/caution
+Binary search only works when a list has been sorted.
+~~~~
 
-In computer science, a binary search or half-interval search algorithm
-finds the position of a specified input value (the search "key") within
-an array sorted by key value.
+The algorithm looks like this:
 
-In each step, the algorithm compares the search key value with the key
-value of the middle element of the array.
+- 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.
+- If every element of the list has been eliminated then the item is not in the list.
+- Otherwise, repeat the process on the part of the list that has not been eliminated.
 
-If the keys match, then a matching element has been found and its index,
-or position, is returned.
+Here's an example:
 
-Otherwise, if the search key is less than the middle element's key, then
-the algorithm repeats its action on the sub-array to the left of the
-middle element or, if the search key is greater, on the sub-array to the
-right.
+Let's say we're looking for the number 23 in the following sorted list: `[4, 8, 12, 16, 23, 28, 32]`.
 
-If the remaining array to be searched is empty, then the key cannot be
-found in the array and a special "not found" indication is returned.
-
-A binary search halves the number of items to check with each iteration,
-so locating an item (or determining its absence) takes logarithmic time.
-A binary search is a dichotomic divide and conquer search algorithm.
+- We start by comparing 23 with the middle element, 16.
+- Since 23 is greater than 16, we can eliminate the left half of the list, leaving us with `[23, 28, 32]`.
+- We then compare 23 with the new middle element, 28.
+- Since 23 is less than 28, we can eliminate the right half of the list: `[23]`.
+- We've found our item.

exercises/practice/binary-search/.docs/introduction.md

@@ -0,0 +1,13 @@
+# Introduction
+
+You have stumbled upon a group of mathematicians who are also singer-songwriters.
+They have written a song for each of their favorite numbers, and, as you can imagine, they have a lot of favorite numbers (like [0][zero] or [73][seventy-three] or [6174][kaprekars-constant]).
+
+You are curious to hear the song for your favorite number, but with so many songs to wade through, finding the right song could take a while.
+Fortunately, they have organized their songs in a playlist sorted by the title — which is simply the number that the song is about.
+
+You realize that you can use a binary search algorithm to quickly find a song given the title.
+
+[zero]: https://en.wikipedia.org/wiki/0
+[seventy-three]: https://en.wikipedia.org/wiki/73_(number)
+[kaprekars-constant]: https://en.wikipedia.org/wiki/6174_(number)