Misc text updates following initial review

...

Co-Authored-By: André Santos <andrerfcsantos@gmail.com>

concepts/regular-expressions/.meta/config.json

@@ -1,5 +1,5 @@
 {
-  "blurb": "Regular expressions",
+  "blurb": "A regular expression is a sequence of characters that specify a search pattern.",
   "authors": ["norbs57"],
   "contributors": []
 }

concepts/regular-expressions/about.md

@@ -6,11 +6,24 @@ Package [regexp][package-regexp] offers support for regular expressions in Go.
 
 The [syntax][regexp-syntax] of the regular expressions accepted is the same general syntax used by Perl, Python, and other languages. 
 
-All characters are UTF-8-encoded code points. 
-Following `utf8.DecodeRune`, each byte of an invalid UTF-8 sequence is treated as if it encoded `utf8.RuneError (U+FFFD)`.
+Both the search patterns and the input texts are interpreted as UTF-8.  
 
-It is convenient to write regular expressions as [raw string literals][raw-string-literals] enclosed by backticks.
-This avoids having to quote the backslashes.
+When using backticks ``(`)`` to make strings, backslashes `(\)`  don't have any special
+meaning, and don't mark the beginning of special characters like tabs `\t` or
+newlines `\`n:
+
+```go
+"\t\n" // regular string literal with 2 characters: a tab and a newline
+`\t\n`// raw string literal with 4 characters: two backslashes, a 't', and an 'n'
+```
+
+Because of this, using backticks is desirable to make regular expressions,
+because it means we don't need to escape backslashes:
+
+```go
+"\\" // string with a single backslash
+`\\` // string with 2 backslashes
+```
 
 ## Type `RegExp`
 
@@ -25,9 +38,18 @@ re, err = regexp.Compile(`a|b)+`)
 fmt.Println(re, err) // => <nil> error parsing regexp: unexpected ): `a|b)+`
 ```
 
-Function `MustCompile` is like `Compile` but panics if the expression cannot be parsed.
-It simplifies safe initialization of global variables holding compiled regular expressions.
-
+Function `MustCompile` is a convenient alternative to `Compile`: 
+
+```go 
+re = regexp.MustCompile(`[a-z]+\d*`)
+```
+
+Using this function, there is no need to handle an error. 
+
+~~~~exercism/caution
+ `MustCompile` should only be used when we know for sure the pattern does compile, as otherwise the program will panic.
+ ~~~~
+
 There are 16 methods of `Regexp` that match a regular expression and identify the matched text.
 Their names are matched by this regular expression:
 

concepts/regular-expressions/introduction.md

@@ -14,11 +14,20 @@ re, err = regexp.Compile(`a|b)+`)
 fmt.Println(re, err) // => <nil> error parsing regexp: unexpected ): `a|b)+`
 ```
 
-Function `MustCompile` is like `Compile` but panics if the expression cannot be parsed.
-It simplifies safe initialization of global variables holding compiled regular expressions.
+When using backticks ``(`)`` to make strings, backslashes `(\)` don't have any special meaning, and don't mark the beginning of special characters like tabs `\t` or
+newlines `\`n:
 
-It is convenient to write regular expressions as [raw string literals][raw-string-literals] enclosed by backticks.
-This avoids having to quote the backslashes.
+```go
+"\t\n" // regular string literal with 2 characters: a tab and a newline
+`\t\n`// raw string literal with 4 characters: two backslashes, a 't', and an 'n'
+```
+
+Because of this, using backticks is desirable to make regular expressions, because it means we don't need to escape backslashes:
+
+```go
+"\\" // string with a single backslash
+`\\` // string with 2 backslashes
+```
 
 The `regexp` package defines more than 40 functions and methods.
 We will demonstrate the use of a few methods below.
@@ -27,7 +36,7 @@ Please see the [API documentation][package-regexp] for details of these and othe
 Method `MatchString` reports whether a strings contains any match of a regular expression.
 
 ```go
-re = regexp.MustCompile(`[a-z]+\d*`)
+re,_ = regexp.Compile(`[a-z]+\d*`)
 b = re.MatchString("[a12]")       // => true
 b = re.MatchString("12abc34(ef)") // => true
 b = re.MatchString(" abc!")       // => true
@@ -37,7 +46,7 @@ b = re.MatchString("123 456")     // => false
 Method `FindString` returns a string holding the text of the leftmost match of the regular expression.
 
 ```go
-re = regexp.MustCompile(`[a-z]+\d*`)
+re,_ = regexp.Compile(`[a-z]+\d*`)
 s = re.FindString("[a12]")       // => "a12"
 s = re.FindString("12abc34(ef)") // => "abc34"
 s = re.FindString(" abc!")       // => "abc"
@@ -49,7 +58,7 @@ This can be used to identify the strings matching capturing groups.
 A return value of `nil` indicates no match.
 
 ```go 
-re = regexp.MustCompile(`[a-z]+(\d*)`)
+re,_ = regexp.Compile(`[a-z]+(\d*)`)
 sl = re.FindStringSubmatch("[a12]")       // => []string{"a12","12"}
 sl = re.FindStringSubmatch("12abc34(ef)") // => []string{"abc34","34"}
 sl = re.FindStringSubmatch(" abc!")       // => []string{"abc",""}
@@ -59,7 +68,7 @@ sl = re.FindStringSubmatch("123 456")     // => <nil>
 Method `re.ReplaceAllString(src,repl)` returns a copy of `src`, replacing matches of the regular expression `re` with the replacement string `repl`.
 
 ```go
-re = regexp.MustCompile(`[a-z]+\d*`)
+re,_ = regexp.Compile(`[a-z]+\d*`)
 s = re.ReplaceAllString("[a12]", "X")       // => "[X]"
 s = re.ReplaceAllString("12abc34(ef)", "X") // => "12X(X)"
 s = re.ReplaceAllString(" abc!", "X")       // => " X!"
@@ -71,7 +80,7 @@ The count `n` determines the maximal number of substrings to return.
 If `n<0`, the method returns all substrings.
 
 ```go
-re = regexp.MustCompile(`[a-z]+\d*`)
+re,_ = regexp.Compile(`[a-z]+\d*`)
 sl = re.Split("[a12]", -1)      // => []string{"[","]"}
 sl = re.Split("12abc34(ef)", 2) // => []string{"12","(ef)"}
 sl = re.Split(" abc!", -1)      // => []string{" ","!"}

exercises/concept/parsing-log-files/.docs/hints.md

@@ -16,7 +16,7 @@
 ## 3. Count the number of lines containing `password` in quoted text
 
 - You can make expression matching case sensitive by prefixing the regular expression with `(?i)`.
-This will set the `i` flag, see for example [yourbasic.org][yourbasic-i-flag].
+This will set the `i` flag.  See [this tutorial][yourbasic-i-flag].
 
 ## 4. Remove artifacts from log
 

exercises/concept/parsing-log-files/.docs/introduction.md

@@ -14,11 +14,20 @@ re, err = regexp.Compile(`a|b)+`)
 fmt.Println(re, err) // => <nil> error parsing regexp: unexpected ): `a|b)+`
 ```
 
-Function `MustCompile` is like `Compile` but panics if the expression cannot be parsed.
-It simplifies safe initialization of global variables holding compiled regular expressions.
+When using backticks ``(`)`` to make strings, backslashes `(\)` don't have any special meaning, and don't mark the beginning of special characters like tabs `\t` or
+newlines `\`n:
 
-It is convenient to write regular expressions as [raw string literals][raw-string-literals] enclosed by backticks.
-This avoids having to quote the backslashes.
+```go
+"\t\n" // regular string literal with 2 characters: a tab and a newline
+`\t\n`// raw string literal with 4 characters: two backslashes, a 't', and an 'n'
+```
+
+Because of this, using backticks is desirable to make regular expressions, because it means we don't need to escape backslashes:
+
+```go
+"\\" // string with a single backslash
+`\\` // string with 2 backslashes
+```
 
 The `regexp` package defines more than 40 functions and methods.
 We will demonstrate the use of a few methods below.
@@ -27,7 +36,7 @@ Please see the [API documentation][package-regexp] for details of these and othe
 Method `MatchString` reports whether a strings contains any match of a regular expression.
 
 ```go
-re = regexp.MustCompile(`[a-z]+\d*`)
+re,_ = regexp.Compile(`[a-z]+\d*`)
 b = re.MatchString("[a12]")       // => true
 b = re.MatchString("12abc34(ef)") // => true
 b = re.MatchString(" abc!")       // => true
@@ -37,7 +46,7 @@ b = re.MatchString("123 456")     // => false
 Method `FindString` returns a string holding the text of the leftmost match of the regular expression.
 
 ```go
-re = regexp.MustCompile(`[a-z]+\d*`)
+re,_ = regexp.Compile(`[a-z]+\d*`)
 s = re.FindString("[a12]")       // => "a12"
 s = re.FindString("12abc34(ef)") // => "abc34"
 s = re.FindString(" abc!")       // => "abc"
@@ -49,7 +58,7 @@ This can be used to identify the strings matching capturing groups.
 A return value of `nil` indicates no match.
 
 ```go 
-re = regexp.MustCompile(`[a-z]+(\d*)`)
+re,_ = regexp.Compile(`[a-z]+(\d*)`)
 sl = re.FindStringSubmatch("[a12]")       // => []string{"a12","12"}
 sl = re.FindStringSubmatch("12abc34(ef)") // => []string{"abc34","34"}
 sl = re.FindStringSubmatch(" abc!")       // => []string{"abc",""}
@@ -59,7 +68,7 @@ sl = re.FindStringSubmatch("123 456")     // => <nil>
 Method `re.ReplaceAllString(src,repl)` returns a copy of `src`, replacing matches of the regular expression `re` with the replacement string `repl`.
 
 ```go
-re = regexp.MustCompile(`[a-z]+\d*`)
+re,_ = regexp.Compile(`[a-z]+\d*`)
 s = re.ReplaceAllString("[a12]", "X")       // => "[X]"
 s = re.ReplaceAllString("12abc34(ef)", "X") // => "12X(X)"
 s = re.ReplaceAllString(" abc!", "X")       // => " X!"
@@ -71,13 +80,13 @@ The count `n` determines the maximal number of substrings to return.
 If `n<0`, the method returns all substrings.
 
 ```go
-re = regexp.MustCompile(`[a-z]+\d*`)
+re,_ = regexp.Compile(`[a-z]+\d*`)
 sl = re.Split("[a12]", -1)      // => []string{"[","]"}
 sl = re.Split("12abc34(ef)", 2) // => []string{"12","(ef)"}
 sl = re.Split(" abc!", -1)      // => []string{" ","!"}
 sl = re.Split("123 456", -1)    // => []string{"123 456"}
 ```
 
-[raw-string-literals]:[https://yourbasic.org/golang/regexp-cheat-sheet/#raw-strings]
+[raw-string-literals]: https://yourbasic.org/golang/regexp-cheat-sheet/#raw-strings
 [package-regexp]: https://pkg.go.dev/regexp
 [regexp-syntax]: https://pkg.go.dev/regexp/syntax

exercises/concept/parsing-log-files/.meta/exemplar.go

@@ -1,4 +1,4 @@
-package parsing_log_files
+package parsinglogfiles
 
 import (
 	"regexp"

exercises/concept/parsing-log-files/go.mod

@@ -1,3 +1,3 @@
-module parsing_log_files
+module parsinglogfiles
 
 go 1.16

exercises/concept/parsing-log-files/parsing_log_files.go

@@ -1,21 +1,21 @@
-package parsing_log_files
+package parsinglogfiles
 
 func IsValidLine(text string) bool {
-	panic("IsValidLine not implemented")
+	panic("Please implement the IsValidLine function")
 }
 
 func SplitLogLine(text string) []string {
-	panic("SplitLogLine not implemented")
+	panic("Please implement the SplitLogLine function")
 }
 
 func CountQuotedPasswords(lines []string) int {
-	panic("CountQuotedPasswords not implemented")
+	panic("Please implement the CountQuotedPasswords function")
 }
 
 func RemoveEndOfLineText(text string) string {
-	panic("RemoveEndOfLineText not implemented")
+	panic("Please implement the RemoveEndOfLineText function")
 }
 
 func TagWithUserName(lines []string) []string {
-	panic("TagWithUserName not implemented")
+	panic("Please implement the TagWithUserName function")
 }

exercises/concept/parsing-log-files/parsing_log_files_test.go

@@ -1,4 +1,4 @@
-package parsing_log_files
+package parsinglogfiles
 
 import "testing"