update and add documentation tiddlers

editions/tw5.com/tiddlers/features/VariableFormat.tid

@@ -0,0 +1,20 @@
+created: 20240219185725834
+modified: 20240221012350449
+tags: Features
+title: VariableFormat
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.3.4">>
+
+Finding "self explaining" variable names for functions, procedures, widgets and macros is difficult. So if variables are listed with <<.mlink dumpvariables>>, <<.mlink search-variables>> or from the "Variables" tab in the $:/AdvancedSearch, it's not obvious ''how'' they work and how they are defined. 
+
+The <<.olink variables>> operator returns all "visible" variables from the current context, depending on where the filter run is executed. The <<.olink getvariable>> allows us to return the "text" or the "value" of variables. But this information is not enough to get a good understanding of existing variables. 
+
+So using <<.olink getvariables>> operator in combination with the <<.olink format>> operator we are able to improve information in variable listings. 
+
+|Token |Substituted Value |h
+|`$type$` |variabe type eg: `\function`, `\procedure` and so on |
+|`$name$` |returns the name of the variable |
+|`$params$` |returns a list of parameters, which are defined with functions, procedures ... |
+|`$firstLine$` |returns the first line of the variable content-type as used by <<.olink getvariables>> |
+|`$varType$` |returns `var`, `fn`, ` proc`, ` macro` or ` widget` which can be used with the <<.olink variables>> operator |

editions/tw5.com/tiddlers/macros/DumpVariablesMacro.tid

@@ -1,11 +1,11 @@
 caption: dumpvariables
 created: 20140908104107181
-modified: 20240221005326328
+modified: 20240427121039507
 tags: Macros [[Core Macros]]
 title: dumpvariables Macro
 type: text/vnd.tiddlywiki
 
-The <<.def dumpvariables>> [[macro|Macros]] returns a table showing the values of all [[variables|Variables]] and [[macros|Macros]] that exist at that position in the [[widget tree|Widgets]].
+The <<.def dumpvariables>> [[macro|Macros]] returns a table showing the values of all [[variables|Variables]], [[procedures|Procedures]], [[functions|Functions]], [[widgets|Widgets]] and [[macros|Macros]] that exist at that position in the [[widget tree|Widgets]].
 
 It is useful for debugging and exploring ~TiddlyWiki's internals.
 
@@ -13,11 +13,14 @@ Placeholders are replaced with values in the normal way, but using the default v
 
 !! Parameters
 
+The following parameters are <<.from-version "5.3.4">>
+
 ; type
 : If type is empty all variable types are shown: `fn, var, proc, macro, widget`. Using the type parameter will reduce the list.
 
-; raw
+; sort
-: Is used to allow the <<.olink variables>> to return a raw list. By default the list is alphabetically sorted.
+: `raw`: Is used to allow the <<.olink variables>> to return a raw list.
+: `alphabetical`: If sort is missing, by ''default ''the list is alphabetically sorted.
 
 ; subfilter
 : This parameter limits the number of variables that are listed eg:  `subfilter:"[search::some[sort .attr]]" `
@@ -26,3 +29,5 @@ Placeholders are replaced with values in the normal way, but using the default v
 : Format the output string using the VariableFormat. Defaults to `$type$ $name$($params$) $firstLine$`.
 
 !!! <<.macro-examples "dumpvariables">>
+
+Also see: [[search-variables Macro]]

editions/tw5.com/tiddlers/macros/examples/dumpvariables.tid

@@ -1,5 +1,5 @@
 created: 20150221151358000
-modified: 20240221165833692
+modified: 20240427120040367
 tags: [[dumpvariables Macro]] [[Macro Examples]]
 title: dumpvariables Macro (Examples)
 type: text/vnd.tiddlywiki
@@ -21,7 +21,7 @@ eg="""<$let EXAMPLE="123" >
 <$macrocall $name=".example" n="3"
 eg="""<<dumpvariables subfilter:"[prefix[.a]]">>"""/>
 
-The following list will be very long. It shows all variables known within this tiddler. Using the macro in a different context. Eg: the sidebar, variables will have different values.
+''The following list will be very long.'' It shows all variables known within this tiddler. Using the macro in a ''different context''. Eg: the sidebar, variables will show ''different values''.
 
 <$macrocall $name=".example" n="4"
 eg="""<<dumpvariables>>"""/>

editions/tw5.com/tiddlers/macros/examples/search-variables Macro (Examples).tid

@@ -0,0 +1,29 @@
+created: 20240427121446051
+modified: 20240427122708648
+title: search-variables Macro (Examples)
+type: text/vnd.tiddlywiki
+
+The following example will list all variables that contain the word "example" in uppercase ''and'' also lowercase, due to the default setting of the <<.olink search>> operator.
+
+While ''the following list will be long'' it should be easy to refine it. It shows all variables known within this tiddler. Using the procedure in a ''different context''. Eg: the sidebar, variables will show ''different values''.
+
+<$macrocall $name=".example" n="1"
+eg="""<<search-variables >>"""/>
+
+<$macrocall $name=".example" n="2"
+eg="""<$let EXAMPLE="123" >
+<<search-variables subfilter:"[search::some[EXAMPLE dumpvariables]]">>
+</$let>"""/>
+
+Listing only specific varibles can be achieved using the <<.olink search>> operator as a subfilter
+
+<$macrocall $name=".example" n="3"
+eg="""<$let EXAMPLE="123" >
+<<search-variables subfilter:"[search::casesensitive,some[EXAMPLE dumpvariables]]">>
+</$let>"""/>
+
+<$macrocall $name=".example" n="4"
+eg="""<<search-variables subfilter:"[prefix[.a]]">>"""/>
+
+
+

editions/tw5.com/tiddlers/macros/search-variables Macro.tid

@@ -0,0 +1,34 @@
+caption: search-variables
+created: 20240427120451313
+modified: 20240427123016441
+tags: Macros [[Core Macros]]
+title: search-variables Macro
+type: text/vnd.tiddlywiki
+
+This macro is <<.from-version "5.3.4">>
+
+The <<.def search-variables>> presents a form, which allows fast filtering of the resulting list. This procedure is also used in the $:/AdvancedSearch ''-> Variables'' tab.
+
+It returns a table showing the values of all [[variables|Variables]], [[procedures|Procedures]], [[functions|Functions]], [[widgets|Widgets]] and [[macros|Macros]] that exist at that position in the [[widget tree|Widgets]].
+
+It is useful for debugging and exploring ~TiddlyWiki's internals.
+
+!! Parameters
+
+; type
+: If type is empty all variable types are shown
+: optional: `fn, var, proc, macro, widget`. Using the type parameter will reduce the list.
+
+; sort
+: `raw`: Is used to allow the <<.olink variables>> to return a raw list.
+: `alphabetical`: If sort is missing, by ''default ''the list is alphabetically sorted.
+
+; subfilter
+: This parameter limits the number of variables that are listed eg:  `subfilter:"[search::some[sort .attr]]" `
+
+; format
+: Format the output string using the VariableFormat. Defaults to `$type$ $name$($params$) $firstLine$`.
+
+!!! <<.macro-examples "search-variables">>
+
+Also see: [[dumpvariables Macro]]