From 6457e887982dc300d6aee12200d23c041024a2c5 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Wed, 17 Jan 2018 23:25:41 +1100 Subject: [PATCH] Add the first of the hyperlink docs --- docs/HyperlinkedInformation/Diffs.md | 24 ++++++++++++++++++++++++ docs/HyperlinkedInformation/README.md | 4 ++++ 2 files changed, 28 insertions(+) create mode 100644 docs/HyperlinkedInformation/Diffs.md create mode 100644 docs/HyperlinkedInformation/README.md diff --git a/docs/HyperlinkedInformation/Diffs.md b/docs/HyperlinkedInformation/Diffs.md new file mode 100644 index 0000000..3c2dcf3 --- /dev/null +++ b/docs/HyperlinkedInformation/Diffs.md @@ -0,0 +1,24 @@ +## Only Before and Only After + +This document briefly explains what you are seeing in those mysterious sections +labelled "Only Before" and "Only After". Enlightenment is nigh. + +`re-frame-trace` displays important values like, for example, what's +currently in `app-db` or in a given subscription. While current values are good, +you are often more interested to know how a value has been changed by the epoch. +The value might start of as, say, `X` (before the event happened) but +ended up as `Y`. How are `X` and `Y` different, you wonder? +What got added or removed? What was modified? + +So, how then to display changes in a way that's easy to grok? I'm glad you asked. +`re-frame-trace` chooses to use the output of `(clojure.data/diff X Y)`. Remember +`X` is the before (original) value, and `Y` is the final value. + +By [looking at the docs](https://clojuredocs.org/clojure.data/diff) on `diff`, you'll see +that it returns a triple of values. `re-frame-trace` +displays the first two elements of this triple as "only before" and "only after" respectively. +The 3rd element is not very interesting because it tells us what hasn't changed, so it isn't shown. + +To correctly interpret "Only Before" and "Only after", you'll need to spend a bit +of time properly familiarising yourself with how `clojure.data/diff` works, but +it will be a worthwhile investment. diff --git a/docs/HyperlinkedInformation/README.md b/docs/HyperlinkedInformation/README.md new file mode 100644 index 0000000..28b5c98 --- /dev/null +++ b/docs/HyperlinkedInformation/README.md @@ -0,0 +1,4 @@ +This directory holds help documents accessed directly from the UI. + +The `re-frame-trace` UI contains +various (helpful) hyperlinks which point to documents kept within this directory.