Conversion of Cats chapter

- Fix links etc to Typst style

Author: noelwelsh

src/pages/cats/conclusions.typ

@@ -1,21 +1,20 @@
-#import "../stdlib.typ": info, warning, solution
+#import "../stdlib.typ": href
 == Conclusions
 
-
 We have also seen the general patterns in Cats type classes:
 
  - The type classes themselves are generic traits
-   in the [`cats`][cats.package] package.
+   in the `cats` package.
 
  - Each type class has a companion object with,
    an `apply` method for materializing instances,
-   one or more _construction_ methods for creating instances,
+   one or more construction methods for creating instances,
    and a collection of other relevant helper methods.
 
- - Many type classes have _syntax_
-   provided via the [`cats.syntax`][cats.syntax] package.
+ - Many type classes have extension methods
+   provided via the `cats.syntax` package.
 
-In the remaining chapters of Part {#sec:part:type-classes}
+In the remaining chapters of @sec:part:type-classes
 we will look at several broad and powerful type classes---`Semigroup`,
 `Monoid`, `Functor`, `Monad`, `Semigroupal`, `Applicative`, `Traverse`, and more.
 In each case we will learn what functionality the type class provides,

src/pages/cats/equal.typ

@@ -1,19 +1,16 @@
-#import "../stdlib.typ": info, warning, solution
+#import "../stdlib.typ": info, warning, solution, href
 == Example: Eq
 
 
 We will finish off this chapter by looking at another useful type class:
-[`cats.Eq`][cats.kernel.Eq].
+#href("http://typelevel.org/cats/api/cats/kernel/Eq.html")[`cats.Eq`].
 `Eq` is designed to support _type-safe equality_
 and address annoyances using Scala's built-in `==` operator.
 
 Almost every Scala developer has written code like this before:
 
-```scala
+```scala mdoc:fail
 List(1, 2, 3).map(Option(_)).filter(item => item == 1)
-// warning: Option[Int] and Int are unrelated: they will most likely never compare equal
-// res: List[Option[Int]] = List()
-
 ```
 
 Ok, many of you won't have made such a simple mistake as this,
@@ -26,12 +23,11 @@ should have compared `item` to `Some(1)` instead of `1`.
 However, it's not technically a type error because
 `==` works for any pair of objects, no matter what types we compare.
 `Eq` is designed to add some type safety to equality checks
-and work around this problem.
+and work around this problem.#footnote[Scala 3 has it's own solution to this problem, called #href("https://docs.scala-lang.org/scala3/reference/contextual/multiversal-equality.html")[multiversal equality]. It also uses a type class, in this case called `CanEqual`. With the correct imports or compiler flags we can get the compiler to complain if we try to perform an equality check that doesn't make sense. So in practice we don't need `Eq` any more. However it's a simple type class to work with and makes a good introduction to using Cats.]
 
 
 === Equality, Liberty, and Fraternity
 
-
 We can use `Eq` to define type-safe equality
 between instances of any given type:
 
@@ -44,7 +40,7 @@ trait Eq[A] {
 }
 ```
 
-The interface syntax, defined in [`cats.syntax.eq`][cats.syntax.eq],
+The interface syntax, defined in #href("https://www.javadoc.io/doc/org.typelevel/cats-docs_3/latest/cats/syntax/EqSyntax.html")[`cats.syntax.eq`],
 provides two methods for performing equality checks
 provided there is an instance `Eq[A]` in scope:
 
@@ -82,13 +78,15 @@ we get a compile error:
 eqInt.eqv(123, "234")
 ```
 
-We can also import the interface syntax in [`cats.syntax.eq`][cats.syntax.eq]
+We can also import the interface syntax
 to use the `===` and `=!=` methods:
 
 ```scala mdoc:silent
 import cats.syntax.all.* // for === and =!=
 ```
 
+Now the syntax methods are available.
+
 ```scala mdoc
 123 === 123
 123 =!= 234
@@ -126,7 +124,7 @@ the `Option.apply` and `Option.empty` methods from the standard library:
 Option(1) === Option.empty[Int]
 ```
 
-or using special syntax from [`cats.syntax.option`][cats.syntax.option]:
+or using special syntax from #href("https://www.javadoc.io/doc/org.typelevel/cats-docs_3/latest/cats/syntax/OptionSyntax.html")[`cats.syntax.option`]:
 
 ```scala mdoc
 1.some === none[Int]

src/pages/cats/index.typ

@@ -1,16 +1,13 @@
-#import "../stdlib.typ": info, warning, solution
-= Using Cats 
-<sec:cats>
+#import "../stdlib.typ": info, warning, solution, chapter, href, exercise
+#chapter[Using Cats] <sec:cats>
 
-
-In this Chapter we'll learn how to use the #link("https://typelevel.org/cats")[Cats] library.
+In this Chapter we'll learn how to use the #href("https://typelevel.org/cats")[Cats] library.
 Cats provides two main things: type classes and their instances, and some useful data structures.
 Our focus will mostly be on the type classes, though we will touch on the data structures where appropriate.
 
 
 == Quick Start
 
-
 The easiest, and recommended, way to use Cats is to add the following imports:
 
 ```scala mdoc:silent
@@ -35,7 +32,7 @@ import cats.data.*
 
 
 Let's now see how we work with Cats, 
-using [`cats.Show`][cats.Show] as an example.
+using #href("http://typelevel.org/cats/api/cats/Show.html")[`cats.Show`] as an example.
 
 `Show` is Cats' equivalent of
 the `Display` type class we defined in @sec:type-classes:display.
@@ -52,7 +49,7 @@ trait Show[A] {
 ```
 
 The easiest way to use `Show` is with the wildcard import above.
-However, we can also import `Show` directly from the [cats][cats.package] package:
+However, we can also import `Show` directly from the `cats` package if we want:
 
 ```scala mdoc:silent
 import cats.Show
@@ -80,19 +77,21 @@ In the case of `Show`, an extension method `show` is defined.
 ```
 
 If, for some reason, we wanted just the syntax for `show`,
-we could import [`cats.syntax.show`][cats.syntax.show].
+we could import `cats.syntax.show`.
 
 ```scala mdoc:silent
 import cats.syntax.show.* // for show
 ```
 
 
 === Defining Custom Instances 
-<defining-custom-instances>
-
+<sec:cats:defining-custom-instances>
 
-We can define an instance of `Show`
-simply by implementing the trait for a given type:
+As we learned in @sec:type-classes,
+we can define an instance of `Show`
+by implementing a given instance of the trait
+for a specific type.
+Let's implement `Show` for `java.util.Date`.
 
 ```scala mdoc:silent
 import java.util.Date
@@ -101,6 +100,9 @@ given dateShow: Show[Date] with
   def show(date: Date): String =
     s"${date.getTime}ms since the epoch."
 ```
+
+It works as expected.
+
 ```scala mdoc
 new Date().show
 ```
@@ -141,10 +143,9 @@ for constructing instances, either from scratch
 or by transforming existing instances for other types.
 
 
-==== Exercise: Cat Show
-
+#exercise[Cat Show]
 
-Re-implement the `Cat` application from @sec:type-classes:cat
+In this exercise we'll re-implement the `Cat` application from @sec:type-classes:cat
 using `Show` instead of `Display`.
 
 Using this data type to represent a well-known type of furry animal:

src/pages/fps.typ

@@ -129,6 +129,7 @@
 // Cats
 #include  "cats/index.typ"
 #include  "cats/equal.typ"
+#include  "cats/conclusions.typ"
 // Monoid
 #include  "monoids/index.typ"
 #include  "monoids/cats.typ"

src/pages/parts/part2.typ

@@ -1,4 +1,4 @@
-#import "../stdlib.typ": part
+#import "../stdlib.typ": part, href
 
 #part[Type Classes] <sec:part:type-classes>
 
@@ -10,6 +10,6 @@ and as conceptual models that can drive program design.
 In this part we'll be looking more at their use for day-to-day programming,
 while the case studies will focus on their role in design.
 
-In @sec:cats we introduce the #link("https://typelevel.org/cats")[Cats] library.
+In @sec:cats we introduce the #href("https://typelevel.org/cats")[Cats] library.
 Cats provides implementation of the type classes we're interested in,
 and so it saves a lot of time and typing to use it.