Regenerate exercise READMEs to include upstream formatting tweaks

Katrina Owen · Katrina Owen · commit 2050602a2ffc · 2018-02-04T11:50:17.000-07:00
diff --git a/exercises/custom-set/README.md b/exercises/custom-set/README.md
@@ -1,4 +1,4 @@
-# Custom-Set
+# Custom Set
 
 Create a custom set type.
 
diff --git a/exercises/dot-dsl/README.md b/exercises/dot-dsl/README.md
@@ -1,4 +1,4 @@
-# Dot Dsl
+# DOT DSL
 
 Write a Domain Specific Language similar to the Graphviz dot language.
 
diff --git a/exercises/isbn-verifier/README.md b/exercises/isbn-verifier/README.md
@@ -1,43 +1,72 @@
-# Isbn Verifier
+# ISBN Verifier
 
-Check if a given ISBN-10 is valid.
+The [ISBN-10 verification process](https://en.wikipedia.org/wiki/International_Standard_Book_Number) is used to validate book identification
+numbers. These normally contain dashes and look like: `3-598-21508-8`
 
-## Functionality
+## ISBN
+
+The ISBN-10 format is 9 digits (0 to 9) plus one check character (either a digit or an X only). In the case the check character is an X, this represents the value '10'. These may be communicated with or without hyphens, and can be checked for their validity by the following formula:
+
+```
+(x1 * 10 + x2 * 9 + x3 * 8 + x4 * 7 + x5 * 6 + x6 * 5 + x7 * 4 + x8 * 3 + x9 * 2 + x10 * 1) mod 11 == 0
+```
+
+If the result is 0, then it is a valid ISBN-10, otherwise it is invalid.
+
+## Example
+
+Let's take the ISBN-10 `3-598-21508-8`. We plug it in to the formula, and get:
+```
+(3 * 10 + 5 * 9 + 9 * 8 + 8 * 7 + 2 * 6 + 1 * 5 + 5 * 4 + 0 * 3 + 8 * 2 + 8 * 1) mod 11 == 0
+```
+
+Since the result is 0, this proves that our ISBN is valid.
+
+## Task
 
-Given an unkown string the program should check if the provided string is a valid ISBN-10.
+Given a string the program should check if the provided string is a valid ISBN-10.
 Putting this into place requires some thinking about preprocessing/parsing of the string prior to calculating the check digit for the ISBN.
 
-The program should allow for ISBN-10 without the separating dashes to be verified as well.
+The program should be able to verify ISBN-10 both with and without separating dashes.
 
-## ISBN
 
-Let's take a random ISBN-10 number, say `3-598-21508-8` for this.
-The first digit block indicates the group where the ISBN belongs. Groups can consist of shared languages, geographic regions or countries. The leading '3' signals this ISBN is from a german speaking country.
-The following number block is to identify the publisher. Since this is a three digit publisher number there is a 5 digit title number for this book.
-The last digit in the ISBN is the check digit which is used to detect read errors.
+## Caveats
+
+Converting from strings to numbers can be tricky in certain languages.
+Now, it's even trickier since the check digit of an ISBN-10 may be 'X' (representing '10'). For instance `3-598-21507-X` is a valid ISBN-10.
+
+## Bonus tasks
+
+* Generate a valid ISBN-13 from the input ISBN-10 (and maybe verify it again with a derived verifier).
 
-The first 9 digits in the ISBN have to be between 0 and 9.
-The check digit can additionally be an 'X' to allow 10 to be a valid check digit as well.
+* Generate valid ISBN, maybe even from a given starting ISBN.
+## Exception messages
 
-A valid ISBN-10 is calculated with this formula `(x1 * 10 + x2 * 9 + x3 * 8 + x4 * 7 + x5 * 6 + x6 * 5 + x7 * 4 + x8 * 3 + x9 * 2 + x10 * 1) mod 11 == 0`
-So for our example ISBN this means:
-(3 * 10 + 5 * 9 + 9 * 8 + 8 * 7 + 2 * 6 + 1 * 5 + 5 * 4 + 0 * 3 + 8 * 2 + 8 * 1) mod 11 = 0
+Sometimes it is necessary to raise an exception. When you do this, you should include a meaningful error message to
+indicate what the source of the error is. This makes your code more readable and helps significantly with debugging. Not
+every exercise will require you to raise an exception, but for those that do, the tests will only pass if you include
+a message.
 
-Which proves that the ISBN is valid.
+To raise a message with an exception, just write it as an argument to the exception type. For example, instead of
+`raise Exception`, you shold write:
 
-### Submitting Exercises
+```python
+raise Exception("Meaningful message indicating the source of the error")
+```
+
+
+## Submitting Exercises
 
 Note that, when trying to submit an exercise, make sure the solution is in the `exercism/python/<exerciseName>` directory.
 
 For example, if you're submitting `bob.py` for the Bob exercise, the submit command would be something like `exercism submit <path_to_exercism_dir>/python/bob/bob.py`.
 
-
 For more detailed information about running tests, code style and linting,
 please see the [help page](http://exercism.io/languages/python).
 
 ## Source
 
-Converting a string into a number and some basic processing utilizing a relatable real world example. [https://en.wikipedia.org/wiki/International_Standard_Book_Number#ISBN-10_check_digit_calculation](https://en.wikipedia.org/wiki/International_Standard_Book_Number)
+Converting a string into a number and some basic processing utilizing a relatable real world example. [https://en.wikipedia.org/wiki/International_Standard_Book_Number#ISBN-10_check_digit_calculation](https://en.wikipedia.org/wiki/International_Standard_Book_Number#ISBN-10_check_digit_calculation)
 
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/pov/README.md b/exercises/pov/README.md
@@ -2,8 +2,6 @@
 
 Reparent a graph on a selected node.
 
-# Tree Reparenting
-
 This exercise is all about re-orientating a graph to see things from a different
 point of view. For example family trees are usually presented from the
 ancestor's perspective:
diff --git a/exercises/secret-handshake/README.md b/exercises/secret-handshake/README.md
@@ -54,7 +54,7 @@ please see the [help page](http://exercism.io/languages/python).
 
 ## Source
 
-Bert, in Mary Poppins http://www.imdb.com/title/tt0058331/quotes/qt0437047
+Bert, in Mary Poppins [http://www.imdb.com/title/tt0058331/quotes/qt0437047](http://www.imdb.com/title/tt0058331/quotes/qt0437047)
 
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/simple-cipher/README.md b/exercises/simple-cipher/README.md
@@ -58,15 +58,13 @@ would get the same thing as the Caesar Cipher.
 
 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 is not composed of numbers or
-capital letters.
+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 characters in length, accessible via Cipher#key (the #
-syntax means instance variable)
+at least 100 characters in length.
 
-If the key submitted has capital letters or numbers, raise a
-ValueError with a message to that effect.
+If the key submitted is not composed only of lowercase letters, your
+solution should handle the error in a language-appropriate way.
 
 ## Extensions
 
diff --git a/exercises/spiral-matrix/README.md b/exercises/spiral-matrix/README.md
@@ -1,23 +1,22 @@
 # Spiral Matrix
 
-
 Given the size, return a square matrix of numbers in spiral order.
 
 The matrix should be filled with natural numbers, starting from 1
 in the top-left corner, increasing in an inward, clockwise spiral order,
 like these examples:
 
-##### Spiral matrix of size 3
+###### Spiral matrix of size 3
 
-```plain
+```text
 1 2 3
 8 9 4
 7 6 5
 ```
 
-##### Spiral matrix of size 4
+###### Spiral matrix of size 4
 
-```plain
+```text
  1  2  3 4
 12 13 14 5
 11 16 15 6
diff --git a/exercises/two-fer/README.md b/exercises/two-fer/README.md
@@ -38,7 +38,7 @@ please see the [help page](http://exercism.io/languages/python).
 
 ## Source
 
-This is an exercise to introduce users to basic programming constructs, just after hello World. [https://en.wikipedia.org/wiki/Two-fer](https://en.wikipedia.org/wiki/Two-fer)
+This is an exercise to introduce users to basic programming constructs, just after Hello World. [https://en.wikipedia.org/wiki/Two-fer](https://en.wikipedia.org/wiki/Two-fer)
 
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Custom-Set`
	`1`	`+# Custom Set`
`2`	`2`
`3`	`3`	`Create a custom set type.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Dot Dsl`
	`1`	`+# DOT DSL`
`2`	`2`
`3`	`3`	`Write a Domain Specific Language similar to the Graphviz dot language.`
`4`	`4`