Update and reformat all READMEs

docs/EXERCISE_README_INSERT.md

@@ -1,9 +1,8 @@
-### Submitting Exercises
+## 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).

exercises/accumulate/README.md

@@ -25,16 +25,12 @@ Keep your hands off that collect/map/fmap/whatchamacallit functionality
 provided by your standard library!
 Solve this one yourself using other basic tools instead.
 
-Lisp specific: it's perfectly fine to use `MAPCAR` or the equivalent,
-as this is idiomatic Lisp, not a library function.
-
-### Submitting Exercises
+## 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).
 

exercises/acronym/README.md

@@ -7,14 +7,12 @@ Techies love their TLA (Three Letter Acronyms)!
 Help generate some jargon by writing a program that converts a long name
 like Portable Network Graphics to its acronym (PNG).
 
-
-### Submitting Exercises
+## 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).
 

exercises/all-your-base/README.md

@@ -6,6 +6,7 @@ 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.
 
@@ -28,16 +29,14 @@ The number 1120, *in base 3*, means:
 
 I think you got the idea!
 
-
 *Yes. Those three numbers above are exactly the same. Congratulations!*
 
-### Submitting Exercises
+## 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).
 

exercises/allergies/README.md

@@ -29,14 +29,12 @@ 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.
 
-
-### Submitting Exercises
+## 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).
 

exercises/alphametics/README.md

@@ -7,7 +7,7 @@ letters in words are replaced with numbers.
 
 For example `SEND + MORE = MONEY`:
 
-```
+```text
   S E N D
   M O R E +
 -----------
@@ -16,7 +16,7 @@ M O N E Y
 
 Replacing these with valid numbers gives:
 
-```
+```text
   9 5 6 7
   1 0 8 5 +
 -----------
@@ -31,13 +31,12 @@ a multi-digit number must not be zero.
 
 Write a function to solve alphametics puzzles.
 
-### Submitting Exercises
+## 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).
 

exercises/anagram/README.md

@@ -6,13 +6,12 @@ Given `"listen"` and a list of candidates like `"enlists" "google"
 "inlets" "banana"` the program should return a list containing
 `"inlets"`.
 
-### Submitting Exercises
+## 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).
 

exercises/atbash-cipher/README.md

@@ -9,7 +9,7 @@ letter, the second with the second-last, and so on.
 
 An Atbash cipher for the Latin alphabet would be as follows:
 
-```plain
+```text
 Plain:  abcdefghijklmnopqrstuvwxyz
 Cipher: zyxwvutsrqponmlkjihgfedcba
 ```
@@ -23,17 +23,17 @@ being 5 letters, and punctuation is excluded. This is to make it harder to guess
 things based on word boundaries.
 
 ## Examples
+
 - Encoding `test` gives `gvhg`
 - Decoding `gvhg` gives `test`
 - Decoding `gsvjf rxpyi ldmul cqfnk hlevi gsvoz abwlt` gives `thequickbrownfoxjumpsoverthelazydog`
 
-### Submitting Exercises
+## 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).
 

exercises/beer-song/README.md

@@ -4,7 +4,7 @@ Produce the lyrics to that beloved classic, that field-trip favorite: 99 Bottles
 
 Note that not all verses are identical.
 
-```plain
+```text
 99 bottles of beer on the wall, 99 bottles of beer.
 Take one down and pass it around, 98 bottles of beer on the wall.
 
@@ -320,13 +320,12 @@ are some additional things you could try:
 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?
 
-### Submitting Exercises
+## 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).
 

exercises/binary-search/README.md

@@ -34,13 +34,12 @@ 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.
 
-### Submitting Exercises
+## 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).
 

exercises/binary/README.md

@@ -7,10 +7,12 @@ string, your program should produce a decimal output. The
 program should handle invalid inputs.
 
 ## Note
+
 - Implement the conversion yourself.
   Do not use something else to perform the conversion for you.
 
 ## About Binary (Base-2)
+
 Decimal is a base-10 system.
 
 A number 23 in base 10 notation can be understood
@@ -28,13 +30,12 @@ Binary is similar, but uses powers of 2 rather than powers of 10.
 
 So: `101 => 1*2^2 + 0*2^1 + 1*2^0 => 1*4 + 0*2 + 1*1 => 4 + 1 => 5 base 10`.
 
-### Submitting Exercises
+## 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).
 

exercises/bob/README.md

@@ -11,13 +11,12 @@ anything.
 
 He answers 'Whatever.' to anything else.
 
-### Submitting Exercises
+## 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).
 

exercises/book-store/README.md

@@ -3,20 +3,20 @@
 To try and encourage more sales of different books from a popular 5 book
 series, a bookshop has decided to offer discounts on multiple book purchases.
 
-One copy of any of the five books costs $8. 
+One copy of any of the five books costs $8.
 
 If, however, you buy two different books, you get a 5%
 discount on those two books.
 
-If you buy 3 different books, you get a 10% discount. 
+If you buy 3 different books, you get a 10% discount.
 
 If you buy 4 different books, you get a 20% discount.
 
-If you buy all 5, you get a 25% 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. 
+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
@@ -30,7 +30,7 @@ For example, how much does this basket of books cost?
 - 2 copies of the third book
 - 1 copy of the fourth book
 - 1 copy of the fifth book
- 
+
 One way of grouping these 8 books is:
 
 - 1 group of 5 --> 25% discount (1st,2nd,3rd,4th,5th)
@@ -67,13 +67,12 @@ For a total of $51.20
 
 And $51.20 is the price with the biggest discount.
 
-### Submitting Exercises
+## 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).
 

exercises/bracket-push/README.md

@@ -3,13 +3,12 @@
 Given a string containing brackets `[]`, braces `{}` and parentheses `()`,
 verify that all the pairs are matched and nested correctly.
 
-### Submitting Exercises
+## 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).
 

exercises/change/README.md

@@ -16,19 +16,18 @@ that the sum of the coins' value would equal the correct amount of change.
 - Can you ask for negative change?
 - Can you ask for a change value smaller than the smallest coin value?
 
-### Submitting Exercises
+## 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
 
-Software Craftsmanship - Kata-logue [http://craftsmanship.sv.cmu.edu/exercises/coin-change-kata](http://craftsmanship.sv.cmu.edu/exercises/coin-change-kata)
+Software Craftsmanship - Coin Change Kata [https://web.archive.org/web/20130115115225/http://craftsmanship.sv.cmu.edu:80/exercises/coin-change-kata](https://web.archive.org/web/20130115115225/http://craftsmanship.sv.cmu.edu:80/exercises/coin-change-kata)
 
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.

exercises/circular-buffer/README.md

@@ -31,25 +31,31 @@ If the buffer has 7 elements then it is completely full:
 When the buffer is full an error will be raised, alerting the client
 that further writes are blocked until a slot becomes free.
 
-The client can opt to overwrite the oldest data with a forced write. In
-this case, two more elements — A & B — are added and they overwrite the
-3 & 4:
+When the buffer is full, the client can opt to overwrite the oldest
+data with a forced write. In this case, two more elements — A & B —
+are added and they overwrite the 3 & 4:
 
     [6][7][8][9][A][B][5]
 
-Finally, if two elements are now removed then what would be returned is
-not 3 & 4 but 5 & 6 because A & B overwrote the 3 & the 4 yielding the
-buffer with:
+3 & 4 have been replaced by A & B making 5 now the oldest data in the
+buffer. Finally, if two elements are removed then what would be
+returned is 5 & 6 yielding the buffer:
 
     [ ][7][8][9][A][B][ ]
 
-### Submitting Exercises
+Because there is space available, if the client again uses overwrite
+to store C & D then the space where 5 & 6 were stored previously will
+be used not the location of 7 & 8. 7 is still the oldest element and
+the buffer is once again full.
+
+    [D][7][8][9][A][B][C]
+
+## 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).
 

exercises/clock/README.md

@@ -6,13 +6,12 @@ You should be able to add and subtract minutes to it.
 
 Two clocks that represent the same time should be equal to each other.
 
-### Submitting Exercises
+## 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).
 

exercises/collatz-conjecture/.meta/hints.md

@@ -0,0 +1,3 @@
+## Notes
+
+The Collatz Conjecture is only concerned with strictly positive integers, so your solution should return `None` if given 0 or a negative integer.