Edits to Monoids chapter

Author: noelwelsh

src/pages/fps.typ

@@ -11,7 +11,7 @@
     paper: "us-trade"
 )
 
-#set text(font: "EB Garamond 12", size: 12pt)
+#set text(font: "EB Garamond", size: 12pt)
 
 #show raw.where(block: true): set block(fill: rgb("F7F7F7"), inset: 8pt, width: 100%)
 #show raw.where(block: true): set text(size: 8pt)

src/pages/monoids/applications.typ

@@ -40,7 +40,7 @@ For example,
 one machine may receive an update that other machines did not receive.
 We would like to reconcile these different views,
 so every machine has the same data if no more updates arrive.
-This is called _eventual consistency_.
+This is called *eventual consistency*.
 
 A particular class of data types support this reconciliation.
 These data types are called conflict-free replicated data types (CRDTs).
@@ -49,6 +49,7 @@ with a result that captures all the information in both instances.
 This operation relies on having a monoid instance.
 We explore this idea further in the CRDT case study.
 
+
 === Monoids in the Small
 
 

src/pages/monoids/cats.typ

@@ -28,10 +28,7 @@ or just
 import cats.*
 ```
 
-#info[
-==== Cats Kernel? {-}
-
-
+#info(title: "Cats Kernel?")[
 Cats Kernel is a subproject of Cats
 providing a small set of typeclasses
 for libraries that don't require the full Cats toolbox.
@@ -61,29 +58,28 @@ For example, if we want the monoid instance for `String`,
 and we have the correct given instances in scope,
 we can write the following:
 
-```scala mdoc:silent
-import cats.Monoid
-```
-
 ```scala mdoc
+import cats.Monoid
 Monoid[String].combine("Hi ", "there")
 Monoid[String].empty
 ```
 
-which is equivalent to:
+which is equivalent to
 
 ```scala mdoc
 Monoid.apply[String].combine("Hi ", "there")
 Monoid.apply[String].empty
 ```
 
 As we know, `Monoid` extends `Semigroup`.
-If we don't need `empty` we can equivalently write:
+If we don't need `empty` we can instead write
 
 ```scala mdoc:silent
 import cats.Semigroup
 ```
 
+and then summon instances of `Semigroup` in the usual way:
+
 ```scala mdoc
 Semigroup[String].combine("Hi ", "there")
 ```
@@ -106,10 +102,12 @@ we access the syntax by importing from #href("http://typelevel.org/cats/api/cats
 import cats.syntax.semigroup.* // for |+|
 ```
 
+Now we can use `|+|` in place of calling `combine`.
+
 ```scala mdoc
 val stringResult = "Hi " |+| "there" |+| Monoid[String].empty
 
-val intResult = 1 |+| 2 |+| Monoid[Int].empty
+val intResult = 1 |+| 2
 ```
 
 As always,

src/pages/monoids/index.typ

@@ -8,9 +8,6 @@ There are instances for `Ints`, `Strings`, `Lists`, `Options`, and many more.
 Let's start by looking at a few simple types and operations
 to see what common principles we can extract.
 
-==== Integer addition
-
-
 Addition of `Ints` is a binary operation that is _closed_,
 meaning that adding two `Ints` always produces another `Int`:
 
@@ -28,8 +25,8 @@ that `a + 0 == 0 + a == a` for any `Int` `a`:
 ```
 
 There are also other properties of addition.
-For instance, it doesn't matter in what order we add elements
-because we always get the same result.
+For instance, it doesn't matter in where we place brackets when we add elements,
+as we always get the same result.
 This is a property known as _associativity_:
 
 ```scala mdoc
@@ -39,9 +36,6 @@ This is a property known as _associativity_:
 ```
 
 
-==== Integer multiplication
-
-
 The same properties for addition also apply for multiplication,
 provided we use `1` as the identity instead of `0`:
 
@@ -60,9 +54,6 @@ Multiplication, like addition, is associative:
 ```
 
 
-==== String and sequence concatenation
-
-
 We can also add `Strings`,
 using string concatenation as our binary operator:
 
@@ -146,11 +137,12 @@ is not a monoid because subtraction is not associative:
 
 In practice we only need to think about laws
 when we are writing our own `Monoid` instances.
-Unlawful instances are dangerous because
-they can yield unpredictable results
+Unlawful instances are dangerous,
+not because using them can cause us to end up in jail,
+but because they can yield unpredictable results
 when used with the rest of Cats' machinery.
 Most of the time we can rely on the instances provided by Cats
-and assume the library authors know what they're doing.
+and assume the library authors knew what they were doing.
 
 
 == Definition of a Semigroup
@@ -165,6 +157,7 @@ sequence concatenation and integer addition are monoids.
 However, if we restrict ourselves
 to non-empty sequences and positive integers,
 we are no longer able to define a sensible `empty` element.
+As a concrete example,
 Cats has a #href("http://typelevel.org/cats/api/cats/data/NonEmptyList.html")[`NonEmptyList`] data type
 that has an implementation of `Semigroup` but no implementation of `Monoid`.
 
@@ -214,7 +207,7 @@ object Monoid {
 
 #solution[
 There are at least four monoids for `Boolean`!
-First, we have _and_ with operator `&&` and identity `true`:
+First, we have *and* with operator `&&` and identity `true`:
 
 ```scala mdoc:silent
 given booleanAndMonoid: Monoid[Boolean] with {
@@ -223,7 +216,7 @@ given booleanAndMonoid: Monoid[Boolean] with {
 }
 ```
 
-Second, we have _or_ with operator `||` and identity `false`:
+Second, we have *or* with operator `||` and identity `false`:
 
 ```scala mdoc:silent
 given booleanOrMonoid: Monoid[Boolean] with {
@@ -232,7 +225,7 @@ given booleanOrMonoid: Monoid[Boolean] with {
 }
 ```
 
-Third, we have _exclusive or_ with identity `false`:
+Third, we have *exclusive or* with identity `false`:
 
 ```scala mdoc:silent
 given booleanEitherMonoid: Monoid[Boolean] with {
@@ -243,7 +236,7 @@ given booleanEitherMonoid: Monoid[Boolean] with {
 }
 ```
 
-Finally, we have _exclusive nor_ (the negation of exclusive or)
+Finally, we have *exclusive nor* (the negation of exclusive or)
 with identity `true`:
 
 ```scala mdoc:silent
@@ -302,7 +295,7 @@ given setIntersectionSemigroup[A]: Semigroup[Set[A]] with {
 ```
 
 Set complement and set difference are not associative,
-so they cannot be considered for either monoids or semigroups.
+so they cannot be either monoids or semigroups.
 However, symmetric difference (the union less the intersection)
 does form a monoid with the empty set:
 

src/pages/monoids/summary.typ

@@ -64,6 +64,6 @@ addAll(List(None, Some(1), Some(2)))
 They're easy to understand and simple to use.
 However, they're just the tip of the iceberg
 in terms of the abstractions Cats enables us to make.
-In the next chapter we'll look at _functors_,
+In the next chapter we'll look at *functors*,
 the type class personification of the beloved `map` method.
 That's where the fun really begins!