From c1c55ca58a0121a189d45b4001f27e5271993ace Mon Sep 17 00:00:00 2001 From: Thomas Walker Lynch Date: Fri, 28 Aug 2026 03:41:33 +0000 Subject: [PATCH] updates design manual --- .../Manuscript.copy/Document/design.html | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/developer/authored/Manuscript.copy/Document/design.html b/developer/authored/Manuscript.copy/Document/design.html index 0798ac9..717b3b0 100644 --- a/developer/authored/Manuscript.copy/Document/design.html +++ b/developer/authored/Manuscript.copy/Document/design.html @@ -48,6 +48,105 @@

+ + The Harmony project and the build loop +

+ RT-Style is a Harmony project. Harmony is a language agnostic project skeleton: a directory structure, a role based environment, and a build and promotion workflow, checked into a repository and copied to start a new project. This section covers what a person has to know about Harmony to work on the engine. The project's own introduction, document/introduction_Harmony.html, covers the skeleton in full, and the Harmony project itself is the authority when the two disagree. +

+ + + Roles +

+ Work is done under a role. The roles are administrator, developer, tester, and consumer, and each owns a top level directory. A person takes a role by sourcing the setup script from the top of the project, which sets REPO_HOME and SETUP, puts the role's tool directory on the path, and changes into the role's workspace: +

+ + > . setup developer + +

+ The build and promotion tools live in developer/tool and refuse to run outside that environment: both check that SETUP reads developer/tool/setup and exit with an error otherwise. A tester who needs to rebuild the engine therefore takes the developer role for the duration, then leaves it. +

+ + + + Authored, scratchpad, consumer +

+ Three directory properties carry the work product, and the build loop moves it from one to the next. +

+ + + Written by a person, tracked by git, and treated as strictly read only by every tool. The engine source lives here, under Manuscript.copy. + + + Untracked and volatile. A clone always has an empty one. Build output is staged here. + + + Untracked, and the sink for finished work product. Nothing arrives here except by promotion. + + +

+ An authored directory is named <Namespace>.<Tool>, and the suffix selects the build component that handles it, found at developer/tool/build_component/<Tool>. This project has three namespaces: Manuscript.copy, the engine; RT_Formatter.copy; and ExampleGreet.make. The engine is staged by the copy component because it is JavaScript delivered as written, with nothing to compile. +

+ + + + Build and promote +

+ Two commands, in this order: +

+ + > build Manuscript + > promote write + +

+ build stages a namespace: it reads developer/authored/Manuscript.copy and writes developer/scratchpad/Manuscript. 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 build Manuscript:clean removes the staged copy, and the pattern is expanded against the namespace list, so build "*:clean" cleans all of them. Quote the pattern or the shell expands it first. +

+

+ promote write copies the scratchpad into consumer/, updating only files that are newer and leaving the base .gitignore alone. It has three commands worth knowing beyond that: promote diff reports what is pending, orphaned, or modified in place; promote dry write previews without touching the filesystem; and promote ls prints the consumer tree with permissions and ownership. +

+

+ 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. +

+ + + + Which documents need a build +

+ This is the detail that wastes an afternoon when it is not known. A document reaches the engine through RT-Manuscript_locator.js, 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. +

+ + + The immediate locator, which resolves to .., 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. + + + The direct locator, which resolves to consumer/Manuscript. This covers developer/document, the top level document tree, and every test under tester/authored. These load the promoted engine, so an edit is invisible until build Manuscript and promote write have both run. + + +

+ The practical consequence: a change verified against the manuals has not been verified against the tests. The counter tests under tester/authored/Counter read the promoted engine, and running them against a stale promotion tests the previous change. Build and promote before opening a test, every time. +

+ + + + Scratchpads +

+ A directory named scratchpad is untracked and volatile, and there is one in each role's workspace. Tools stage intermediate output there, under a subdirectory named for the namespace, and a person is welcome to use the rest of it as a temporary directory. Nothing on a scratchpad survives a clone, and nothing on it is a source of truth: if the only copy of something is on a scratchpad, it is not saved. +

+

+ Harmony supplies a maintenance tool for it, named scratchpad, which operates on the scratchpad of the current directory. scratchpad ls prints the tree with permissions and ownership, scratchpad size reports whether anything is there, and scratchpad write copies a file or directory onto the pad. +

+

+ scratchpad clear deletes the entire contents of the current directory's scratchpad, preserving only the top level .gitignore. It does not prompt. Given a name, as in scratchpad clear Manuscript, it removes that subdirectory alone, which is the form to reach for. A cleared pad means the next promote write has nothing to promote, so clear and rebuild rather than clear and promote. +

+ + + + A note on the introduction document +

+ document/introduction_Harmony.html describes promotion as a flat copy from scratchpad/made. The tool copies the whole of developer/scratchpad, preserving structure. Where the two disagree, the tool is what runs. +

+ + + The global object

-- 2.20.1