Changes and Corrections for rotational-cipher

Edits, spelling, and grammer nits.

Author: BethanyG

exercises/practice/rotational-cipher/.approaches/alphabet/content.md

@@ -16,28 +16,28 @@ def rotate(text, key):
     return result
 ```
 
-The approach starts with defining the a constant which holds the whole alphabets lowercase letters.
-After that the function `rotate` is declared, then a variable `result` is defined with the value of an empty string.
+The approach starts with defining the constant `ALPHABET` which is a string of all lowercase letters.
+The function `rotate()` is then declared, and a variable `result` is defined as an empty string.
 
-Then is all the letters from the text argument iterated over through a [`for loop`][for-loop].
-Then is checked if the letter is a letter, if it is a letter then is checked if it is a uppercased letter.
+The text argument is then iterated over via a [`for loop`][for-loop].
+Each element is checked to make sure it is a letter, and subsequently checked if it is uppercase or lowercase.
+Uppercase letters are converted to lowercase.
+Then index of each letter is found in the `AlPHABET` constant.
+The numeric key value is added to the letter index and [modulo (`%`)][modulo] 26 is used on the result.
+Finally, the new number is used as an index into the `AlPHABET` constant, and the resulting letter is converted back to uppercase.
 
-If it is a uppercased letter then it is converted to lowe case and finds its index in the `AlPHABET` constant.
-Then is the key added to the index and [modulo (`%`)][modulo] 26 is used on the result.
-Then is the letter at the index found in the `AlPHABET` constant and the letter is converted to upcase.
+Lowercase letters follow the same process without the conversion steps.
 
-If the letter is a lowercased letter then it does the same process but don't convert the letter to downcase and then to uppercase.
+If the element is not a letter (for example, space or punctuation) then it is added directly to the result string.
+The result string is returned once the loop finishes.
 
-If the letter is not a letter then is the letter added to the result.
-When the loop is finished we return the result.
+If only English letters are needed, the constant [`string.ascii_lowercase`][ascii_lowercase] can be imported from the [`string`][string] module.
 
-If you only want to use english letters so could you import the alphabet instead of defining it yourself.
-Since in the [`string`][string] module there is a constant called [`ascii_lowercase`][ascii_lowercase] which holds the lowercased alphabet.
 
 ```python
-import string
+from string import ascii_lowercase
 
-AlPHABET = string.ascii_lowercase
+AlPHABET = ascii_lowercase
 ```
 
 [ascii_lowercase]: https://docs.python.org/3/library/string.html#string.ascii_letters

exercises/practice/rotational-cipher/.approaches/ascii-values/content.md

@@ -14,37 +14,44 @@ def rotate(text, key):
     return result
 ```
 
-This approach uses [ascii values][ascii], ascii stands for American Standard Code for Information Interchange.
-It is a character encoding standard for electronic communication.
-It is a 7-bit code, which means that it can represent 128 different characters.
-The system uses numbers to represent various characters, symbols, and other entities.
+This approach uses [ascii values][ascii].
+ASCII stands for **A**merican **S**tandard **C**ode for **I**nformation **I**nterchange.
+It is a 7-bit character encoding standard for electronic communication first described in 1969, becoming a formal standard in 2015.
+It uses numbers to represent 128 different entities including carriage returns, whitespace characters, box characters, alphabetic characters, punctuation, and the numbers 0-9.
 
-In ascii can you find all the downcased letter in the range between 97 and 123.
-While the upcased letters are in the range between 65 and 91.
+In ascii, all the lowercase English letters appear between 97 and 123.
+While the uppercase letters are in the range between 65 and 91.
 
-The reason why you might not want to do this approach is that it only supports the english alphabet.
+~~~~exercism/caution
 
-The approach starts with defining the function `rotate`, then a variable `result` is defined with the value of an empty string.
-Then is all the letters from the text argument iterated over through a [`for loop`][for-loop].
-Then is checked if the letter is a letter, if it is a letter then is checked if it is a uppercased letter.
+This approach only supports the English alphabet.
+Non-English alphabets are not contiguous in their ascii number ranges, and are not consistently defined across platforms.
+For example, the Scandinavian letter: **å** has the extended ascii value of 132, but is used in combination with Latin characters that appear in the 65-91 and 97-123 ranges.
+This means that a shift for an extended ascii word containing **å** won't result in an accurate alphabet position for a Scandinavian language.
 
-Python has a built in function called `ord` that converts a [unicode][unicode] symbol to an integer.
-The unicode's first 128 characters are the same as ascii.
+~~~~
 
-If it is a uppercased letter then is [`ord`][ord] used to convert the letters to an integer and is then added with the key and then subtracted with 65.
-Then is the result of that [modulo (`%`)][modulo] 26 added with 65.
 
-That is because we want to know which index in the alphabet the letter is.
-And if the number is over 26 we want to make sure that it is in the range of 0-26.
-So we use modulo to make sure it is in that range.
-To use modulo for a range we have to make sure that it starts at zero, thereby are we subtracting the integer value of the letter with 65.
-After that to get the back to a letter we add 65 and use the [`chr`][chr] method which converts an an unicode value to a letter.
-After that is the new letter added to the result.
+The approach starts with defining the function `rotate()`, with a variable `result` is assigned to an empty string.
+The elements of the text argument are then iterated over using a [`for loop`][for-loop].
+Each element is checked to see if it is a letter, and then is checked if it is an uppercase letter.
 
-If the letter is a lowercased letter then is the same done but with the ascii value of 97 subtracted with the letter.
+Python has a builtin function called `ord` that converts a [unicode][unicode] symbol to an integer representation.
+Unicode's first 128 code points have the same numbers as their ascii counterparts.
 
-If the letter is not a letter then is the letter added to the result.
-When the loop is finished we return the result.
+If the element is an uppercase letter, [`ord`][ord] is used to convert the letter to an integer.
+The integer is added to the numeric key and then 65 is subtracted from the total.
+Finally, the result is [modulo (`%`)][modulo] 26 (_to put the value within the 2) and 65 is added back.
+
+This is because we want to know which letter of the alphabet the number will become.
+And if the new number is over 26 we want to make sure that it "wraps around" to remain in the range of 0-26.
+To properly use modulo for a range we have to make sure that it starts at zero, so we subtract 65.
+To get back to a letter in the asciii range we add 65 and use the [`chr`][chr] method to convert the value to a letter.
+
+The process is the same for a lowercase letter, but with 97 subtracted to put the letter in the lowercase ascii range of 97 - 123.
+
+Any element that is not a letter (_whitespace or punctuation_) is added directly to the result string.
+When all the elements have been looped over, the full result is returned.
 
 [ascii]: https://en.wikipedia.org/wiki/ASCII
 [chr]: https://docs.python.org/3/library/functions.html#chr

exercises/practice/rotational-cipher/.approaches/introduction.md

@@ -1,22 +1,30 @@
 # Introduction
 
 There are various ways to solve `rotational-cipher`.
-You can for example use a [ascii values][ascii], alphabet, recursion, and `str.translate`.
+You can for example use [ascii values][ascii], an alphabet `str` or `list`, recursion, or `str.translate`.
+
 
 ## General guidance
 
-The goal of this exercise is to rotate the letters in a string by a given key.
+The goal of this exercise is to shift the letters in a string by a given integer key between 0 and 26.
+The letter in the encrypted string is shifted for as many values (or "positions") as the value of the key.
 
 ## Approach: Using ascii values
 
-This approach is very simple and easy to understand.
-it uses the ascii value of the letters to rotate them.
-There the numbers 65-91 in the ascii range represent downcased letters.
-While 97-123 represent upcased letters.
+This approach is straightforward to understand.
+It uses the ascii value of the letters to rotate them within the message.
+The numbers 65-91 in the ascii range represent lowercase Latin letters, while 97-123 represent uppercase Latin letters.
+
+
+~~~~exercism/caution
+
+This approach only supports the English alphabet.
+Non-English alphabets are not contiguous in their ascii number ranges, and are not consistently defined across platforms.
+For example, the Scandinavian letter: **å** has the extended ascii value of 132, but is used in combination with Latin characters that appear in the 65-91 and 97-123 ranges.
+This means that a shift for an extended ascii word containing **å** won't result in an accurate alphabet position for a Scandinavian language.
+
+~~~~
 
-The reason why you might not want to do this approach is that it only supports the english alphabet.
-Say we want to use the scandinavian letter: **å**, then this approach will not work.
-Since **å** has the ascii value of 132.
 
 ```python
 def rotate(text, key):
@@ -34,16 +42,20 @@ def rotate(text, key):
 
 For more information, check the [ascii values approach][approach-ascii-values].
 
+
 ## Approach: Alphabet
 
-This approach is similar to the previous one, but instead of using the ascii values, it uses the index of the letter in the alphabet.
-It requires the storing of a string and unless you are using two strings you have to convert the letters from upper to lower case.
+This approach is similar to the ascii one, but it uses the index number of each letter in an alphabet string.
+It requires making a string for all the letters in an alphabet.
+And unless two strings are used, you will have to convert individual letters from lower to upper case (or vice-versa).
+
+The big advantage of this approach is the ability to use any alphabet (_although there are some issues with combining characters in Unicode._).
+Here, if we want to use the scandinavian letter: **å**, we can simply insert it into our string where we want it:
+`abcdefghijklmnopqrstuvwxyzå` and the rotation will work correctly.
 
-What this approach although give is the possibility to use any alphabet.
-Say we want to use the scandinavian letter: **å**, then we just add it where we want it:
-`abcdefghijklmnopqrstuvwxyzå` and it will rotate correctly around that.
 
 ```python
+# This only uses English characters
 AlPHABET = "abcdefghijklmnopqrstuvwxyz"
 
 def rotate(text, key):
@@ -61,14 +73,19 @@ def rotate(text, key):
 
 For more information, check the [Alphabet approach][approach-alphabet].
 
+
 ## Approach: Str translate
 
-This approach is similar to the previous one, but instead of using the index of the letter in the alphabet, it uses the `str.translate` method.
-The benefit of this approach is that it has no visible loop, thereby the code becomes more concise.
-What to note is that the `str.translate` still loops over the `string` thereby even if it is no visible loop, it doesn't mean that a method is not looping.
+This approach uses the [`str.translate`][str-translate] method to create a mapping from input to shifted string instead of using the index of an alphabet string to calculate the shift.
+The benefit of this approach is that it has no visible loop, making the code more concise.
+
+~~~~exercism/note
+`str.translate` **still loops over the `string`**  even if it is not visibly doing so.
+~~~~
+
 
 ```python
-AlPHABET = "abcdefghijklmnopqrstuvwxyz"
+AlPHABET = "abcdefghijklmnopqrstuvwxyz
 
 def rotate(text, key):
     translator = AlPHABET[key:] + AlPHABET[:key]
@@ -77,13 +94,19 @@ def rotate(text, key):
 
 For more information, check the [Str translate approach][approach-str-translate].
 
+
 ## Approach: Recursion
 
-In this approach we use a recursive function.
+This approach uses a recursive function.
 A recursive function is a function that calls itself.
 This approach can be more concise than other approaches, and may also be more readable for some audiences.
 
-The reason why you might not want to use this approach is that Python has a [recursion limit][recursion-limit] with a default of 1000.
+
+~~~~exercism/caution
+Python does not have any tail-call optimization and has a default [recursion limit][recursion-limit] of 1000 calls on the stack.
+Calculate your base case carefully to avoid errors.
+~~~~
+
 
 ```python
 AlPHABET = "abcdefghijklmnopqrstuvwxyz"
@@ -103,6 +126,7 @@ def rotate(text, key):
 
 For more information, check the [Recursion approach][approach-recursion].
 
+
 ## Benchmark
 
 For more information, check the [Performance article][article-performance].
@@ -114,3 +138,4 @@ For more information, check the [Performance article][article-performance].
 [approach-alphabet]: https://exercism.org/tracks/python/exercises/rotational-cipher/approaches/alphabet
 [article-performance]: https://exercism.org/tracks/python/exercises/rotational-cipher/articles/performance
 [recursion-limit]: https://docs.python.org/3/library/sys.html#sys.setrecursionlimit
+[str-translate]: https://docs.python.org/3/library/stdtypes.html?highlight=str%20translate#str.translate

exercises/practice/rotational-cipher/.approaches/recursion/content.md

@@ -16,23 +16,25 @@ def rotate(text, key):
         return first_letter + rotate(rest, key)
 ```
 
-This approach uses a very similar approach to alphabet.
-And uses the same logic but instead of a loop so does this approach use [concept:python/recursion]() to solve the problem.
+This approach uses the same logic as that of the `alphabet` approach, but instead of a `loop`, [concept:python/recursion]() is used to parse the text and solve the problem.
 
 Recursion is a programming technique where a function calls itself.
-It is a powerful technique, but can be more tricky to implement than a while loop.
-Recursion isn't that common in Python, it is more common in functional programming languages, like: [Elixir][elixir], [Haskell][haskell], and [Clojure][clojure].
+It is powerful, but can be more tricky to implement than a `while loop` or `for loop`.
+Recursive techniques are more common in functional programming languages like [Elixir][elixir], [Haskell][haskell], and [Clojure][clojure] than they are in Python.
 
-Solving this exercise with recursion removes the need for a "result" variable and the instantiation of a `loop`.
+Solving this exercise with recursion removes the need for a `result` variable and the instantiation of a `loop`.
 If the number is not equal to one, we call `<letter> + rotate(rest)`.
 Then the `rotate` function can execute the same code again with new values.
-Meaning we can get a long chain or stack of `<letter> + rotate(rest)` until the rest variable is exhausted and then the code adds `""`.
+We can build a long chain or "stack" of `<letter> + rotate(rest)` calls until the `rest` variable is exhausted and the code adds `""`.
 That translates to something like this: `<letter> + <letter> + <letter> + <letter> + ""`.
 
-In Python, we can't have a function call itself more than 1000 times by default.
-Code that exceeds this recursion limit will throw a [RecursionError][recursion-error].
-While it is possible to adjust the [recursion limit][recursion-limit], doing so risks crashing Python and may also crash your system.
+
+~~~~exercism/note
+By default, we can't have a function call itself more than 1000 times.
+Code that exceeds this recursion limit will throw a RecursionError.
+While it is possible to adjust the recursion limit, doing so risks crashing Python and may also crash your system.
 Casually raising the recursion limit is not recommended.
+~~~~
 
 [clojure]: https://exercism.org/tracks/clojure
 [elixir]: https://exercism.org/tracks/elixir

exercises/practice/rotational-cipher/.approaches/str-translate/content.md

@@ -8,45 +8,42 @@ def rotate(text, key):
     return text.translate(str.maketrans(AlPHABET + AlPHABET.upper(), translator + translator.upper()))
 ```
 
-This approach uses the [`<str>.translate`][translate] method to solve the problem.
+This approach uses the [`<str>.translate`][translate] method.
 `translate` takes a translation table as an argument.
 To create a translation table we use [str.`makestrans`][maketrans].
 
-The approach starts with defining the a constant which holds the whole alphabets lowercase letters.
-Then the function `rotate` is declared.
-Then is the `translator` variable defined with the value of the `AlPHABET` constant [sliced][slicing] from the key to the end and then the `AlPHABET` constant sliced from the start to the key.
+This approach starts with defining a constant of all the lowercase letters in the alphabet.
+Then the function `rotate()` is declared.
+A `translator` variable defined with the value of the `AlPHABET` constant [sliced][slicing] from the key to the end and then sliced from the start to the key.
 
-This is done so we have 2 strings which are the same but shifted by the key.
+This is done so we have 2 strings which are the same but shifted by the key value.
 Say we have the `AlPHABET` constant with the value of `abcdefghijklmnopqrstuvwxyz` and the key is 3.
 Then the `translator` variable will have the value of `defghijklmnopqrstuvwxyzabc`.
 
-Then is the `translate` method called on the `text` argument.
-The `translate` method takes a translation table as an argument.
-To create a translation table we use str.`makestrans`maketrans.
+`str.translate` is then called on the `text` argument.
+`str.translate` takes a translation table mapping start values to transformed values as an argument.
+To create a translation table, `str.makestrans` is used.
+`makestrans` takes 2 arguments: the first is the string to be translated, and the second is the string the first argument should be translated to.
 
-The `makestrans` method takes 2 arguments.
-The first argument is the string which holds the characters which should be translated.
-The second argument is the string which holds the characters which the characters from the first argument should be translated to.
+For our solution, the first argument is the `AlPHABET` constant + the `AlPHABET` constant in uppercase.
+The second argument is the `translator` variable + uppercase `translator` variable.
 
-The first argument is the `AlPHABET` constant and the `AlPHABET` constant uppercased.
-The second argument is the `translator` variable and the `translator` variable uppercased.
+`makestrans` does is that it takes the [Unicode][unicode] values of the first argument and maps them to the corresponding Unicode values in the second argument, creating a `dict`.
 
-What the `makestrans` does is that it takes the first argument and maps it to the second argument.
-It does that by creating a [dictionary], and converting the letter to [unicode][unicode].
 
 ```python
 >>> str.maketrans("abc", "def")
 {97: 100, 98: 101, 99: 102}
 ```
 
-The `translate` method takes the dictionary created by the `makestrans` method and uses it to translate the characters in the `text` argument.
+`str.translate` takes the `dict` created by `str.makestrans`  and uses it to translate the characters in the `text` argument.
 
 ```python
 >>> "abc".translate({97: 100, 98: 101, 99: 102})
 'def'
 ```
 
-When the loop is finished we return the result.
+Once the `str.translate` loop completes, we return the `result`.
 
 [maketrans]: https://docs.python.org/3/library/stdtypes.html#str.maketrans
 [slicing]: https://www.w3schools.com/python/python_strings_slicing.asp