From 53b715faccb8dd1ac411f0fd61a7b9e1c17ec166 Mon Sep 17 00:00:00 2001
From: John Practicalli <250870+practicalli-john@users.noreply.github.com>
Date: Fri, 22 Sep 2023 18:55:12 +0100
Subject: [PATCH] intro: additional updates to clojure in 15

---
 docs/introduction/clojure-in-15-minutes.md | 78 ++++++++++++++--------
 1 file changed, 49 insertions(+), 29 deletions(-)

diff --git a/docs/introduction/clojure-in-15-minutes.md b/docs/introduction/clojure-in-15-minutes.md
index b5048a3bd..f89cdf392 100644
--- a/docs/introduction/clojure-in-15-minutes.md
+++ b/docs/introduction/clojure-in-15-minutes.md
@@ -65,11 +65,11 @@ A company name or community repository name is often used making the namespace u
 The `str` function creates a new string from all the arguments passed
 
 !!! EXAMPLE "Combine strings into a single string value"
-```clojure
-(str "Hello" " " "World")
-```
-`"Hello World"` is returned from evaluating the expression.
+    ```clojure
+    (str "Hello" " " "World")
+    ```
 
+`"Hello World"` is returned from evaluating the expression.
 
 !!! HINT "clojure.string library for manipulating strings"
     `clojure.string` library functions manipulate values and return string values (other clojure.core functions my return characters as results, e.g. `map`)
@@ -106,28 +106,49 @@ Maintain precision for calculations using a Ratio type in Clojure
 `22/7` is returned as the value, rather than a floating point value (double) which may loose some precision due to rounding.
 
 
-```clojure
-(+ 1 (- 3 2)) ; = 1 + (3 - 2) => 2
-```
+### Equality
 
-Equality is =
+Equality is `=`
 
-```clojure
-(= 1 1) ; => true
-(= 2 1) ; => false
-```
+!!! EXAMPLE "Equal values return a boolean true"
+    ```clojure
+    (= 1 1) ; => true
+    ```
+
+!!! EXAMPLE "Unequals values return a boolean false"
+    ```clojure
+    (= 2 1) ; => false
+    ```
 
-`true` and `false` are Boolean values
+`true` and `false` are Boolean values and can be used literally in Clojure.
 
- ```clojure
-(true? true) ; => true
-(not true) ; => false
-(not= true false) ; => true
-(true? (complement true?)) ; => false
- ```
 
+### Predicates
 
-### Collections & Sequences
+A predicate is a function that returns a boolean `true` or `false` value and by convention the function name ends in `?`, e.g. `true?`, `false?`, `seq?`, `even?`, `uuid?`.
+
+`and` & `or` functions can be used to chain the results of predicates together for more interesting conditional tests.
+
+!!! EXAMPLE "All predicates are true, returning true"
+    ```clojure
+    (and (true? true) (not false)) ; => true
+    ```
+
+!!! EXAMPLE "One of the predicates or values is true"
+    ```clojure
+    (or nil (not= true false) (true? (complement true?)) ) ; => true
+    ```
+
+!!! HINT "Truthy and Falsy values in Clojure"
+    `false` boolean value and `nil` value are considered false in Clojure.
+
+    All other values are consider true.
+
+
+[:fontawesome-solid-book-open: Clojure Standard Library Predicate Functions](https://practical.li/clojure/reference/standard-library/predicate-functions/){.md-button} 
+
+
+## Collections & Sequences
 
 The most common data collections in Clojure:
 
@@ -140,16 +161,15 @@ A list `()` is evaluated as a function call. The first element of the list the n
 
 The `'` quote function informs the Clojure reader to treat the list as data only.
 
-```clojure
-'(1 2 3)
-```
-
-Lists and vectors are collections
+!!! EXAMPLE "A quoted list is treated as data"
+    ```clojure
+    '(1 2 3) ; => (1 2 3)
+    ```
 
-```clojure
-(coll? '(1 2 3)) ; => true
-(coll? [1 2 3]) ; => true
-```
+!!! EXAMPLE "Lists and vectors are collections"
+    ```clojure
+    (and (coll? '(1 2 3)) (coll? [1 2 3])) ; => true
+    ```
 
 Only lists are sequences