[doc] Rename "signal filters" -> "call filters", etc.

The new terminology hopefully makes the distinction clearer
between call filters and handler filters, etc.

main/resources/signal-docstrings/signal-content.txt

@@ -19,12 +19,12 @@ Default signal keys:
 `:run-nsecs` --- ?int nanosecs runtime of   `:run` ?form
 `:end-inst` ---- Platform ?instant [1] when `:run` ?form completed
 
-`:ctx` --------- ?val of `*ctx*` (arb app-level state) when signal was created
 `:parent` ------ ?{:keys [id uid]} of parent signal, present in nested signals when tracing
 `:root` -------- ?{:keys [id uid]} of root   signal, present in nested signals when tracing
+`:ctx` --------- ?val of `*ctx*` (arb app-level state) when signal was created
 
-`:ns` ---------- ?str namespace of signal creator callsite
+`:ns` ---------- ?str namespace of signal callsite
-`:coords` ------ ?[line column] of signal creator callsite
+`:coords` ------ ?[line column] of signal callsite
 
 `:host` -------- (Clj only) {:keys [name ip]}       info for network host
 `:thread` ------ (Clj only) {:keys [name id group]} info for thread that created signal

main/resources/signal-docstrings/signal-options.txt

@@ -1,5 +1,5 @@
 Signal options are provided as a map with COMPILE-TIME keys.
-All options are available for all signal creators:
+All options are available for all signal creator calls:
 
 `:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <[1]>}
 `:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
@@ -21,8 +21,8 @@ All options are available for all signal creators:
 `:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal, as per `with-ctx`
 `:ctx+` -------- Custom ?val to update   auto (dynamic `*ctx*`) in signal, as per `with-ctx+`
 
-`:ns` ---------- Custom ?str namespace to override auto signal creator callsite
+`:ns` ---------- Custom ?str namespace to override auto signal callsite info
-`:coords` ------ Custom ?[line column] to override auto signal creator callsite
+`:coords` ------ Custom ?[line column] to override auto signal callsite info
 
 `:elidable?` --- Should signal be subject to compile-time elision? (Default: true)
 `:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all)

wiki/1-Getting-started.md

@@ -167,16 +167,18 @@ Both have several options, see their docstrings (links above) for details.
 
 A signal will be provided to a handler iff ALL of the following are true:
 
-- 1. Signal **creation** is allowed by **signal filters**:
+- 1. Signal **call filters** pass:
 	- a. Compile time: sample rate, kind, ns, id, level, when form, rate limit
 	- b. Runtime: sample rate, kind, ns, id, level, when form, rate limit
 	  
-- 2. Signal **handling** is allowed by **handler filters**:
+- 2. Signal **handler filters** pass:
 	- a. Compile time: not applicable
 	- b. Runtime: sample rate, kind, ns, id, level, when fn, rate limit
 	  
-- 3. **Signal middleware** `(fn [signal]) => ?modified-signal` does not return nil
+- 3. **Call middleware** `(fn [signal]) => ?modified-signal` returns non-nil
-- 4. **Handler middleware** `(fn [signal]) => ?modified-signal` does not return nil
+- 4. **Handler middleware** `(fn [signal]) => ?modified-signal` returns non-nil
+
+> Middleware provides a flexible way to modify and/or filter signals by arbitrary signal data/content conditions (return nil to skip).
 
 Quick examples of some basic filtering:
 

wiki/2-Architecture.md

@@ -16,4 +16,4 @@ This flow is visualized below:
 <img src="https://raw.githubusercontent.com/taoensso/telemere/master/imgs/signal-flow.svg" alt="Telemere signal flowchart" width="640"/>
 
 - `A/sync queue` semantics are specified via [handler dispatch options](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options).
-- The shared **signal middleware cache** is super useful when doing signal transformations that are expensive and/or involve side effects (like syncing with another service/db to get a unique tx id, etc.).
+- The shared **call middleware cache** is super useful when doing signal transformations that are expensive and/or involve side effects (like syncing with another service/db to get a unique tx id, etc.).

wiki/3-Config.md

@@ -4,16 +4,18 @@ See below for config by topic-
 
 A signal will be provided to a handler iff ALL of the following are true:
 
-- 1. Signal **creation** is allowed by **signal filters**:
+- 1. Signal **call filters** pass:
 	- a. Compile time: sample rate, kind, ns, id, level, when form, rate limit
 	- b. Runtime: sample rate, kind, ns, id, level, when form, rate limit
 	  
-- 2. Signal **handling** is allowed by **handler filters**:
+- 2. Signal **handler filters** pass:
 	- a. Compile time: not applicable
 	- b. Runtime: sample rate, kind, ns, id, level, when fn, rate limit
 	  
-- 3. **Signal middleware** `(fn [signal]) => ?modified-signal` does not return nil
+- 3. **Call middleware** `(fn [signal]) => ?modified-signal` returns non-nil
-- 4. **Handler middleware** `(fn [signal]) => ?modified-signal` does not return nil
+- 4. **Handler middleware** `(fn [signal]) => ?modified-signal` returns non-nil
+
+> Middleware provides a flexible way to modify and/or filter signals by arbitrary signal data/content conditions (return nil to skip).
 
 See [`help:filters`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:filters) for more about filtering.
 
@@ -126,7 +128,7 @@ Telemere and Tufte work great together:
 
 ## Truss
 
-> [Truss](https://www.taoensso.com/truss) is an assertions micro-library for Clojure/Script by the author of Telemere.
+> [Truss](https://www.taoensso.com/truss) is a micro toolkit for Clojure/Script errors by the author of Telemere.
 
 Telemere can easily incorporate Truss assertion failure information in its signals, just like any other (error) data.
 
@@ -135,3 +137,5 @@ The [`catch->error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/tao
 ```clojure
 (t/catch->error! <form-with-truss-assertion/s>)
 ```
+
+Telemere also uses [Truss contextual exceptions](https://cljdoc.org/d/com.taoensso/truss/CURRENT/api/taoensso.truss#ex-info) when relevant.

wiki/7-Tips.md

@@ -80,9 +80,9 @@ Consider the [differences](https://www.youtube.com/watch?v=oyLBGkS5ICk) between
   
   This way you can see all your ids in one place, and precise info on when ids were added/removed/changed.
   
-- Use **signal middleware** to your advantage.
+- Use **signal call middleware** to your advantage.
   
-  The result of signal middleware is cached and *shared between all handlers* making it an efficient place to transform signals. For this reason - prefer signal middleware to handler middleware when possible/convenient.
+  The result of call middleware is cached and *shared between all handlers* making it an efficient place to transform signals. For this reason - prefer signal middleware to handler middleware when possible/convenient.
   
 - Signal and handler **sampling is multiplicative**.