Merge branch 'master' into this-tiddler-reference

* external-js file naming adjusted. import docs form tw5.com. make external-js more visible

* add comment about doc usage in server-external-js edition

* add changes suggested by cdruan

* change modifed date to start vercel rebuild process

boot/boot.js

@@ -1920,7 +1920,7 @@ $tw.loadTiddlersFromSpecification = function(filepath,excludeRegExp) {
 	// Read the specification
 	var filesInfo = $tw.utils.parseJSONSafe(fs.readFileSync(filepath + path.sep + "tiddlywiki.files","utf8"));
 	// Helper to process a file
-	var processFile = function(filename,isTiddlerFile,fields,isEditableFile) {
+	var processFile = function(filename,isTiddlerFile,fields,isEditableFile,rootPath) {
 		var extInfo = $tw.config.fileExtensionInfo[path.extname(filename)],
 			type = (extInfo || {}).type || fields.type || "text/plain",
 			typeInfo = $tw.config.contentTypeInfo[type] || {},
@@ -1941,6 +1941,12 @@ $tw.loadTiddlersFromSpecification = function(filepath,excludeRegExp) {
 				} else {
 					var value = tiddler[name];
 					switch(fieldInfo.source) {
+						case "subdirectories":
+							value = path.relative(rootPath, filename).split('/').slice(0, -1);
+							break;
+						case "filepath":
+							value = path.relative(rootPath, filename);
+							break;
 						case "filename":
 							value = path.basename(filename);
 							break;
@@ -2023,7 +2029,7 @@ $tw.loadTiddlersFromSpecification = function(filepath,excludeRegExp) {
 					var thisPath = path.relative(filepath, files[t]),
 					filename = path.basename(thisPath);
 					if(filename !== "tiddlywiki.files" && !metaRegExp.test(filename) && fileRegExp.test(filename)) {
-						processFile(thisPath,dirSpec.isTiddlerFile,dirSpec.fields,dirSpec.isEditableFile);
+						processFile(thisPath,dirSpec.isTiddlerFile,dirSpec.fields,dirSpec.isEditableFile,dirSpec.path);
 					}
 				}
 			} else {

core/modules/widgets/transclude.js

@@ -279,6 +279,8 @@ TranscludeWidget.prototype.getTransclusionTarget = function() {
 							defaultType: this.transcludeType
 						});
 	}
+	// Set 'thisTiddler'
+	this.setVariable("thisTiddler",this.transcludeTitle);
 	// Return the parse tree
 	if(parser) {
 		return {

core/templates/external-js/save-all-external-js.tid

@@ -5,7 +5,10 @@ title: $:/core/save/all-external-js
 \define saveTiddlerFilter()
 [is[tiddler]] -[prefix[$:/state/popup/]] -[prefix[$:/temp/]] -[prefix[$:/HistoryList]] -[status[pending]plugin-type[import]] -[[$:/core]] -[[$:/boot/boot.css]] -[type[application/javascript]library[yes]] -[[$:/boot/boot.js]] -[[$:/boot/bootprefix.js]] +[sort[title]] $(publishFilter)$
 \end
+
+<!-- Important: core library is provided by serving URI encoded $:/core/templates/tiddlywiki5.js -->
 \define defaultCoreURL() %24%3A%2Fcore%2Ftemplates%2Ftiddlywiki5.js
+
 <$let coreURL={{{ [[coreURL]is[variable]then<coreURL>else<defaultCoreURL>] }}}>
 	{{$:/core/templates/tiddlywiki5-external-js.html}}
 </$let>

editions/server-external-js/tiddlers/config/$__DefaultTiddlers.tid

@@ -0,0 +1,7 @@
+created: 20230314153132081
+modified: 20230314153243008
+title: $:/DefaultTiddlers
+type: text/vnd.tiddlywiki
+
+GettingStarted
+[[Using the external JavaScript template]]

editions/server-external-js/tiddlers/config/$__config_SaveWikiButton_Filename.tid

@@ -0,0 +1,4 @@
+title: $:/config/SaveWikiButton/Filename
+type: text/vnd.tiddlywiki
+
+external-<<version>>.html

editions/server-external-js/tiddlers/external/tiddlywiki.files

@@ -0,0 +1,8 @@
+{
+	"tiddlers": [
+		{
+			"file": "../../../tw5.com/tiddlers/webserver/Using the external JavaScript template.tid",
+			"isTiddlerFile": true
+		}
+	]
+}

editions/server-external-js/tiddlywiki.info

@@ -2,8 +2,7 @@
 	"description": "Client-server edition with external tiddlywiki.js",
 	"plugins": [
 		"tiddlywiki/tiddlyweb",
-		"tiddlywiki/filesystem",
-		"tiddlywiki/highlight"
+		"tiddlywiki/filesystem"
 	],
 	"themes": [
 		"tiddlywiki/vanilla",
@@ -13,7 +12,7 @@
 		"listen": [
 			"--listen","root-tiddler=$:/core/save/all-external-js","use-browser-cache=yes"],
 		"index": [
-			"--render","$:/core/save/offline-external-js","index.html","text/plain",
+			"--render","$:/core/save/offline-external-js","[[external-]addsuffix<version>addsuffix[.html]]","text/plain",
 			"--render","$:/core/templates/tiddlywiki5.js","[[tiddlywikicore-]addsuffix<version>addsuffix[.js]]","text/plain"],
 		"static": [
 			"--render","$:/core/templates/static.template.html","static.html","text/plain",

editions/test/tiddlers/tests/data/this-tiddler/Simple.tid

@@ -0,0 +1,29 @@
+title: ThisTiddler/Simple
+description: Simple usage of thisTiddler variable
+type: text/vnd.tiddlywiki-multiple
+tags: [[$:/tags/wiki-test-spec]]
+
+title: Output
+
+\whitespace trim
+\import Macro
+\define print-this-tiddler()
+<$text text=<<thisTiddler>>/>
+\end
+
+(<$text text=<<thisTiddler>>/>)
+
+(<<print-this-tiddler>>)
+
+(<<imported-print-this-tiddler>>)
+
++
+title: Macro
+
+\define imported-print-this-tiddler()
+<$text text=<<thisTiddler>>/>
+\end
++
+title: ExpectedResult
+
+<p>(Output)</p><p>(Output)</p><p>(Output)</p>

editions/tw5.com/tiddlers/definitions/Xememex.tid

@@ -5,7 +5,7 @@ modified: 20230410105035569
 
 <span style="float:right;">[img width=340 [Xememex Logo]]</span>
 
-Xememex is a multiuser TiddlyWiki from [[Federatial]]. It allows large groups of people to work together on intertwingled wikis that can share content.
+Xememex is a multiuser TiddlyWiki from [[Federatial]]. It allows large groups of people to work together on intertwingled wikis that can share content. It is implemented as a serverless application on Amazon Web Services.
 
 The largest customer implementation has hundreds of online wikis with thousands of users. See https://manuals.annafreud.org/
 

editions/tw5.com/tiddlers/nodejs/tiddlywiki.files_Files.tid

@@ -29,6 +29,8 @@ Each field can be specified as either a ''string'' or ''array'' value to be assi
 ** //extname// the extension of the filename of the file containing the tiddler
 ** //created// the creation date/time of the file containing the tiddler
 ** //modified// the modification date/time of the file containing the tiddler
+** <<.from-version "5.3.0">> //filepath// the path of the file containing the tiddler, relative to the ''path'' property of the directory (only usable in ''directories'' declarations)
+** <<.from-version "5.3.0">> //subdirectories// an array of the subdirectories in the file's path relative, to the ''path'' property of the directory (only usable in ''directories'' declarations)
 * ''prefix'' - (optional) a string to be prepended to the value of the field
 * ''suffix'' - (optional) a string to be appended to the value of the field
 
@@ -52,7 +54,7 @@ Directory specifications in the `directories` array may take the following forms
 ** ''filesRegExp'' - (optional) a [[regular expression|https://developer.mozilla.org/en/docs/Web/JavaScript/Guide/Regular_Expressions]] that matches the filenames of the files that should be processed within the directory
 ** ''isTiddlerFile'' - (required) if `true`, the file will be treated as a [[tiddler file|TiddlerFiles]] and deserialised to extract the tiddlers. Otherwise, the raw content of the file is assigned to the `text` field without any parsing
 ** ''isEditableFile'' - <<.from-version "5.1.23">> (optional) if `true`, changes to the tiddler be saved back to the original file. The tiddler will be saved back to the original filepath as long as it does not generate a result from the $:/config/FileSystemPath filters, which will override the final filepath generated if a result is returned from a filter.
-** ''searchSubdirectories'' - <<.from-version "5.1.23">> (optional) if `true`, all subdirectories of the //path// are searched recursively for files that match the (optional) //filesRegExp//. If no //filesRegExp// is provided, all files in all subdirectories of the //path// are loaded. Tiddler titles generated via a //source// attribute (see above) will only include the filename, not any of the subdirectories of the path. If this results in multiple files with loaded with the same tiddler title, then only the last file loaded under that tiddler title will be in memory. In order to prevent this, you must have multiple directory objects listed and customise the title field with a //prefix// or //suffix// alongside the //source// attribute.
+** ''searchSubdirectories'' - <<.from-version "5.1.23">> (optional) if `true`, all subdirectories of the //path// are searched recursively for files that match the (optional) //filesRegExp//. If no //filesRegExp// is provided, all files in all subdirectories of the //path// are loaded. Tiddler titles generated via the //source// attribute //filename// (see above) will only include the filename, not any of the subdirectories of the path. If this results in multiple files with loaded with the same tiddler title, then only the last file loaded under that tiddler title will be in memory. In order to prevent this, you can use the //filepath// attribute instead of //filename//. Alternately, you can include multiple directory objects and customise the title field with a //prefix// or //suffix// alongside the //source// attribute.
 ** ''fields'' - (required) an object containing values that override or customise the fields provided in the tiddler file (see above)
 
 Fields can also be overridden for particular files by creating a file with the same name plus the suffix `.meta` -- see TiddlerFiles.
@@ -95,6 +97,7 @@ This example retrieves all the files with the extension `.pdf` from a folder spe
     ]
 }
 ```
+
 !! Importing a folder of text files
 
 This example retrieves all the files with the extension `.txt` from a folder specified by a relative path. This folder is within the wiki's base directory, and the current config file is in a directory within the wiki's "tiddlers/" directory. So, in this case the path starts with "../../" to traverse upwards two directory levels, and then down into the "externalnotes/" directory. Each tiddler is set up with the following fields:
@@ -130,4 +133,39 @@ This will load all text files in the `../../externalnotes/` directory into the w
 
 From the examples in [[Customising Tiddler File Naming]] we see that the final `[!tag[externalnote]addprefix[wiki/]]` filter in the $:/config/FileSystemPaths tiddler excludes all tiddlers tagged with `externalnotes` (that have not matched an earlier filter). These tiddlers have their filepath retrieved from the $:/config/OriginalTiddlerPaths generated upon boot startup.
 
-Then, the `[tag[.txt]then[.txt]]` filter in the $:/config/FileSystemExtensions tiddler forces all these tiddlers to be saved back to disk as *.txt and accompanying *.txt.meta files (overriding the normal tiddler-type to file-type mapping). In this case, allowing the snippets of Tiddlywiki wikitext or markdown-text to be saved back to "text" *.txt files.
+Then, the `[tag[.txt]then[.txt]]` filter in the $:/config/FileSystemExtensions tiddler forces all these tiddlers to be saved back to disk as *.txt and accompanying *.txt.meta files (overriding the normal tiddler-type to file-type mapping). In this case, allowing the snippets of Tiddlywiki wikitext or markdown-text to be saved back to "text" *.txt files.
+
+!! Importing and auto-tagging images
+
+This example imports all the image files in the `files` directory and all its subdirectories as external-image tiddlers, and tags them based on their filepath. Each tiddler is set up with the following fields:
+
+* ''title'' - set to the URI decoded base filename of the text file
+* ''created'' - set to the creation date/time of the text file
+* ''modified'' - set to the modification date/time of the text file
+* ''type'' - set to `image/jpeg`. There is currently no way to infer the correct ContentType of the image tiddler from the file, but `image/jpeg` tiddlers should render correctly even with png or gif images. As an alternative, you could create separate definitions for jpg, png, and gif files with the `image/jpeg`, `image/png`, and `image/gif` types respectively.
+* ''tags'' - generated based on the path of the image relative to the parent directory (`files` in this case). Eg, images in `files/photos` will be tagged with `photos`, those in `files/photos/family` will be tagged with both `photos` and `family`, and those in the root `files` directory will have no tags.
+* ''text'' - set to an empty string
+* ''_canonical_uri'' - set to the full filepath of the image relative to the wiki root
+
+
+```
+{
+    "directories": [
+        {
+            "path": "../../files/",
+            "filesRegExp": "^.*\\.(?:jpg|jpeg|png|gif)$",
+            "isTiddlerFile": false,
+	        "searchSubdirectories": true,
+            "fields": {
+                "title": {"source": "basename-uri-decoded"},
+                "created": {"source": "created"},
+                "modified": {"source": "modified"},
+                "type": "image/jpeg",
+                "tags": { "source": "subdirectories" },
+                "text": "",
+                "_canonical_uri": { "source": "filepath", "prefix": "files/" }
+            }
+        }
+    ]
+}
+```

editions/tw5.com/tiddlers/pragmas/Pragma_ _procedure.tid

@@ -28,7 +28,7 @@ For example:
 
 ```
 \procedure sayhi(name:"Bugs Bunny")
-Hi, I'm $name$.
+Hi, I'm <<name>>.
 \end
 
 <<sayhi "Jeremy">>
@@ -37,7 +37,7 @@ Hi, I'm $name$.
 Alternatively, the entire definition can be presented on a single line without an `\end` marker:
 
 ```
-\procedure sayhi(name:"Bugs Bunny") Hi, I'm $name$.
+\procedure sayhi(name:"Bugs Bunny") Hi, I'm <<name>>.
 ```
 
 Procedure definitions can be nested by specifying the name of the procedure in the `\end` marker. For example:
@@ -47,7 +47,7 @@ Procedure definitions can be nested by specifying the name of the procedure in t
 <$action-sendmessage $message="tm-notify" $param="HelloThere"/>
 \end actions
 <$button actions=<<actions>>>
-$caption$
+<<caption>>
 </$button>
 \end special-button
 

editions/tw5.com/tiddlers/procedures/Procedure Calls.tid

@@ -7,7 +7,7 @@ type: text/vnd.tiddlywiki
 
 !! Introduction
 
-This tiddler describes the different ways in which [[macros|Procedures]] can be called.
+This tiddler describes the different ways in which [[procedure|Procedures]] can be called.
 
 !! Procedure Call Transclusion Shortcut
 

editions/tw5.com/tiddlers/system/doc-macros.tid

@@ -134,7 +134,11 @@ This is an example tiddler. See [[Table-of-Contents Macros (Examples)]].
 	</dl>
 	<blockquote class="doc-example-result">
 	<$reveal default="$egvar$" type="match" text="NO-SUCH-VAR">
-		$eg$
+
+$$$text/vnd.tiddlywiki
+$eg$
+$$$
+
 	</$reveal>
 	<$reveal default="$egvar$" type="nomatch" text="NO-SUCH-VAR">
 		<<$egvar$>>

editions/tw5.com/tiddlers/thisTiddler Variable (Examples).tid

@@ -0,0 +1,13 @@
+created: 20230304123606350
+modified: 20230304124149055
+tags: [[currentTiddler Variable]] [[Variable Examples]]
+title: thisTiddler Variable (Examples)
+type: text/vnd.tiddlywiki
+
+
+
+<$macrocall $name=".example" n="1" eg="""<$text text=<<thisTiddler>>/>"""/>
+
+<$macrocall $name=".example" n="2" eg="""\define example() <$text text=<<thisTiddler>>/>
+<<example>>
+"""/>

editions/tw5.com/tiddlers/thisTiddler Variable.tid

@@ -0,0 +1,12 @@
+caption: currentTiddler
+created: 20230304122810114
+modified: 20230304123557862
+tags: Variables [[Core Variables]]
+title: thisTiddler Variable
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.3.0">> The <<.def thisTiddler>> [[variable|Variables]] is set by the <<.wlink TranscludeWidget>> widget to contain the title of the tiddler that was transcluded. This means that within a tiddler <<.def thisTiddler>> will contain the title of that tiddler. It is not affected by macros, which means that within a macro <<.def thisTiddler>> will contain the title of the tiddler from which the macro was invoked. Intermediate, nested macro calls are ignored.
+
+Compare <<.vlink storyTiddler>> and <<.vlink currentTiddler>>.
+
+<<.variable-examples "thisTiddler">>

editions/tw5.com/tiddlers/webserver/Using the external JavaScript template.tid

@@ -1,9 +1,13 @@
 created: 20180905075846391
-modified: 20221207112242775
+modified: 20230319130830880
 tags: [[WebServer Guides]]
 title: Using the external JavaScript template
 type: text/vnd.tiddlywiki
 
+<!--
+This tiddler is also included in the "server-external-js" edition. Take care before editing or moving it.
+-->
+
 You can use a special template to externalise ~TiddlyWiki's core code into a separate file. This configuration allows the browser to cache the core for improved efficiency. 
 
 ! Background
@@ -60,7 +64,7 @@ The "server-external-js" edition lets you save the snapshot from the command lin
 tiddlywiki YOUR_WIKI_FOLDER --build index
 ```
 
-The files `index.html` and `tiddlywikicore-5.x.x.js` will be saved in your wiki folder's `output` directory.
+The files `external-5-x-x.html` and `tiddlywikicore-5.x.x.js` will be saved in your wiki folder's `output` directory.
 
 !! Obtaining the ~TiddlyWiki core in the browser
 

editions/tw5.com/tiddlers/widgets/ParametersWidget.tid

@@ -52,7 +52,7 @@ These attributes provide low level access to the contents of the transcluding wi
 Here the <<.wlink ParametersWidget>> widget is used to declare a parameter whose default value is transcluded from another tiddler.
 
 <$macrocall $name='wikitext-example-without-html' 
-src="""\procedure mymacro
+src="""\procedure mymacro()
 <$parameters name={{$:/SiteTitle}} age="21">
 My name is <<name>> and my age is <<age>>.
 </$parameters>

plugins/tiddlywiki/dynannotate/config/LegacySelectionTracker.tid

@@ -0,0 +1,3 @@
+title: $:/config/Dynannotate/LegacySelectionTracker/Enable
+
+no

plugins/tiddlywiki/dynannotate/config/SelectionTracker.tid

@@ -0,0 +1,3 @@
+title: $:/config/Dynannotate/SelectionTracker/Enable
+
+no

plugins/tiddlywiki/dynannotate/docs/readme.tid

@@ -25,7 +25,7 @@ The `<$dynannotate>` widget uses the selection tracker to support a popup that d
 |popup |Popup state tiddler to be used to trigger a popup when an annotation is clicked |
 |search |Search text to be highlighted within the widget |
 |searchDisplay |"overlay" or "snippet" (see below) |
-|searchMode |"normal" (default), "regexp" or "whitespace" (see below) |
+|searchMode |"literal" (default), "regexp", "whitespace", "words" or "some" (see below) |
 |searchMinLength |Optional minimum length of search string |
 |searchCaseSensitive |"yes" (the default) for a case sensitive search, or "no" for a case insensitive search|
 |searchClass |Optional CSS class to be added to search overlays |
@@ -46,9 +46,10 @@ The values supported by the `searchDisplay` attribute are:
 
 The search modes supported by the `searchMode` attribute are:
 
-* `normal` - a literal string of plain text to match
+* `literal` or `normal` - a literal string of plain text to match (default).
 * `regexp` - a JavaScript-style regular expression (without the quoting backslashes and flags)
-* `whitespace` - a literal string to match while normalising runs of whitespace. This allows `a. b` to match `a.  b`
+* `whitespace` - a literal string to match while normalising runs of whitespace. Thus `A B` matches `A   B`.
+* `words` or `some` - treats the search string as a list of tokens separated by whitespace, and matches all tokens (regardless of ordering and whether there is other text in between)
 
 When the selection popup is triggered, the currently selected text can be found in the tiddler named in the `selection` attribute, with the disambiguating prefix and suffix in the tiddlers named in the `selectionPrefix` and `selectionPopup` tiddlers. Note that the selection text will be an empty string if the selection popup was triggered in response to a click (ie zero width selection).
 
@@ -95,7 +96,7 @@ Note that using the `annotate-tiddler` field to associate an annotation with the
 
 !! Selection Trackers
 
-The following configuration tiddlers can be used to control whether the selection trackers are enabled when the following configuration tiddlers are set to ''yes'' (the default).
+The selection trackers are enabled when the following configuration tiddlers are set to ''yes''.
 
 * $:/config/Dynannotate/SelectionTracker/Enable for the main selection tracker
 * $:/config/Dynannotate/LegacySelectionTracker/Enable for the legacy selection tracker

plugins/tiddlywiki/dynannotate/examples/simple.tid

@@ -10,16 +10,33 @@ caption: Simple
 $example$
 \end
 
+\define search-example-code()
+<!-- 
+The inline filters update the displayed codeblock to reflect the choices the user has made in the UI.
+The rules pragma is used here to evaluate only these filters, but leave everything else untouched.
+The tabs and linebreaks within the parameters to addprefix, though maybe confusing, help with the readability of the codeblock output.
+-->
+\rules only filteredtranscludeinline
+<$dynannotate
+	search="{{{ [{$:/temp/dynannotate-example/search}!is[blank]else[The human mind]] }}}"{{{ [{$:/temp/dynannotate-example/searchMode}!search::some[literal normal]addprefix[
+	searchMode="]addsuffix["]] }}}
+	searchCaseSensitive="{{{ [{$:/temp/dynannotate-example/searchCaseSensitive}!is[blank]else[yes]] }}}"{{{ [{$:/temp/dynannotate-example/searchClass}!is[blank]addprefix[
+	searchClass="]addsuffix["]] }}}
+>
+<$transclude tiddler="$:/plugins/tiddlywiki/dynannotate/example-text-1" mode="block"/>
+<$transclude tiddler="$:/plugins/tiddlywiki/dynannotate/example-text-2" mode="block"/>
+</$dynannotate>
+\end
+
 <div class="tc-dynannotation-example-info">
 
-!! Simple annotation
+!! Annotations with `target`
 
-We use the `target*` attributes to specify a target string for the annotation and optionally a prefix and suffix for disambiguating multiple occurances.
+We use the `target*` attributes to specify a target string for the annotation and optionally a prefix and suffix for disambiguating multiple occurences.
 
 </div>
 
-<<show-example """
-<$dynannotate
+<<show-example """<$dynannotate
 	target="the"
 	targetPrefix="Yet "
 	targetSuffix=" speed"
@@ -30,55 +47,35 @@ We use the `target*` attributes to specify a target string for the annotation an
 
 <div class="tc-dynannotation-example-info">
 
-!! Plain text searching
+!! Highlights with `search`
 
-We use the `search` attribute to specify a search string for highlighting:
+We use the `search` attribute to specify a search string for highlighting.
+
+The search type can be set with the `searchMode` and `searchCaseSensitive` attributes.
+
+We can style the highlights with the `searchClass` attribute, which has some predefined values.
 
 </div>
 
-<<show-example """
+|tc-table-no-border tc-dynannotate-search-parameters|k
+|search term |<$edit-text tiddler="$:/temp/dynannotate-example/search" field="text" tag="input" default="The human mind" />|
+|search mode |<$select tiddler="$:/temp/dynannotate-example/searchMode" field="text" default="literal"><option value="literal">literal</option><option value="normal">normal</option><option value="regexp">regexp</option><option value="whitespace">whitespace</option><option value="some">some</option><option value="words">words</option></$select> |
+|case sensitive |<$checkbox tiddler="$:/temp/dynannotate-example/searchCaseSensitive" field="text" checked="yes" unchecked="no" default="yes"> <$text text={{{ [{$:/temp/dynannotate-example/searchCaseSensitive}!is[blank]else[yes]] }}} /></$checkbox> |
+|search class |<$select tiddler="$:/temp/dynannotate-example/searchClass" field="text" default=""><option value="">(none)</option><option value="tc-dynannotation-search-overlay-animated">tc-dynannotation-search-overlay-animated</option><option value="tc-dynannotation-search-overlay-blurred">tc-dynannotation-search-overlay-blurred</option></$select> |
+
 <$dynannotate
-	search="the"
+	search={{{ [{$:/temp/dynannotate-example/search}!is[blank]else[The human mind]] }}}
+	searchMode={{{ [{$:/temp/dynannotate-example/searchMode}] }}}
+	searchCaseSensitive={{{ [{$:/temp/dynannotate-example/searchCaseSensitive}!is[blank]else[yes]] }}}
+	searchClass={{{ [{$:/temp/dynannotate-example/searchClass}] }}}
 >
 <$transclude tiddler="$:/plugins/tiddlywiki/dynannotate/example-text-1" mode="block"/>
+<$transclude tiddler="$:/plugins/tiddlywiki/dynannotate/example-text-2" mode="block"/>
 </$dynannotate>
-""">>
 
-<div class="tc-dynannotation-example-info">
-
-!! Regular expression searching
-
-We use the `mode` attribute set to `regexp` to highlight matches of a regular expression:
-
-</div>
-
-<<show-example """
-<$dynannotate
-	search="the|an"
-	searchMode="regexp"
-	searchClass="tc-dynannotation-search-overlay-blurred"
->
-<$transclude tiddler="$:/plugins/tiddlywiki/dynannotate/example-text-1" mode="block"/>
-</$dynannotate>
-""">>
-
-<div class="tc-dynannotation-example-info">
-
-!! Normalised whitespace searching
-
-We use the `mode` attribute set to `whitespace` to search for a string with whitespace normalised (ie runs of whitespace are collapsed to a single space for matching purposes):
-
-</div>
-
-<<show-example """
-<$dynannotate
-	search="does  not     work that way.     It operates"
-	searchMode="whitespace"
-	searchClass="tc-dynannotation-search-overlay-animated"
->
-<$transclude tiddler="$:/plugins/tiddlywiki/dynannotate/example-text-1" mode="block"/>
-</$dynannotate>
-""">>
+<$wikify name="wikifiedCode" text=<<search-example-code>> mode="block" output="text">
+<$codeblock code=<<wikifiedCode>>/>
+</$wikify>
 
 <div class="tc-dynannotation-example-info">
 
@@ -90,8 +87,7 @@ Annotation tiddlers can be used to describe annotations. This example references
 
 <<list-links "[all[shadows+tiddlers]annotate-tiddler[$:/plugins/tiddlywiki/dynannotate/example-text-1]]">>
 
-<<show-example """
-<$dynannotate
+<<show-example """<$dynannotate
 	filter="[all[shadows+tiddlers]annotate-tiddler[$:/plugins/tiddlywiki/dynannotate/example-text-1]]"
 >
 <$transclude tiddler="$:/plugins/tiddlywiki/dynannotate/example-text-1" mode="block"/>

plugins/tiddlywiki/dynannotate/examples/viewtemplate-text.tid

@@ -34,6 +34,7 @@ title: $:/plugins/tiddlywiki/dynannotate/examples/viewtemplate/text
 	selectionPopup={{{ [<currentTiddler>addprefix[$:/state/dynannotate/popup-selection/]] }}}
 	search={{$:/temp/search}}
 	searchClass="tc-dynannotation-search-overlay-blurred"
+	searchCaseSensitive="no"
 	searchMinLength={{$:/config/Search/MinLength}}
 >
 <$transclude mode="block">

plugins/tiddlywiki/dynannotate/examples/viewtemplate.tid

@@ -1,28 +1,69 @@
-title: $:/plugins/tiddlywiki/dynannotate/examples/viewtemplate
-tags: $:/tags/dynannotateExamples
 caption: View Template
+tags: $:/tags/dynannotateExamples
+title: $:/plugins/tiddlywiki/dynannotate/examples/viewtemplate
+
+\define show-example(example)
+<$codeblock code=<<__example__>>/>
+
+//''Displays as:''//
+
+$example$
+\end
 
 <div class="tc-dynannotation-example-info">
 
 !! Using Dynannotate in the view template
 
-This example shows how to override the core view template with a custom template that includes dynannotate. It is disabled by default but can be enabled by clicking the button below. (Clicking the button below copies the custom view template from $:/plugins/tiddlywiki/dynannotate/examples/viewtemplate/text to $:/core/ui/ViewTemplate/body).
+This example shows how to override the core view template with a custom template that includes dynannotate. It is disabled by default but can be enabled by clicking the corresponding button below. The example transcludes the [[Searching in TiddlyWiki|$:/plugins/tiddlywiki/dynannotate/searching-in-tiddlywiki]] tiddler for illustration purposes, but the chosen view template is applied to all open tiddlers.
 
-Once enabled, this example demonstrates several features:
+Once enabled, this example demonstrates several features of Dynannotate:
 
-* Highlighting of search results within tiddler bodies
-* Creating annotations on any tiddler by selecting text and then clicking a colour in the resulting dropdown
+* Highlight text within tiddler bodies -- any text entered in the sidebar search input will be highlighted (in all tiddlers)
+* Create annotations (on any tiddler) by selecting text and then clicking //Create annotation// in the resulting dropdown
+
+(Clicking the buttons below either puts the custom body view template [[$:/plugins/tiddlywiki/dynannotate/examples/viewtemplate/text]] in front of the default in the [[View Template Body Cascade|https://tiddlywiki.com/#View%20Template%20Body%20Cascade]] or removes it from the cascade).
 
 </div>
 
 <$button>
-<$action-setfield $tiddler="$:/config/ViewTemplateTitleFilters/dynannotate" tags="$:/tags/ViewTemplateTitleFilter" text="[[$:/plugins/tiddlywiki/dynannotate/examples/viewtemplate/text]]" list-before="$:/config/ViewTemplateBodyFilters/default"/>
+<$action-setfield $tiddler="$:/config/ViewTemplateBodyFilters/dynannotate" tags="$:/tags/ViewTemplateBodyFilter" text="[[$:/plugins/tiddlywiki/dynannotate/examples/viewtemplate/text]]" list-before="$:/config/ViewTemplateBodyFilters/default"/>
 Click here to use the custom view template
 </$button>
 
 <$button>
-<$action-deletetiddler $tiddler="$:/config/ViewTemplateTitleFilters/dynannotate"/>
+<$action-deletetiddler $tiddler="$:/config/ViewTemplateBodyFilters/dynannotate"/>
 Click here to revert to the core view template
 </$button>
 
-<$codeblock code={{$:/plugins/tiddlywiki/dynannotate/examples/viewtemplate/text}}/>
+<p/>
+
+<div class="tc-dynannotation-example-info">
+
+!! Using Dynannotate to highlight text on a per-tiddler basis
+
+Using state tiddlers containing the text which is to be highlighted, Dynannotate highlights can be applied on a per-tiddler basis when used in the body view template. This can also be combined with the [[GenesisWidget]] to insert the Dynannotate widget into the DOM only when such a highlight is configured.
+
+This example uses a transcluded tiddler, but Dynannotate could be added to the view template (to show highlights in all parts of a tiddler) or to the body view template (to show highlights only in the tiddler body) in the same way. Note how in this example, Dynannotate only affects the transcluded content.
+
+</div>
+
+<<show-example """<$button set="$:/state/dynannotate/examples/viewtemplate" setTo="tiddler">Highlight "tiddler"</$button>
+<$button set="$:/state/dynannotate/examples/viewtemplate" setTo="created">Highlight "created"</$button>
+<$button set="$:/state/dynannotate/examples/viewtemplate" setTo="">Clear highlights</$button>
+<p/>
+<$let dynannotateText={{$:/state/dynannotate/examples/viewtemplate}}>
+    <$genesis $type={{{ [<dynannotateText>!is[blank]then[$dynannotate]] }}}
+              search=<<dynannotateText>>
+              searchDisplay="overlay"
+              searchClass="tc-dynannotation-search-overlay-animated"
+              searchCaseSensitive="no">
+        <div class="tc-dynannotate-example-frame">
+
+            !! `$:/core/ui/ControlPanel/TiddlerFields`:
+            <$transclude tiddler="$:/core/ui/ControlPanel/TiddlerFields" mode="block" />
+        </div>
+    </$genesis>
+</$let>
+""">>
+
+When used in the view template, the state tiddler title could be derived from the current tiddler, e.g. `<$let dynannotateText={{{ [<currentTiddler>addprefix[$:/state/dynannotate/]get[text]] }}}>`, to configure highlights for each tiddler separately.

plugins/tiddlywiki/dynannotate/modules/textmap.js

@@ -15,7 +15,7 @@ Structure for modelling mapping between a string and its representation in the D
 var PREFIX_SUFFIX_LENGTH = 50;
 
 /*
-Build a map of the text content of a dom node and its descendents:
+Build a map of the text content of a DOM node and its descendants:
 
 string: concatenation of the text content of child nodes
 metadata: array of {start,end,domNode} where start and end identify position in the string
@@ -60,7 +60,7 @@ exports.TextMap.prototype.locateMetadata = function(position) {
 };
 
 /*
-Search for the first occurance of a target string within the textmap of a dom node
+Search for the first occurrence of a target string within the textmap of a DOM node
 
 Returns an object with the following properties:
 	startNode: node containing the start of the text
@@ -92,10 +92,10 @@ exports.TextMap.prototype.findText = function(targetString,targetPrefix,targetSu
 };
 
 /*
-Search for all occurances of a string within the textmap of a dom node
+Search for all occurrences of a string within the textmap of a DOM node
 
 Options include:
-	mode: "normal", "regexp" or "whitespace"
+	mode: "normal", "literal", "regexp", "whitespace", "some" or "words"
 	caseSensitive: true if the search should be case sensitive
 
 Returns an array of objects with the following properties:
@@ -121,6 +121,11 @@ exports.TextMap.prototype.search = function(searchString,options) {
 		regExpString = "(" + searchString.split(/\s+/g).filter(function(word) {
 			return !!word
 		}).map($tw.utils.escapeRegExp).join("\\s+") + ")";
+	} else if(options.mode === "words" || options.mode === "some") {
+		// Match any word separated by whitespace
+		regExpString = "(" + searchString.split(/\s+/g).filter(function(word) {
+			return !!word
+		}).map($tw.utils.escapeRegExp).join("|") + ")";
 	} else {
 		// Normal search
 		regExpString = "(" + $tw.utils.escapeRegExp(searchString) + ")";

plugins/tiddlywiki/dynannotate/styles.tid

@@ -34,6 +34,16 @@ tags: [[$:/tags/Stylesheet]]
 	animation: ta-dynannotation-search-overlay-animated 12s linear infinite;
 }
 
+.tc-dynannotate-example-frame {
+    border: 1px solid black;
+    border-radius: 20px;
+    padding: 1em;
+}
+
+.tc-control-panel table.tc-dynannotate-search-parameters, .tc-control-panel table.tc-dynannotate-search-parameters input {
+    width: initial;
+}
+
 .tc-dynannotate-snippet-highlight {
 	background: #efef53;
 }