From: Thomas Walker Lynch <eknp9n@reasoningtechnology.com>
Date: Tue, 13 Oct 2026 05:42:18 +0000 (+0000)
Subject: updates doc for new locator approach
X-Git-Url: https://git.reasoningtechnology.com/%27%20%20%20full_path%20%20%20%27?a=commitdiff_plain;h=6f6f3d3c8333ca1c8904895d95a86bd0238b2e2b;p=RT-Style

updates doc for new locator approach
---

diff --git a/administrator/document/how-to_release.html b/administrator/document/how-to_release.html
index d3d437b..0f33c4a 100644
--- a/administrator/document/how-to_release.html
+++ b/administrator/document/how-to_release.html
@@ -24,75 +24,75 @@
   <body>
     <RT·theme-selector></RT·theme-selector>
     <RT·article>
-      <RT-title 
+      <RT·title 
         author="Thomas Walker Lynch" 
         date="2026-06-24" 
         title="How to release a project">
-      </RT-title>
+      </RT·title>
 
-      <RT-TOC level="1"></RT-TOC>
+      <RT·TOC level="1"></RT·TOC>
 
       <h1>Prerequisites</h1>
       <p>
-        A developer works in the developer branch of the project, and makes use of the <RT-code>build</RT-code> and <RT-code>promote</RT-code> tools to stage release candidates into the <RT-code>$REPO_HOME/consumer</RT-code> directory. The <RT-code>tester</RT-code> then validates the release candidate. This constitutes a cycle of work, developing, promoting candidates, testing, and then further developing. Once the project manager agrees this cycle is complete, the release flow moves to the next step.
+        A developer works in the developer branch of the project, and makes use of the <RT·code>build</RT·code> and <RT·code>promote</RT·code> tools to stage release candidates into the <RT·code>$REPO_HOME/consumer</RT·code> directory. The <RT·code>tester</RT·code> then validates the release candidate. This constitutes a cycle of work, developing, promoting candidates, testing, and then further developing. Once the project manager agrees this cycle is complete, the release flow moves to the next step.
       </p>
 
       <h1>Make the release branch</h1>
       <p>
-        The <RT-term>administrator</RT-term> executes the release. Open a terminal. Enter the project workspace.
+        The <RT·term>administrator</RT·term> executes the release. Open a terminal. Enter the project workspace.
       </p>
-      <RT-code>
+      <RT·code>
         > . setup administrator
-      </RT-code>
+      </RT·code>
 
       <p>
         Switch to the core development branch. Ensure the local repository is current.
       </p>
-      <RT-code>
+      <RT·code>
         > git checkout core-developer_branch
         > git pull
-      </RT-code>
+      </RT·code>
 
       <p>
         Make a new branch for the release. Use the major version number.
       </p>
-      <RT-code>
+      <RT·code>
         > git checkout -b release_v&lt;major&gt;
-      </RT-code>
+      </RT·code>
 
       <h1>Issue management and patching</h1>
       <p>
-        Only critical issues receive patches on a release branch. The product manager defines what is critical. If approved, the release team applies the fix directly to the existing <RT-code>release_v&lt;major&gt;</RT-code> branch.
+        Only critical issues receive patches on a release branch. The product manager defines what is critical. If approved, the release team applies the fix directly to the existing <RT·code>release_v&lt;major&gt;</RT·code> branch.
       </p>
       <p>
-        The branch name <RT-code>release_v&lt;major&gt;</RT-code> remains static. The code on the branch is updated. The administrator advances the minor release number in the <RT-code>shared/tool/version</RT-code> file.
+        The branch name <RT·code>release_v&lt;major&gt;</RT·code> remains static. The code on the branch is updated. The administrator advances the minor release number in the <RT·code>shared/tool/version</RT·code> file.
       </p>
       <p>
-        The administrator tags the new commit with the full version number, such as <RT-code>v&lt;major&gt;.&lt;minor&gt;</RT-code>. Minor versions are edits on the major release branch. They are visible to a person by running the version command.
+        The administrator tags the new commit with the full version number, such as <RT·code>v&lt;major&gt;.&lt;minor&gt;</RT·code>. Minor versions are edits on the major release branch. They are visible to a person by running the version command.
       </p>
       <p>
-        The developer must ensure the fix is also ported to the <RT-code>core-developer_branch</RT-code>. This prevents the defect from reappearing in future major releases.
+        The developer must ensure the fix is also ported to the <RT·code>core-developer_branch</RT·code>. This prevents the defect from reappearing in future major releases.
       </p>
 
       <h1>Tag and push</h1>
       <p>
         Tag the release with the exact version number.
       </p>
-      <RT-code>
+      <RT·code>
         > git tag -a v&lt;major&gt;.&lt;minor&gt; -m "Release v&lt;major&gt;.&lt;minor&gt;"
-      </RT-code>
+      </RT·code>
 
       <p>
         Push the branch to the remote repository. Push the tags.
       </p>
-      <RT-code>
+      <RT·code>
         > git push origin release_v&lt;major&gt;
         > git push origin --tags
-      </RT-code>
+      </RT·code>
 
       <h1>Repository default branch</h1>
       <p>
-        Set the repository default branch to the new <RT-code>release_v&lt;major&gt;</RT-code> branch on the hosting platform. This ensures a person cloning or pulling the repository receives the most recent major release code by default.
+        Set the repository default branch to the new <RT·code>release_v&lt;major&gt;</RT·code> branch on the hosting platform. This ensures a person cloning or pulling the repository receives the most recent major release code by default.
       </p>
 
       <h1>Verification</h1>
@@ -109,6 +109,6 @@
         <li><strong>Project Manager:</strong> Participates in release issue triage. Assesses impact to the overall project schedule.</li>
       </ul>
 
-    </RT-article>
+    </RT·article>
   </body>
 </html>
diff --git a/administrator/tool/deploy_RT-Style_locators b/administrator/tool/deploy_RT-Style_locators
deleted file mode 100755
index 6910cea..0000000
--- a/administrator/tool/deploy_RT-Style_locators
+++ /dev/null
@@ -1,68 +0,0 @@
-#!/usr/bin/env python3
-import sys
-import os
-import stat
-import shutil
-from pathlib import Path
-
-def deploy_RT_Style_locators(locator_dir_path):
-    locator_dir = Path(locator_dir_path)
-    if not locator_dir.is_dir():
-        print(f"Error: Locator directory not found at {locator_dir_path}")
-        sys.exit(1)
-
-    immediate_js = locator_dir / "immediate.js"
-    direct_js = locator_dir / "direct.js"
-
-    if not immediate_js.exists() or not direct_js.exists():
-        print("Error: Required locator source files missing in the specified directory.")
-        sys.exit(1)
-
-    repo_home = Path(os.environ.get("REPO_HOME", "."))
-    IGNORED_DIRS = {".git"}
-    updated_dirs = set()
-
-    for root, dirs, files in os.walk(repo_home):
-        # Prune ignored directories in place
-        dirs[:] = [d for d in dirs if d not in IGNORED_DIRS]
-        current_path = Path(root)
-
-        # Skip if the directory has already received a locator during this run
-        if current_path in updated_dirs:
-            continue
-
-        needs_locator = False
-        for file_name in files:
-            if file_name.endswith(".html"):
-                file_path = current_path / file_name
-                try:
-                    with open(file_path, "r", encoding="utf-8") as f:
-                        content = f.read()
-                        if "RT-Style_locator.js" in content:
-                            needs_locator = True
-                            break
-                except Exception as e:
-                    print(f"Warning: Could not read {file_path}: {e}")
-
-        if needs_locator:
-            target_file = current_path / "RT-Style_locator.js"
-            
-            # Evaluate the physical location to select the proper locator
-            is_release_candidate = "Manuscript" in current_path.parts or "Manuscript.copy" in current_path.parts
-            source_js = immediate_js if is_release_candidate else direct_js
-            
-            # Eliminate permission denial on read-only artifacts
-            if target_file.exists():
-                target_file.chmod(target_file.stat().st_mode | stat.S_IWUSR)
-            
-            shutil.copyfile(source_js, target_file)
-            print(f"Copied {source_js.name} -> {target_file}")
-            
-            updated_dirs.add(current_path)
-
-if __name__ == "__main__":
-    if len(sys.argv) != 2:
-        print("Usage: deploy_RT-Style_locators <path_to_Locator_directory>")
-        sys.exit(1)
-        
-    deploy_RT_Style_locators(sys.argv[1])
diff --git a/developer/authored/Manuscript.copy/Document/design.html b/developer/authored/Manuscript.copy/Document/design.html
index 68a61e8..b95974d 100644
--- a/developer/authored/Manuscript.copy/Document/design.html
+++ b/developer/authored/Manuscript.copy/Document/design.html
@@ -105,11 +105,12 @@
             &gt; build Manuscript
             &gt; promote write
           </RT·code>
+
           <p>
-            <RT·code>build</RT·code> stages a namespace: it reads <RT·code>developer/authored/Manuscript.copy</RT·code> and writes <RT·code>developer/scratchpad/Manuscript</RT·code>. Run with no arguments it prints its usage and lists the namespaces it found, which is the reliable way to see what is buildable. An argument after a colon is passed to the component, so <RT·code>build Manuscript:clean</RT·code> removes the staged copy, and the pattern is expanded against the namespace list, so <RT·code>build "*:clean"</RT·code> cleans all of them. Quote the pattern or the shell expands it first.
+            <RT·code>build</RT·code> stages a namespace: it reads <RT·code>developer/authored/Manuscript.copy</RT·code> and writes <RT·code>developer/scratchpad/made/Manuscript</RT·code>. Run with no arguments it prints its usage and lists the namespaces it found, which is the reliable way to see what is buildable. An argument after a colon is passed to the component, so <RT·code>build Manuscript:clean</RT·code> removes the staged copy, and the pattern is expanded against the namespace list, so <RT·code>build "*:clean"</RT·code> cleans all of them. Quote the pattern or the shell expands it first.
           </p>
           <p>
-            <RT·code>promote write</RT·code> copies the scratchpad into <RT·code>consumer/</RT·code>, updating only files that are newer and leaving the base <RT·code>.gitignore</RT·code> alone. It has three commands worth knowing beyond that: <RT·code>promote diff</RT·code> reports what is pending, orphaned, or modified in place; <RT·code>promote dry write</RT·code> previews without touching the filesystem; and <RT·code>promote ls</RT·code> prints the consumer tree with permissions and ownership.
+            <RT·code>promote write</RT·code> copies <RT·code>developer/scratchpad/made</RT·code> into <RT·code>consumer/</RT·code>, updating only files that are newer and leaving the base <RT·code>.gitignore</RT·code> alone. Promoted files are read-only, and so are the directories below <RT·code>consumer/</RT·code>; promote opens the directories while it writes and locks them again when it is done. It has three commands worth knowing beyond that: <RT·code>promote diff</RT·code> reports what is pending, orphaned, or modified in place; <RT·code>promote dry write</RT·code> previews without touching the filesystem; and <RT·code>promote ls</RT·code> prints the consumer tree with permissions and ownership.
           </p>
           <p>
             Neither command reaches back. Building without promoting leaves the new engine staged and invisible; promoting without building copies whatever was staged last, which might be old. Run the pair.
@@ -119,18 +120,21 @@
         <RT·section>
           <RT·name>Which documents need a build</RT·name>
           <p>
-            This is the detail that wastes an afternoon when it is not known. A document reaches the engine through <RT·code>RT-Manuscript_locator.js</RT·code>, and there are several locators. Which one sits beside a document decides whether an edit to the engine is visible on a reload or has to travel through the build loop first.
+            This is the detail that wastes an afternoon when it is not known. A document does not name where the engine is. Its header reads the library location recorded in the browser, and falls back to <RT·code>https://style.ReasoningTechnology.com/Manuscript</RT·code> when nothing is recorded. The record is made by opening a <RT·code>setup.html</RT·code>: each Manuscript directory carries one, and opening it records that directory as the library. Which <RT·code>setup.html</RT·code> was opened last decides whether an edit to the engine is visible on a reload or has to travel through the build loop first.
           </p>
-          <RT·dictionary key="Document location" definition="Locator, and what it loads">
-            <RT·entry key="developer/authored/Manuscript.copy/Document">
-              The <RT·code>immediate</RT·code> locator, which resolves to <RT·code>..</RT·code>, the authored tree itself. The design and user manuals live here, so they exercise the engine as written. Edit an element file, reload, and the change is there. No build.
+          <RT·dictionary key="setup.html opened last" definition="What every document then loads">
+            <RT·entry key="developer/authored/Manuscript.copy/setup.html">
+              The authored tree itself. Edit an element file, reload, and the change is there. No build.
+            </RT·entry>
+            <RT·entry key="consumer/Manuscript/setup.html">
+              The promoted engine. An edit is invisible until <RT·code>build Manuscript</RT·code> and <RT·code>promote write</RT·code> have both run.
             </RT·entry>
-            <RT·entry key="Everywhere else">
-              The <RT·code>direct</RT·code> locator, which resolves to <RT·code>consumer/Manuscript</RT·code>. This covers <RT·code>developer/document</RT·code>, the top level <RT·code>document</RT·code> tree, and every test under <RT·code>tester/authored</RT·code>. These load the promoted engine, so an edit is invisible until <RT·code>build Manuscript</RT·code> and <RT·code>promote write</RT·code> have both run.
+            <RT·entry key="None">
+              The engine served from <RT·code>style.ReasoningTechnology.com</RT·code>, which is the last one deployed there.
             </RT·entry>
           </RT·dictionary>
           <p>
-            The practical consequence: a change verified against the manuals has not been verified against the tests. The counter tests under <RT·code>tester/authored/Counter</RT·code> read the promoted engine, and running them against a stale promotion tests the previous change. Build and promote before opening a test, every time.
+            The record is one per browser, not one per document. Chrome keeps a single local storage for every file opened from disk, so the manuals and the tests alike load whatever engine the last opened <RT·code>setup.html</RT·code> named. A change verified against the authored tree has not been verified against the promoted engine. To test a promotion, build, promote, and open <RT·code>consumer/Manuscript/setup.html</RT·code> before opening a test under <RT·code>tester/authored</RT·code>.
           </p>
         </RT·section>
 
@@ -405,12 +409,12 @@
         <RT·section>
           <RT·name>The sequence</RT·name>
           <p>
-            A document's head names only the locator and a short configuration block. Everything else arrives transitively.
+            A document's head carries the header block and a short configuration block. Everything else arrives transitively.
           </p>
 
           <RT·dictionary key="Step" definition="Effect">
-            <RT·entry key="1. Locator">
-              Sets <RT·code>RT.dirpr_library</RT·code>, fixing the root against which every later module path resolves, then requests the make file. Four locator variants exist, differing only in how that root is computed, which is what allows the same document to build inside the distribution or outside it.
+            <RT·entry key="1. Header block">
+              Sets <RT·code>RT.dirpr_library</RT·code>, fixing the root against which every later module path resolves, then requests the make file. The root is the value already set on the page if there is one, else the location a <RT·code>setup.html</RT·code> recorded in the browser, else the Reasoning Technology server. This is what allows the same document to load the authored engine, the promoted engine, or the served one without being edited.
             </RT·entry>
             <RT·entry key="2. Manuscript make">
               Establishes <RT·code>RT.Module</RT·code> and <RT·code>RT.load</RT·code>, then requests the utilities, the stage manager, the theme machinery, the theme manifest, the counter layout, and the note layout.
diff --git a/developer/authored/Manuscript.copy/Document/user.html b/developer/authored/Manuscript.copy/Document/user.html
index 597a722..b694c9d 100644
--- a/developer/authored/Manuscript.copy/Document/user.html
+++ b/developer/authored/Manuscript.copy/Document/user.html
@@ -88,7 +88,15 @@
             &lt;head&gt;
               &lt;meta charset="UTF-8"&gt;
               &lt;title&gt;RT Manuscript: Reference Manual&lt;/title&gt;
-              &lt;script src="RT-Manuscript_locator.js"&gt;&lt;/script&gt;
+              &lt;script&gt;
+                {
+                  let dirpr_library = null;
+                  try{ dirpr_library = localStorage.getItem("RT.dirpr_library"); }catch(e){}
+                  window.RT = window.RT || {};
+                  RT.dirpr_library = RT.dirpr_library || dirpr_library || "https://style.ReasoningTechnology.com/Manuscript";
+                  document.write('&lt;script src="' + RT.dirpr_library + '/Core/RT-Manuscript_make.js"&gt;&lt;\/script&gt;');
+                }
+              &lt;/script&gt;
               &lt;script&gt;
                 window.RT.theme_preference('inverse_wheat');
                 window.RT.load('Layout/paginate');
@@ -105,6 +113,18 @@
           &lt;/html&gt;
         </RT·code>
 
+        <p>Both the first and second script blocks shown in this example can be copied verbatim as shown in this example into other RT Manuscript documents. The second script shown in this header sets the configuration for the manuscript. Users might want to customize this. The first script loads the style engine, and should not be customized by users.
+        </p>
+
+        <p>
+          The first script will attempt to use a style engine installed on the local disk, and if that fails it will attempt to serve the style engine online from</p>
+
+        <RT·code>
+          https://style.ReasoningTechnology.com
+        </RT·code>
+
+        <p>To install the RT Manuscript style engine locally on disk, clone the github project to a convenient place to browse, say <RT·code>$PROJECT</RT·code>. Build the project. This will put the style engine in <RT·code>$PROJECT/consumer/Manuscript</RT·code> directory with the style engine in it. Browse the file <RT·code>consumer/Manuscript/setup.html</RT·code> and the style engine will be installed in the browser. Currently, it is only known to work in Chrome and Brave. <RT·code>setup.html</RT·code> can be loaded multiple times and/or from different locations, which is a useful feature for testing. Upon a page reload, each manuscript will use the most recently loaded style engine. <RT·code>setup.html</RT·code> will remain in effect for all RT Manuscripts for as long as the browser process runs.</p>
+
         <RT·section>
           <RT·name>Decorators</RT·name>
           <RT·dictionary key="Tag" definition="Description & Arguments">
@@ -755,7 +775,15 @@
             &lt;head&gt;
               &lt;meta charset="UTF-8"&gt;
               &lt;title&gt;Wire Protocol Handbook&lt;/title&gt;
-              &lt;script src="RT-Manuscript_locator.js"&gt;&lt;/script&gt;
+              &lt;script&gt;
+                {
+                  let dirpr_library = null;
+                  try{ dirpr_library = localStorage.getItem("RT.dirpr_library"); }catch(e){}
+                  window.RT = window.RT || {};
+                  RT.dirpr_library = RT.dirpr_library || dirpr_library || "https://style.ReasoningTechnology.com/Manuscript";
+                  document.write('&lt;script src="' + RT.dirpr_library + '/Core/RT-Manuscript_make.js"&gt;&lt;\/script&gt;');
+                }
+              &lt;/script&gt;
               &lt;script&gt;
                 window.RT.theme_preference('inverse_wheat');
                 window.RT.load('Layout/paginate');
diff --git a/developer/document/naming_file-and-directory.html b/developer/document/naming_file-and-directory.html
index 8adc549..c597855 100644
--- a/developer/document/naming_file-and-directory.html
+++ b/developer/document/naming_file-and-directory.html
@@ -1,6 +1,4 @@
 <!DOCTYPE html>
-<html lang="en">
-  <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="UTF-8">
diff --git a/developer/experiment/RT-Manuscript_locator.js b/developer/experiment/RT-Manuscript_locator.js
deleted file mode 100644
index 4a1b936..0000000
--- a/developer/experiment/RT-Manuscript_locator.js
+++ /dev/null
@@ -1,37 +0,0 @@
-/*
-  direct.js
-
-
-  We have four scenarios
-
-  immediate - used in the RT-style distribution itself (authored, consummer, staged)
-  direct - used in the RT-style project itself, but not in the distribution
-  indirect - the version all Harmony projects use
-  URL_only - always pulls style through a URL, a webserver must be present
-  
-*/
-
-window.RT = window.RT || {};
-
-(function() {
-  const project_name = "RT-Style"; 
-  const path = window.location.pathname;
-  const project_root_index = path.indexOf('/' + project_name + '/');
-  
-  if (project_root_index !== -1) {
-    // substring(0, x) excludes the trailing slash. We must prepend it to the payload.
-    const absolute_project_root = path.substring(0, project_root_index + project_name.length + 1);
-    window.RT.dirpr_library = absolute_project_root + "/consumer/Manuscript";
-  } else {
-    // Fallback for when served via local Python HTTP daemon from the project root
-    window.RT.dirpr_library = "../consumer/made/Manuscript";
-  }
-  
-  document.write(
-      '<script src="'
-      + window.RT.dirpr_library
-      + '/Core/RT-Manuscript_make.js"'
-      + '><\/script>'
-  );
-
-})();
diff --git a/document/role-and-workflow_product-development.html b/document/role-and-workflow_product-development.html
index a15ab9c..411b732 100644
--- a/document/role-and-workflow_product-development.html
+++ b/document/role-and-workflow_product-development.html
@@ -40,13 +40,13 @@
         These roles interact directly with the repository. To enter a workspace, change directory to the top-level of the project and source the setup file for the desired role:
       </p>
       <RT·code>
-        > . setup administrator
-        > . setup developer
-        > . setup tester
-        > . setup consumer
+        > ./setup administrator
+        > ./setup developer
+        > ./setup tester
+        > ./setup consumer
       </RT·code>
-      <p>
-        It is common for a person to have multiple terminal sessions or IDEs open, each running under a different role environment.
+
+      <p>This will run a new shell with the proper environment setting. It is common for a person to have multiple shells, terminal sessions, or IDEs open, each running under a different role environment.  Development and tests is a common pair, though tests are intended to be production tests. The developer has an <RT·code>experiment</RT·code> directory for experiments.
       </p>
 
       <h3>Administrator role</h3>
diff --git a/shared/document/RT-Manuscript_locator.js b/shared/document/RT-Manuscript_locator.js
deleted file mode 100644
index 2f93eb7..0000000
--- a/shared/document/RT-Manuscript_locator.js
+++ /dev/null
@@ -1,40 +0,0 @@
-/*
-  direct.js
-
-
-  We have four scenarios
-
-  immediate - used in the RT-style distribution itself (authored, consummer, staged)
-  direct - used in the RT-style project itself, but not in the distribution
-  indirect - the version all Harmony projects use
-  URL_only - always pulls style through a URL, a webserver must be present
-  
-*/
-
-window.RT = window.RT || {};
-
-(function() {
-  const project_name = "RT-Style"; 
-  const path = window.location.pathname;
-  const project_root_index = path.indexOf('/' + project_name + '/');
-  
-  if (project_root_index !== -1) {
-    // substring(0, x) excludes the trailing slash. We must prepend it to the payload.
-    const absolute_project_root = path.substring(0, project_root_index + project_name.length + 1);
-    window.RT.dirpr_library = absolute_project_root + "/consumer/Manuscript";
-  } else {
-    // Fallback for when served via local Python HTTP daemon from the project root
-    window.RT.dirpr_library = "../consumer/made/Manuscript";
-  }
-  
-  document.write('<script src="' + window.RT.dirpr_library + '/Core/loader.js"><\/script>');
-  
-  document.write(
-    '<script>' +
-    'window.RT.load("Core/utility");' +
-    'window.RT.load("Core/block_visibility_during_layout");' +
-    'window.RT.load("Theme");' +
-    'window.RT.load("Element/theme_selector");' +
-    '<\/script>'
-  );
-})();