From: Thomas Walker Lynch <eknp9n@reasoningtechnology.com>
Date: Tue, 10 Mar 2026 17:53:12 +0000 (+0000)
Subject: doc additions
X-Git-Url: https://git.reasoningtechnology.com/%5B%5E?a=commitdiff_plain;h=refs%2Fheads%2Fcore_developer_branch;p=Harmony

doc additions
---

diff --git a/developer/document/RT_code_format.html b/developer/document/RT_code_format.html
index 4f6c3d2..7f2de0c 100644
--- a/developer/document/RT_code_format.html
+++ b/developer/document/RT_code_format.html
@@ -13,7 +13,7 @@
     <RT-article>
       <RT-title 
         author="Thomas Walker Lynch" 
-        date="2026-03-09" 
+        date="2026-03-11" 
         title="RT code format conventions">
       </RT-title>
 
@@ -144,7 +144,7 @@
 
       <h1>The CLI vs. work function pattern</h1>
       <p>
-        To avoid the "String Trap" — where logic is tightly coupled to the terminal and requires string serialization to reuse — executable modules must separate the Command Line Interface from the core logic.
+        To avoid the "String Trap" (where logic is tightly coupled to the terminal and requires string serialization to reuse) executable modules must separate the Command Line Interface from the core logic.
       </p>
       <ul>
         <li><strong>Work Functions:</strong> Implement core logic. They accept and return native instances (ints, lists, paths), never look at <RT-code>sys.argv</RT-code> (or equivalent), and do not depend on being run from a command line.</li>
@@ -163,6 +163,29 @@
         <li>Prefer explicit <RT-code>*_count</RT-code> parameters over sentinel values when passing arrays.</li>
       </ul>
 
+      <h1>Automated formatting tools</h1>
+      <p>
+        To ensure consistency without manual drudgery, the Harmony skeleton provides a dedicated code formatter called <RT-code>RTfmt</RT-code>. A person can find this tool in the <RT-code>shared/tool/</RT-code> directory.
+      </p>
+
+      <h2>The RTfmt CLI</h2>
+      <p>
+        <RT-code>RTfmt</RT-code> is a shallow-tokenizing formatter written in Python. It parses source code into structural blocks (strings, comments, commas, and enclosures) without needing a full Abstract Syntax Tree. This architecture allows it to safely enforce RT formatting rules across multiple languages while preserving indentation and protecting native operators.
+      </p>
+      <ul>
+        <li><RT-code>RTfmt write &lt;file...&gt;</RT-code> : Formats files in place. It performs a content comparison before writing, leaving the file modification timestamp untouched if the file is already compliant.</li>
+        <li><RT-code>RTfmt pipe</RT-code> : Reads from standard input and writes to standard output, making it ideal for editor integration.</li>
+        <li><RT-code>--lisp</RT-code> : A flag that instructs the formatter to skip the outermost enclosure padding rule, honoring the Lisp function call exception.</li>
+      </ul>
+
+      <h2>Emacs integration</h2>
+      <p>
+        For Emacs users, the <RT-code>RTfmt.el</RT-code> file provides the <RT-code>RTfmt-buffer</RT-code> interactive command.
+      </p>
+      <p>
+        This wrapper passes the current buffer through the <RT-code>RTfmt pipe</RT-code> command. It automatically detects Lisp-derived modes to append the <RT-code>--lisp</RT-code> flag. Furthermore, it utilizes a non-destructive buffer replacement strategy. This ensures that a programmer's cursor position, selection marks, and window scroll state remain anchored exactly where they were before the formatting occurred.
+      </p>
+
       <h1>Exercises</h1>
       <h2>Exercise 1: Comma and function call formatting</h2>
       <p>Reformat the following C code snippet to strictly adhere to the RT code format rules.</p>
@@ -197,7 +220,6 @@
         <li>A variable holding multiple absolute file paths for images: <RT-code>imageFiles</RT-code></li>
       </ul>
 
-
     </RT-article>
   </body>
 </html>
diff --git a/developer/document/Single-file_C_modules_and_namespaces.html b/developer/document/Single-file_C_modules_and_namespaces.html
index c05225e..23af5f8 100644
--- a/developer/document/Single-file_C_modules_and_namespaces.html
+++ b/developer/document/Single-file_C_modules_and_namespaces.html
@@ -2,7 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8">
-    <title>Single-file C modules and namespaces</title>
+    <title>C modules, namespaces, and the build lifecycle</title>
     <script src="setup.js"></script>
     <script>
       window.StyleRT.include('RT/theme');
@@ -13,8 +13,8 @@
     <RT-article>
       <RT-title 
         author="Thomas Walker Lynch" 
-        date="2026-03-10" 
-        title="Single-file C modules and namespaces">
+        date="2026-03-11" 
+        title="C modules, namespaces, and the build lifecycle">
       </RT-title>
 
       <RT-TOC level="1"></RT-TOC>
@@ -88,7 +88,7 @@
         #include "Math.lib.c"
       </RT-code>
       <p>
-        Because every file is protected by a <RT-code>·ONCE</RT-code> include guard, it is safe for multiple modules to include the same dependency. The preprocessor will only expand the interface once per translation unit.
+        Because every file is protected by a <RT-code>·ONCE</RT-code> include guard, it is safe for multiple modules to include the same dependency. The preprocessor will expand the interface once per translation unit.
       </p>
 
       <h2>Information hiding</h2>
@@ -120,6 +120,52 @@
         A <RT-code>.CLI.c</RT-code> file includes the necessary <RT-code>.lib.c</RT-code> files, parses command-line arguments in the <RT-code>main</RT-code> function, and passes native data types to a dedicated <RT-code>CLI()</RT-code> function to orchestrate the core logic.
       </p>
 
+      <h1>Directory structure and namespaces</h1>
+      <p>
+        The physical layout of the <RT-code>authored</RT-code> directory dictates how the build orchestrator finds the source code.
+      </p>
+      <ul>
+        <li><strong>Flat Structure:</strong> If a project does not utilize namespaces, the <RT-code>.lib.c</RT-code> and <RT-code>.CLI.c</RT-code> files reside directly inside the <RT-code>developer/authored/</RT-code> directory.</li>
+        <li><strong>Namespaced Structure:</strong> If a project utilizes namespaces, the files are grouped into subdirectories matching the namespace name, such as <RT-code>developer/authored/ExampleGreet/</RT-code>.</li>
+      </ul>
+
+      <h1>Making the code</h1>
+      <p>
+        The developer compiles the code using the <RT-code>make</RT-code> wrapper script located in <RT-code>developer/tool/make</RT-code>. This script accepts two primary arguments: the build command and the target namespace.
+      </p>
+
+      <RT-code>
+        > make &lt;command&gt; [namespace]
+      </RT-code>
+
+      <p>
+        To build the <RT-code>ExampleGreet</RT-code> code, a person issues the following command from the developer workspace:
+      </p>
+
+      <RT-code>
+        > make all ExampleGreet
+      </RT-code>
+
+      <p>
+        Behind the scenes, the <RT-code>make</RT-code> wrapper assigns the namespace to an environment variable and calls the master orchestrator makefile. The orchestrator detects the namespace, updates the source directory search path to <RT-code>authored/ExampleGreet</RT-code>, and injects the appropriate namespace macros during compilation. 
+      </p>
+      <p>
+         The orchestrator compiles the <RT-code>.lib.c</RT-code> files into object files under <RT-code>scratchpad/build/object/</RT-code>, archives them into a library file, and links the <RT-code>.CLI.c</RT-code> objects into standalone executables. The final artifacts are placed in the <RT-code>scratchpad/made/</RT-code> directory.
+      </p>
+
+      <h1>Promoting the artifacts</h1>
+      <p>
+        Artifacts resting in the scratchpad are volatile and private to the developer. To share the executables and libraries with the rest of the project (such as the tester or consumer roles), the developer must promote them.
+      </p>
+      
+      <RT-code>
+        > promote write
+      </RT-code>
+
+      <p>
+        The <RT-code>promote</RT-code> tool compares the contents of <RT-code>developer/scratchpad/made/</RT-code> against <RT-code>consumer/made/</RT-code>. It atomically copies any new or updated files to the consumer workspace, stripping write permissions to enforce the immutability of the deployment target. Once promoted, the <RT-code>hello</RT-code> executable is ready for testing.
+      </p>
+
     </RT-article>
   </body>
 </html>