[doc] Misc improvements

examples.cljc

@@ -272,17 +272,17 @@
    ;; Do option validation and other prep here, i.e. try to keep
    ;; expensive work outside handler function when possible!
 
-   (let [handler-fn ; Fn of exactly 2 arities
+   (let [handler-fn ; Fn of exactly 2 arities (1 and 0)
          (fn a-handler:my-fancy-handler ; Note fn naming convention
 
-           ([] ; Arity-0 called when stopping the handler
-            ;; Flush buffers, close files, etc. May just noop.
-            ;; Return value is ignored.
-            )
-
            ([signal] ; Arity-1 called when handling a signal
             ;; Do something useful with the given signal (write to
             ;; console/file/queue/db, etc.). Return value is ignored.
+            )
+
+           ([] ; Arity-0 called when stopping the handler
+            ;; Flush buffers, close files, etc. May just noop.
+            ;; Return value is ignored.
             ))]
 
      ;; (Advanced, optional) You can use metadata to provide default

main/src/taoensso/telemere/files.clj

@@ -272,14 +272,14 @@
     - Takes a Telemere signal (map).
     - Writes (appends) the signal as a string to file specified by `path`.
 
-  Depending on options, archives may be maintained:
+  Can output signals as human or machine-readable (edn, JSON) strings.
+
+  Depending on options, archive file/s may also be maintained:
     - `logs/app.log.n.gz`             (for     nil `:interval`, non-nil `:max-file-size`)
     - `logs/app.log-YYYY-MM-DDd.n.gz` (for non-nil `:interval`) ; d=daily/w=weekly/m=monthly
 
-  Can output signals as human or machine-readable (edn, JSON) strings.
-
   Example files with default options:
-    `/logs/telemere.log`                  ; Current file
+    `/logs/telemere.log`                  ; Current file (newest entries)
     `/logs/telemere.log-2020-01-01m.1.gz` ; Archive for Jan 2020, part 1 (newest entries)
     ...
     `/logs/telemere.log-2020-01-01m.8.gz` ; Archive for Jan 2020, part 8 (oldest entries)

wiki/1-Getting-started.md

@@ -69,7 +69,7 @@ Its name is a combination of _telemetry_ and _telomere_:
 
 > *Telemetry* derives from the Greek *tele* (remote) and *metron* (measure). It refers to the collection of *in situ* (in position) data, for transmission to other systems for monitoring/analysis. *Logs* are the most common form of software telemetry. So think of telemetry as the *superset of logging-like activities* that help monitor and understand (software) systems.
 
-> *Telomere* derives from the Greek *télos* (end) and *méros* (part). It refers to a genetic feature commonly found at the end of linear chromosomes that helps to protect chromosome integrity.
+> *Telomere* derives from the Greek *télos* (end) and *méros* (part). It refers to a genetic feature commonly found at the end of linear chromosomes that helps to protect chromosome integrity (think biological checksum).
 
 # Setup
 

wiki/3-Config.md

@@ -101,6 +101,13 @@ To do this:
 
 Aside from configuring the exporters (2), Telemere's OpenTelemetry interop **does not require** any use of or familiarity with the OpenTelemetry Java API or concepts. Just use Telemere as you normally would, and the handler (3) will automatically emit detailed log and trace data to your configured exporters (2).
 
+Verify successful interop with [`check-interop`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#check-interop):
+
+```clojure
+(check-interop) ; =>
+{:open-telemetry {:present? true, :use-tracer? true, :viable-tracer? true}}
+```
+
 ## Tufte
 
 > [Tufte](https://www.taoensso.com/tufte) is a simple performance monitoring library for Clojure/Script by the author of Telemere.

wiki/4-Handlers.md

@@ -1,10 +1,14 @@
 Telemere's signal handlers are just **plain functions** that take a signal (map) to **do something with them** (analyse them, write them to console/file/queue/db/etc.).
 
-Here's a simple handler: `(fn [signal] (println signal))`.
+Here's a minimal handler: `(fn [signal] (println signal))`.
 
 A second 0-arg arity will be called when stopping the handler. This is handy for stateful handlers or handlers that need to release resources, e.g.:
 
-`(fn my-handler ([] (my-stop-code)) ([signal] (println signal))`
+```
+(fn my-handler
+  ([signal] (println signal)
+  ([] (my-stop-code)))
+```
 
 Telemere includes a number of signal handlers out-the-box, and more may be available via the [community](./8-Community#handlers-and-tools).
 
@@ -47,7 +51,7 @@ Handler dispatch opts includes dispatch priority (determines order in which hand
 
 See [`help:handler-dispatch-options`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options) for full info, and [`default-handler-dispatch-opts`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#default-handler-dispatch-opts) for defaults.
 
-Note that handler middleware in particular is an often overlooked but powerful feature, allowing you to arbitrarily transform and/or filter every [signal map](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-content) before it is given to each handler.
+Note that handler middleware in particular is an easily overlooked but powerful feature, allowing you to arbitrarily transform and/or filter every [signal map](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-content) before it is given to each handler.
 
 ## Handler-specific opts
 
@@ -181,9 +185,9 @@ Writing your own signal handlers for Telemere is straightforward, and a reasonab
 - Handlers just plain Clojure/Script fns of 2 arities:
 
 ```clojure
-(defn my-basic-handler
-  ([])                        ; Arity-0 called when stopping the handler
+(defn my-handler
   ([signal] (println signal)) ; Arity-1 called when handling a signal
+  ([] (my-stop-code))         ; Arity-0 called when stopping the handler
   )
 ```
 
@@ -211,17 +215,17 @@ If you're making a customizable handler for use by others, it's often handy to d
    ;; Do option validation and other prep here, i.e. try to keep
    ;; expensive work outside handler function when possible!
 
-   (let [handler-fn ; Fn of exactly 2 arities
+   (let [handler-fn ; Fn of exactly 2 arities (1 and 0)
          (fn a-handler:my-fancy-handler ; Note fn naming convention
 
-           ([] ; Arity-0 called when stopping the handler
-            ;; Flush buffers, close files, etc. May just noop.
-            ;; Return value is ignored.
-            )
-
            ([signal] ; Arity-1 called when handling a signal
             ;; Do something useful with the given signal (write to
             ;; console/file/queue/db, etc.). Return value is ignored.
+            )
+
+           ([] ; Arity-0 called when stopping the handler
+            ;; Flush buffers, close files, etc. May just noop.
+            ;; Return value is ignored.
             ))]
 
      ;; (Advanced, optional) You can use metadata to provide default

wiki/6-FAQ.md

@@ -26,7 +26,7 @@ That eventually grew into Telemere. And I'm happy enough with the result that I
 
 I will **continue to maintain and support** Timbre for users that are happy with it, though I've also tried to make [migration](./5-Migrating#from-timbre) as easy as possible.
 
-Over time, I also intend to back-port many backwards-compatible improvements from Telemere to Timbre. For one, Telemere's core was actually written as a library that will eventually be used by Telemere, Timbre, and also [Tufte](https://taoensso.com/tufte).
+Over time, I also intend to back-port many backwards-compatible improvements from Telemere to Timbre. For one, Telemere's core was actually written as a library that can eventually be used by Telemere, Timbre, and also [Tufte](https://taoensso.com/tufte).
 
 This will eventually ease long-term maintenance, increase reliability, and help provide unified capabilities across all 3.
 
@@ -60,7 +60,7 @@ They're focused on complementary things. When both are in use:
 
 > [Babashka](https://github.com/babashka/babashka) is a native Clojure interpreter for scripting with fast startup.
 
-**No**, not currently - though support should be possible with a little work. The current bottleneck is a dependency on [Encore](https://github.com/taoensso/encore), though that could actually be removed (also offering benefits re: library size).
+**No**, not currently - though support should be possible with a little work. The current bottleneck is a dependency on [Encore](https://github.com/taoensso/encore), which uses some classes not available in Babashka. With some work it should be possible to remove the dependency, and so also reduce library size.
 
 If there's interest in this, please [upvote](https://github.com/taoensso/roadmap/issues/22) on my open source roadmap.
 

wiki/7-Tips.md

@@ -94,12 +94,15 @@ Consider the [differences](https://www.youtube.com/watch?v=oyLBGkS5ICk) between
   
   So for `n` randomly sampled signals matching some criteria, you'd have seen an estimated `Σ(1.0/sample-rate_i)` such signals _without_ sampling, etc.
   
-- Middleware can return any type, but it's best to return only `nil` or a map.
+- Middleware can return any type, but it's best to return only `nil` or a map. This ensures maximum compatibility with community middleware, handlers, and tools.
+  
 - Middleware can be used to **filter signals** by returning `nil`.
-- Middleware can be used to **split signals**.
+- Middleware can be used to **split signals**:
   
   Your middleware can *call signal creators* like any other code. Return `nil` after to filter the source signal. Just be aware that new signals will re-enter your handler queue/s as would any other signal - and so may be subject to handling delay and normal handler queue back-pressure.
   
+  See also the [`dispatch-signal!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#dispatch-signal!) util.
+  
 - Levels can be **arbitrary integers**.
   
   See the value of [`level-aliases`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#level-aliases) to see how the standard keywords (`:info`, `:warn`, etc.) map to integers.