From 3a2c81192ef21fa892325ee0add9bec9d2640c17 Mon Sep 17 00:00:00 2001
From: Jeremy Ruston <jeremy@jermolene.com>
Date: Mon, 7 Apr 2025 10:42:37 +0100
Subject: [PATCH] Docs for the inspect-filter macro

---
 .../tiddlers/filters/inspect Operator.tid     |  9 -------
 .../tiddlers/macros/InspectFilterMacro.tid    | 21 +++++++++++++++
 .../inspect-filter Macro (Examples).tid       | 26 +++++++++++++++++++
 3 files changed, 47 insertions(+), 9 deletions(-)
 create mode 100644 editions/tw5.com/tiddlers/macros/InspectFilterMacro.tid
 create mode 100644 editions/tw5.com/tiddlers/macros/examples/inspect-filter Macro (Examples).tid

diff --git a/editions/tw5.com/tiddlers/filters/inspect Operator.tid b/editions/tw5.com/tiddlers/filters/inspect Operator.tid
index 3e3a6d449..937327c5d 100644
--- a/editions/tw5.com/tiddlers/filters/inspect Operator.tid	
+++ b/editions/tw5.com/tiddlers/filters/inspect Operator.tid	
@@ -26,12 +26,3 @@ The JSON object contains the following properties:
 *** `input`: the input titles passed to the operator
 *** `output`: the output titles resulting from evaluating the operator
 
-!! Examples
-
-<$transclude $variable="inspect-filter" filter="1 2 3" inputFilter="[all[tiddlers]]"/>
-
-<$transclude $variable="inspect-filter" filter="[title<currentTiddler>] [{$:/palette}length[]] [[marker]]" inputFilter="[all[tiddlers]]"/>
-
-<$transclude $variable="inspect-filter" filter="[all[shadows+tiddlers]tag[$:/tags/MenuBar]!has[draft.of]] -[all[tiddlers+shadows]tag[$:/tags/TopLeftBar]limit[1]then[]else[$:/plugins/tiddlywiki/menubar/items/topleftbar]]" inputFilter="[all[tiddlers]]"/>
-
-<$transclude $variable="inspect-filter" filter="[all[shadows+tiddlers]tag[$:/tags/MenuBar]!has[draft.of]] -[all[tiddlers+shadows]tag[$:/tags/TopLeftBar]limit[1]then[]else[$:/plugins/tiddlywiki/menubar/items/topleftbar]]" inputFilter="[all[tiddlers]]" orientation="vertical"/>
diff --git a/editions/tw5.com/tiddlers/macros/InspectFilterMacro.tid b/editions/tw5.com/tiddlers/macros/InspectFilterMacro.tid
new file mode 100644
index 000000000..3bf19462a
--- /dev/null
+++ b/editions/tw5.com/tiddlers/macros/InspectFilterMacro.tid
@@ -0,0 +1,21 @@
+caption: inspect-filter
+created: 20250401094200994
+modified: 20250401094200994
+tags: Macros [[Core Macros]]
+title: inspect-filter Macro
+type: text/vnd.tiddlywiki
+
+The <<.def inspect-filter>> [[macro|Macros]] displays a schematic representation of the filter evaluation process, including the input, output and intermediate results of evaluating the specified filter. It is based on the [[inspect operator|inspect Operator]].
+
+By default the tabs are arranged horizontally above the content. To get vertical tabs, set the <<.param class>> parameter to <<.value tc-vertical>>.
+
+!! Parameters
+
+;filter
+: The [[filter|Filters]] to be inspected
+;inputFilter
+: Optionally, a filter defining the input titles for the filter to be inspected, defaulting to `[all[tiddlers]]`
+;orientation
+: Optionally, the orientation of the schematic representation, defaulting to `horizontal`. Set to `vertical` to display the tabs vertically. This is useful for narrow windows or when the content is too wide to fit in a horizontal tab layout
+
+<<.macro-examples "inspect-filter">>
diff --git a/editions/tw5.com/tiddlers/macros/examples/inspect-filter Macro (Examples).tid b/editions/tw5.com/tiddlers/macros/examples/inspect-filter Macro (Examples).tid
new file mode 100644
index 000000000..662686de2
--- /dev/null
+++ b/editions/tw5.com/tiddlers/macros/examples/inspect-filter Macro (Examples).tid	
@@ -0,0 +1,26 @@
+created: 20250401094200994
+modified: 20250401094200994
+tags: [[Macro Examples]]
+title: inspect-filter Macro (Examples)
+type: text/vnd.tiddlywiki
+
+
+<$macrocall $name=".example" n="1" eg="""
+<$transclude $variable="inspect-filter" filter="[tags[]prefix[$:/]] :sort[length[]] +[first[2]tagging[]]" inputFilter="[all[tiddlers]]"/>
+"""/>
+
+<$macrocall $name=".example" n="2" eg="""
+<$transclude $variable="inspect-filter" filter="1 2 3" inputFilter="[all[tiddlers]]"/>
+"""/>
+
+<$macrocall $name=".example" n="3" eg="""
+<$transclude $variable="inspect-filter" filter="[title<currentTiddler>] [{$:/palette}length[]] [[marker]]" inputFilter="[all[tiddlers]]"/>
+"""/>
+
+<$macrocall $name=".example" n="4" eg="""
+<$transclude $variable="inspect-filter" filter="[all[shadows+tiddlers]tag[$:/tags/MenuBar]!has[draft.of]] -[all[tiddlers+shadows]tag[$:/tags/TopLeftBar]limit[1]then[]else[$:/plugins/tiddlywiki/menubar/items/topleftbar]]" inputFilter="[all[tiddlers]]"/>
+"""/>
+
+<$macrocall $name=".example" n="5" eg="""
+<$transclude $variable="inspect-filter" filter="[all[shadows+tiddlers]tag[$:/tags/MenuBar]!has[draft.of]] -[all[tiddlers+shadows]tag[$:/tags/TopLeftBar]limit[1]then[]else[$:/plugins/tiddlywiki/menubar/items/topleftbar]]" inputFilter="[all[tiddlers]]" orientation="vertical"/>
+"""/>