<li>A safe, predictable build and release workflow.</li>
</ol>
- <h1>Key Concepts</h1>
- <h2>Created vs. Made</h2>
+ <h1>Setup</h1>
+
+ <p>
+ Python programmers speak of <RT-term>virtual environment</RT-term> and <RT-term>activate</RT-term>. In contrast, <RT-term>Harmony</RT-term> users speak of <RT-term>roles</RT-term> and <RT-term>setup</RT-term>. Whatever the terminology, this is about setting up the environment by giving values to environment variables. In Python there is one set of environment variable values independent of user role. With Harmony there is a different set of variables depending on the role the user is taking on.
+ </p>
+
+ <p>
+ A person takes on a role by sourcing the top-level setup script and providing the target role. In a bash shell to take on the role of <RT-term>developer</RT-term> the command is: <RT-code>. setup developer</RT-code>, or <RT-code>source setup developer</RT-code>. As of this writing, the supported roles are: <strong>administrator</strong>, <strong>consumer</strong>, <strong>developer</strong>, and <strong>tester</strong>.
+ </p>
+
+ <p>
+ Behind the scenes, the <RT-code>setup</RT-code> script performs the following actions:
+ </p>
+
+ <ul>
+ <li>Sources the project-wide setup (<RT-code>shared/authored/setup</RT-code>) to establish the core environment variables (e.g., <RT-code>REPO_HOME</RT-code> and <RT-code>PROJECT</RT-code>).</li>
+ <li>Configures the <RT-code>PATH</RT-code> to include shared tools, library environments, and the specific <RT-code><role>/tool</RT-code> directory.</li>
+ <li>Changes the working directory into the specified role's workspace.</li>
+ <li>Sources the <RT-code><role>/tool/setup</RT-code> script. While the earlier steps apply the standard Harmony skeleton setup, this final step applies the role setup that is customized for this specific project.</li>
+ </ul>
+
+
+ <h1>Documentation</h1>
+ <p>Documentation is placed closest to the role it pertains to.</p>
+ <ul>
+ <li><RT-code>consumer/release/document/</RT-code> : Documentation for end-users of released code (e.g., man pages, application manuals, library API references).</li>
+ <li><RT-code>administrator/document/</RT-code> : Project-wide documentation covering structure, ontology, and workflow.</li>
+ <li><RT-code>developer/document/</RT-code> : Documentation for developers, including coding standards and internal API guides.</li>
+ <li><RT-code>tester/document/</RT-code> : Documentation for testers detailing test plans and tools.</li>
+ <li><RT-code>shared/document/</RT-code> : Documentation on installing and configuring shared tools.</li>
+ </ul>
+
+ <h1>Key concepts</h1>
+ <h2>Authored vs. Made</h2>
<p>
Harmony divides the world into two categories:
</p>
This separation protects authored material from accidental overwrite and makes build artifacts fully disposable.
</p>
- <h2>Semantic Paths</h2>
+ <h1>Top-Level repository layout</h1>
<p>
- Directory names in Harmony are not decorative. Each directory name is a <RT-term>property</RT-term> shared among files. A full path forms a semantic sentence describing those files.
+ A team member will source the project setup file to take on a role. As of this writing, the supported roles are: <RT-code>administrator</RT-code>, <RT-code>developer</RT-code>, <RT-code>tester</RT-code>, and <RT-code>consumer</RT-code>.
</p>
- <h1>Top-Level Repository Layout</h1>
+ <ul>
+ <li><RT-code>administrator/</RT-code> : Project-local tools and skeleton maintenance.</li>
+ <li><RT-code>developer/</RT-code> : Primary workspace for developers.</li>
+ <li><RT-code>tester/</RT-code> : Regression and validation workspace for testers.</li>
+ <li><RT-code>consumer/</RT-code> : Consumption workspace holding the <RT-code>consumer/release</RT-code> directory.</li>
+ <li><RT-code>shared/</RT-code> : Shared ecosystem tools and global environments.</li>
+ </ul>
+
+ <h1>The administrator work area</h1>
<p>
- A team member will source the project setup file to take on a role. As of this writing, the supported roles are: <RT-code>administrator</RT-code>, <RT-code>developer</RT-code>, <RT-code>tester</RT-code>, and <RT-code>consumer</RT-code>.
+ This directory holds the tools and documentation used to manage the project as a whole. It includes the HTML documentation for the project ontology and workflow, as well as project-local tools utilized by the administrator to maintain the Harmony skeleton.
</p>
+ <h1>The developer work area</h1>
+ <p>
+ This directory is entered by first going to the top-level directory of the project, then sourcing <RT-code>. setup developer</RT-code>.
+ </p>
<ul>
- <li><RT-code>administrator/</RT-code> — Project-local tools and skeleton maintenance.</li>
- <li><RT-code>developer/</RT-code> — Primary workspace for developers.</li>
- <li><RT-code>tester/</RT-code> — Regression and validation workspace for testers.</li>
- <li><RT-code>consumer/</RT-code> — Consumption workspace holding the <RT-code>release</RT-code> directory.</li>
- <li><RT-code>shared/</RT-code> — Shared ecosystem tools and global environments.</li>
+ <li><RT-code>authored/</RT-code> : Human-written source. Tracked by Git.</li>
+ <li><RT-code>made/</RT-code> : Tracked artifacts generated by tools (e.g., links to CLI entry points).</li>
+ <li><RT-code>experiment/</RT-code> : Try-it-here code. Short-lived spot testing.</li>
+ <li><RT-code>scratchpad/</RT-code> : Git-ignored directory. Holds all intermediate build outputs, including the <RT-code>stage</RT-code> directory for releases.</li>
+ <li><RT-code>tool/</RT-code> : Developer-specific tools (like the release and make scripts).</li>
</ul>
- <h1>The Consumer Tree</h1>
+ <h1>The tester work area</h1>
+ <p>
+ This directory is dedicated to formal testing, including regression suites. While a developer can run and keep informal spot tests in their <RT-code>experiment/</RT-code> directory, any experiment promoted to a formal test is moved here. This enforces the boundary between writing code and validating it.
+ </p>
+
+ <h1>The shared tree</h1>
+ <p>
+ This directory contains ecosystem tools and global environments available to all roles. This includes shared authored tools, as well as third-party installations (like Python virtual environments or compilers) required by the project.
+ </p>
+
+ <h1>The consumer tree</h1>
<p>
The <RT-code>consumer/release/</RT-code> tree is where developers put work product that is ready to be consumed. The entire <RT-code>consumer/release</RT-code> directory is git-ignored and treated as a transient deployment target.
</p>
<p>
- Artifacts arrive in the <RT-code>release/</RT-code> tree <em>only</em> when the developer invokes the <RT-code>release</RT-code> script, which performs a flat-copy from the developer's <RT-code>scratchpad/stage</RT-code> directory.
+ Artifacts arrive in the <RT-code>consumer/release/</RT-code> tree <em>only</em> when the developer invokes the release script, which performs a flat-copy from the developer's <RT-code>scratchpad/stage</RT-code> directory.
</p>
- <h1>The Developer Tree</h1>
+ <h1>Releases</h1>
<p>
- This directory is entered by first going to the top-level directory of the project, then sourcing <RT-code>. setup developer</RT-code>.
+ While the workflow document provides a deep dive, it is helpful to understand how directories relate to the concept of a release. There is a distinction between a developer release and a project release.
</p>
<ul>
- <li><RT-code>authored/</RT-code> — Human-written source. Tracked by Git.</li>
- <li><RT-code>made/</RT-code> — Tracked artifacts generated by tools (e.g., links to CLI entry points).</li>
- <li><RT-code>experiment/</RT-code> — Try-it-here code. Short-lived spot testing.</li>
- <li><RT-code>scratchpad/</RT-code> — Git-ignored directory. Holds all intermediate build outputs, including the <RT-code>stage</RT-code> directory for releases.</li>
- <li><RT-code>tool/</RT-code> — Developer-specific tools (like the <RT-code>release</RT-code> and <RT-code>make</RT-code> scripts).</li>
+ <li><strong>Developer Release:</strong> A developer releases when they determine a work product is ready for testing. They invoke a script to copy artifacts into the <RT-code>consumer/release/</RT-code> directory.</li>
+ <li><strong>Project Release:</strong> A project is released when the tester and other team members determine the code in the <RT-code>consumer/release/</RT-code> directory is fully validated and ready for end users. This is enacted by creating a release branch on the version control system (e.g., GitHub), not by moving files to another directory.</li>
</ul>
+ <h2>Directory names</h2>
+ <p>
+ Each directory name is a <RT-term>property</RT-term> shared among the files contained within it. Hence, a full path forms a semantic sentence describing each file within it.
+ </p>
+ <p>
+ Because a directory name represents a property, it is rarely plural. For example, when each and every file in a directory is a test, the directory is named <RT-code>test</RT-code>.
+ </p>
+ <p>
+ When a property name <em>is</em> plural, it describes something about the internal nature of each file. For instance, a directory named <RT-code>constants</RT-code> implies that each individual file inside it (say, <RT-code>physics.py</RT-code>, <RT-code>math.py</RT-code>, and <RT-code>cosmology.py</RT-code>) provides a collection of multiple constants.
+ </p>
+ <p>
+ The following list presents each property type in order of preference that we use when naming directories.
+ </p>
+ <ul>
+ <li><strong>Role Association</strong> (<RT-code>administrator</RT-code>, <RT-code>developer</RT-code>, <RT-code>tester</RT-code>, <RT-code>consumer</RT-code>): Identifies the persona, whether human or AI, intended to interact with the files.</li>
+ <li><strong>Provenance</strong> (<RT-code>authored</RT-code>, <RT-code>made</RT-code>): Indicates whether the file was created by an intellect or mechanically produced by a tool.</li>
+ <li><strong>Capability</strong> (<RT-code>tool</RT-code>, <RT-code>document</RT-code>, <RT-code>experiment</RT-code>): Describes the primary function or structural nature of the file.</li>
+ <li><strong>Lifecycle State</strong> (<RT-code>scratchpad</RT-code>, <RT-code>release</RT-code>): Denotes the persistence, volatility, or promotion status of the file.</li>
+ <li><strong>Tracking Status</strong> (<RT-code>tracked</RT-code>, <RT-code>untracked</RT-code>): Specifies the version control expectations for the artifacts.</li>
+ </ul>
+
+ <p>
+ In the Unix file system, a person must choose a single string to use as the directory name. Hence, we typically choose a primary property, though when needed, we use multiple property names separated by an underscore.
+ </p>
+
+ <h1>The version 2.2 Harmony directory tree</h1>
+ <RT-code>
+ 2026-03-07 10:38:58 Z [Harmony:administrator] Thomas_developer@StanleyPark
+ §/home/Thomas/subu_data/developer/project§
+ > tree Harmony
+ Harmony
+ ├── 0pus_Harmony
+ ├── administrator
+ │ ├── document
+ │ │ ├── 00_Project_Structure.html
+ │ │ ├── 01_Workflow_Build_Contract.html
+ │ │ ├── Harmony.md
+ │ │ └── setup.js
+ │ └── tool
+ │ ├── after_pull
+ │ ├── archive
+ │ ├── release
+ │ └── setup
+ ├── consumer
+ │ ├── scratchpad
+ │ └── tool
+ │ └── env
+ ├── developer
+ │ ├── authored
+ │ │ └── hello.cli.c
+ │ ├── document
+ │ │ ├── 02_RT_Code_Format.html
+ │ │ ├── 03_Naming_and_Directory_Conventions.html
+ │ │ ├── 04_Language_Addenda.html
+ │ │ ├── ontology.org
+ │ │ └── setup.js
+ │ ├── experiment
+ │ ├── made
+ │ ├── scratchpad
+ │ └── tool
+ │ ├── do_all
+ │ ├── make
+ │ ├── makefile
+ │ ├── release
+ │ └── setup
+ ├── LICENSE
+ ├── scratchpad
+ │ └── Harmony__79f9d52__2026-03-07_085628Z.tar
+ ├── setup
+ ├── shared
+ │ ├── authored
+ │ │ ├── scratchpad
+ │ │ ├── setup
+ │ │ ├── style
+ │ │ └── version
+ │ ├── document
+ │ │ ├── install_generic.org
+ │ │ ├── install_Python.org
+ │ │ └── setup.js
+ │ ├── made
+ │ ├── style_directory_dict.js
+ │ └── third_party
+ │ ├── RT-style-JS_public -> ../../../RT-style-JS_public/
+ │ └── upstream
+ └── tester
+ ├── authored
+ │ └── test_routine.sh
+ ├── RT_Format
+ │ ├── RT_Format
+ │ ├── RT_Format.el
+ │ ├── test_0_data.c
+ │ └── test_1_data.py
+ └── tool
+ └── setup
+ </RT-code>
+
</RT-article>
</body>
</html>
<RT-TOC level="1"></RT-TOC>
- <h1>Roles and Process</h1>
+ <h1>The Three Circular Loops</h1>
+ <ol>
+ <li><strong>Development Loop:</strong> Developers author code, run experiments, and promote work product to the <RT-code>consumer/release/</RT-code> directory via the <RT-code>release write</RT-code> script.</li>
+ <li><strong>Developer-Tester Loop:</strong> Testers validate release candidates and file issues. Developers address these and promote new candidates. (A single person can play both roles locally to speed this up).</li>
+ <li><strong>Release Branching Loop:</strong> Once a candidate meets the goals for a version, the tester creates a release branch (Major.Minor). Released code then has bugs filed against it, restarting the cycle.</li>
+ </ol>
<h2>Administrator Role</h2>
<p>Responsibilities:</p>
<ol>
<li>Setup the project directory and keep it in sync with the Harmony skeleton.</li>
- <li>Maintain the role environments, apart from the <RT-code><role>/tool/setup</RT-code> files which are owned by the respective role.</li>
- <li>Install and maintain shared tools.</li>
+ <li>Maintain role environments (apart from role-specific <RT-code>tool/setup</RT-code> files).</li>
+ <li>Install and maintain shared tools, addressing issues with the project workflow.</li>
+ </ol>
+
+ <h2>Consumer Role</h2>
+ <p>Responsibilities:</p>
+ <ol>
+ <li>Act as the end-user simulation environment.</li>
+ <li>Consume and deploy artifacts exclusively from the <RT-code>consumer/release/</RT-code> target.</li>
+ <li>Never author or modify code; strictly run local builds or deployments for architecture-specific testing.</li>
</ol>
<h2>Developer Role</h2>
<li>Execute the <RT-code>release write</RT-code> script to copy artifacts to <RT-code>consumer/release</RT-code> for consumption/testing.</li>
</ol>
+
<h2>Tester Role</h2>
<p>Responsibilities:</p>
<ol>
To enter a project, cd to the top-level directory and source the setup file for your 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 to have multiple terminal sessions or IDEs open, each running under a different role environment.
<p>
The <RT-code>consumer/release</RT-code> directory is strictly an untracked deployment target. No tools may rebuild during promotion, and no builds are run directly inside the release directory.
</p>
+
+ <h1>Separation of Roles</h1>
+ <p>
+ To maintain integrity, strict boundaries exist between workspaces:
+ </p>
+ <ul>
+ <li>A tester never patches code in the <RT-code>developer/</RT-code> directory. Instead, the tester files issues or proposes code fixes on a separate branch.</li>
+ <li>A developer never writes into the <RT-code>tester/</RT-code> directory. Instead, a developer adds tests to <RT-code>developer/experiment/</RT-code> and offers to share them.</li>
+ </ul>
+
</RT-article>
</body>
</html>
+++ /dev/null
-#+TITLE: 00 - Project Structure and Ontology
-#+AUTHOR: Harmony Project Team
-#+DATE: 2025-11-21
-#+OPTIONS: toc:2 num:nil
-
-#+HTML_HEAD_EXTRA: <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
-#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../style/rt_dark_doc.css">
-
-#+BEGIN_EXPORT html
-<div class="page">
-#+END_EXPORT
-
-* Purpose
-
-Harmony provides a language agnostic project directory structure and maintenance tools for long-lived, multi-person team software development. The structure exists to enforce:
-
-1. Clarity about where things live.
-1.1. Role based work areas
-1.2. Separation of skeleton, team member authored, machine-made, and third party installed software.
-3. A safe, predictable build and release workflow.
-
-A newcomer should be able to clone Harmony and understand the entire
-working model in minutes.
-
-To make a new project a toolsmith first clones Harmony, renames it to the project name, resets the history, and disconnects it from the Harmony project. The skeleton of the new project can be kept in sync with the Harmony skeleton by going to a Harmony skeleton clone and running the =Harmony/tool/sync= tool.
-
-Harmony is IDE agnostic. I typically use Emacs as an IDE and encourage its use. Because of this the documents standard format is emacs `.org` format. Files in this format can be exported to other formats, such as HTML. I have also used IntelliJ IDEA and Eclipse with Harmony, though the project skeleton has drifted some since then. I would like to update Harmony to work out of the box with these and other IDEs in the future.
-
-* 1. Key Concepts
-
-** Created vs. Made
-Harmony divides the world into two categories:
-
-- *Created / Authored*
- Human-written: source files, docs, design notes.
-
-- *Made*
- Tool-produced: binaries, generated sources, intermediates.
-
-This separation protects authored material from accidental overwrite and
-makes build artifacts fully disposable.
-
-** Semantic Paths
-Directory names in Harmony are not decorative.
-Each directory name is a *property* shared among files. Thus, a full path forms a semantic
-sentence describing said files.
-
-Example:
-
-- =developer/authored/=
- “Developer authored code”
-
-- =developer/scratchpad/made/=
- “Developer → scratch workspace → tool-made binaries”
-
-Once you learn the ontology, you can infer the meaning of any path.
-
-* Top-Level Repository Layout
-
-The layout below is stable across all Harmony skeleton based projects:
-
-| Directory | Meaning |
-|----------|---------|
-| =developer/= | Primary workspace for developers |
-| =tester/= | Regression and validation workspace for testers |
-| =tool/= | Project-local tools |
-| =shared/= | Shared ecosystem tools |
-| =document/= | Documentation (local to project) |
-| =release/= | Central Working Point for promoted artifacts |
-| =scratchpad/= | Global scratch (misc experiments) |
-| =env_* = | Role activators |
-
-The `env_*` files prepare PATH, set environment variables, and cd into
-the correct workspace. A team member will source one of the =env_*= files to take on a role in the project. As of this writing the supported roles are: toolsmith, developer, and tester.
-
-* The =release/= tree.
-
-The =release/= tree is where developers put work product that is to be shared with testers. Once the contents of the =release/= directory are blessed by the tester, the project will be given a release branch, and then the =release/= tree contains the files that are shared with users. Users should not be pulling files from anywhere else in the project tree.
-
-The =release/= tree is owned by the developer. No other role should write into this tree.
-
-Ideally, artifacts arrive in the =release/= tree *only* then the developer invokes the =promote= tool. And take note, The developer's =promote= script, as initially provided with the Harmony skeleton, has a command for erasing the contents of the release directory.
-
-** =release/made_tracked/=
- Architecture-agnostic artifacts. Tracked by Git, comes when the project is cloned. Users update the release directory when on a release branch, by pulling the project.
-
-** =release/made_untracked/=
- Architecture-specific artifacts. Directory tracked, contents are git ignored. The contents of this directory are created by running a build after the project is cloned/pulled. This was a compromise to avoid the problem of maintaining architecture and platform specific binaries.
-
-** =release/documnt/=
- Documents for users of the code in the release directory.
-
-* The =developer/= tree
-
-This property is set, i.e. this director is entered, by first going to the top level directory of the project, then sourcing the =env_developer= environment file. The developer can hook additional items into the environment by putting them into the =developer/tool/env= file.
-
-** =authored/=
- Human-written source. Tools should never delete files in this directory. =authored/= files are tracked.
-
-** =made/=
-
- Generated by tools, and the artifacts are tracked. These artifacts
- are stable across machine architectures. A common item to find in
- the =developer/made/= directory is a link to a Python program in
- the =authored/= directory. When following RT conventions the entry
- point of command line driven Python files is `CLI.py`, so the link
- in =developer/made/= gives the program a name.
-
-** =experiment/=
- Try-it-here code. Short-lived. Developers do spot testing here. If tests are to longer lived, they should be moved to the tester role.
-
-** =scratchpad/=
- Contents of this directory are git ignored. It is intended to hold all intermediate build outputs, and anything else the developer might consider scratchpad work.
-
-** =scratchpad/made/=
- By RT convention, architecture specific build artifacts are not tracked, but rather are built each time the project is cloned. Such build artifacts are placed in =developer/scratchpad/made= and if they are to be shared with the tester, the release script will release them to =release/made_untracted=.
-
-** =tool/=
- Developer specific tools. Additional tools will be found under =shared=. If the project is not self contained, then yet additional tools might come from the system environment.
-
-* Documents
-
-** =release/document/=
- Documentation for users of released code. E.g.s a =man= page, user manual for an application, or a reference manually for a released library.
-
-** =document/=
- Project wide documentation for project team members.
-
-** =developer/document/=
- Documentation for developers.
-
-** =tester/document/=
- Documentation for testers.
-
-** =shared/document/=
- Documentation on installing the shared tools. Note if a tool has a document directory that remains with the tool.
- This will typically have a list of tools that need to be installed for the project, and notes to help make installs go more smoothly.
-
-* Tools
-
-** =tool/=
-
-We call the team members who administer the project and install tools the 'toolsmith'. The top level =tool/= directory holds the toolsmith's tools.
-
-** =shared/=
-
-Shared tools are available to all team members. Those that have been written specifically for the Harmony skeleton or for this project go into the =shared/authored= directory. Note the tool =scratchpad=, try =scratchpat help=.
-
-Tools installed from third parties go into the git ignored directory =shared/third_party=.
-
-** =developer/tool=
-
-Developer role specific tools. The =release= script and the RT project shared =make= scripts are found here.
-
-** =tester/tool=
-
-Tester role specific tools.
-
-
-#+BEGIN_EXPORT html
-</div>
-#+END_EXPORT
+++ /dev/null
-#+TITLE: 01 - Workflow and Build Contract
-#+AUTHOR: RT
-#+DATE: 2025-11-21
-#+OPTIONS: toc:2 num:nil
-
-#+HTML_HEAD_EXTRA: <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
-#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../style/rt_dark_doc.css">
-
-#+BEGIN_EXPORT html
-<div class="page">
-#+END_EXPORT
-
-* Purpose
-The workflow contract defines the steps from authorship through release of work product.
-
-There are three circular loops.
-
-In the development loop, developers author code and run experiments, eventually then promoting work product to the =release/= directory.
-
-In the developer tester loop, testers test the promoted release candidates and file issues against them, developers address these, and then promote new release candidates. Or in a tighter version of this loop, a developer with a local copy of this project plays both roles so as to speed the cycle.
-
-In the third loop, the tester finds the release candidates to meet the goals for the release version, and to be of sufficient quality that they create a new release branch. Released code then has bug reports filed against it. Developers address these and the prior two loops are run until a new release candidate is stable, and a new release branch is made.
-
-Release branches have two integer numbers. The first number is the version of the software, as per the architectural specification. (That specification is placed into the project document directory.) The second number counts the number of times the tester has created a release branch for said version of the software.
-
-The workflow is designed for forward motion of through release numbers, so as to avoid having to maintain older releases separately. It is better to give a customer a new release if a bug must be fixed, even the customer will not pay for the new release, that it is to pay the cost of dealing with multi-release level bug fixes. However, as each release has its own branch, it is possible to perform multi-release level bug fixes if that is what is required or desired.
-
-* Roles and Process
-
-** Developer Role
-Responsibilities:
-
-1. Write and modify authored source. Ensure code meets RT style (see =02_RT_Code_Format.org=).
-2. Run builds.
-3. Spot testing in =experiment/=
-4. Promotes release candidates for more thorough testing using the customized =prommote= script.
-5. Rinse, lather, repeat.
-
-** Tester Role
-Responsibilities:
-
-1. Validate candidates under =release/=.
-2. Run regression suites.
-3. Approve for quality and completeness, and create release branches.
-
-** Toolsmith Role
-Responsibilities:
-
-1. Setup the project directory, and keep the project in sync with the Harmony skeleton.
-2. Maintain the role environments, apart from the =<role>/tool/env= files which are owned by the respective =<role>=.
-3. Install and maintained shared tools, =tool/= and =shared/=, and other tools upon request.
-4. Address issues with project workflow. Propose updates to the Harmony skeleton.
-
-
-* Entering the project
-
-What I do to enter a project is to first run an emacs shell. I cd to the project I want to work on, and then source the =env_toolsmith=, =env_developer=, or =env_tester= file, depending on which role I want to work in. Although sourcing these files affects the environment of the shell I am running, it does not effect the environment of emacs. Hence after sourcing the environment, I launch an IDE. This newly launched IDE will have a correct environment. For myself, these days, that new IDE will be emacs again.
-
-It is common that I will have two or three IDE's (emacs invocations) running side by side, each as different roles. Then I can write code, spot test it, promote it, then change to the other IDE and run regression tests. And if it is a phase of the project where tools are in flux, I will use the third IDE for modifying tools. Hence, as one person I will taken on three roles simultaneously, each in a different IDE.
-
-On a large project, chances are that all team members will be doing something similar to this on their local clones of the project. However, there will be team members concentrating on code development, and others on testing and release. Early on a toolsmith will setup the project, and then continue to maintain it.
-
-* Developer
-
-** Authoring and Building
-
-Developers write the build fodder files in the =authored/= directory. File name extensions are used to signal to the build tools how the build fodder is to be used. When the conventional single extension giving the main file type is not enough, two extensions are used.
-
-For example, with the default makefile for C, compiler fodder is found in the =authored/= directory, each file has one these file name extensions:
-
-- CLIs end in =.cli.c=
-- Libary code source end in =.lib.c=
-- Kernel module sources are =.mod.c=
-
-Fodder with the =.cli.c= extension is made into a stand alone executable.
-
-Fodder with =.lib.c= extension is compiled as an object file and added to the =lib<project>.a= archive. The =.cli.c= files are linkedin against said archive.
-
-Build tools never write into the =developer/authored= directory. Build products that are not to be tracked go on the =scratchpad/=. Those that are tracked go into the =developer/made= directory.
-
-It is expected that developers customize and add to the build scripts that come with the Harmony skeleton in order to fit their specific build needs. Note the Ariadne project for complex builds.
-
-** Developer Testing
-
-Spot tests are run in the =experiment/= directory. If the tests grow complex or are to be kept for the long term, move them to the tester environment.
-
-Once the developer finds the edits to be stable he or she can promote them. The promoted code is referred to as release candidates. Promoted release candidates can then be read by the tester role.
-
-As I mentioned, it is not uncommon for a team member to have two IDEs open, with one being in the developer environment, and one being in the tester environment, and then to bounce back and fourth between them.
-
-Once the release candidate code is stable, the developer can pull the remote repo, address merge conflicts, then push the local repo back. Merge conflicts on tracked release candidates are common as it is a bottleneck point in the code development.
-
-** Promotion for release
-
-As mentioned, files are promoted from the developer environment to the top level =release/= directory by the developer. The developer effects promotion for release by running the customized =developer/tool/promote= script, and then pushing the repository. Only a tester can actually perform a release.
-
-Building and promotion are separate activities.
-
-- No tool may rebuild during promotion.
-- Promotion is a copy-only operation.
-- No builds are run in the =release/= directory.
-
-If architecture specific files are to be part of the release, the developer will develop a =build_untracked= script and promote it into the =release/tool= directory. Then when a user clones a released project, as a second step the user will invoke the =release/tool/build_untracked= script. That script will fill in the =release/made_untracked= directory with code built specifically for the user's platform.
-
-- =release/documnt/= (documents for those who intend to use the work product)
-- =release/authored= (interpreter fodder - _none are run directly_)
-- =release/made_tracked/= (pushed to remote, pulled from remote, links into authored scripts)
-- =release/made_untracked/= (local-only)
-- =release/tool/= (=build_untracked= and other tools for maintaining released code)
-
-We chose the 'build after clone' approach over the 'thousand architecture specific binary release directories' approach, because maintaining many architecture release files became a maintenance problem. Note this new approach requires that third party tools be installed so that the =release/tool/build_untracked= script can run. This is the trade off cost for nothing having the thousand architecture directories.
-
-A user of the Harmony skeleton is free to customize the promotion tool and go back to multiple architecture specific binary release directories if that is what they want.
-
-Clearly if work product is intended to be distributed to lay users, there must be a deployment step after the release step, but we do not address this in these documents, as it this is not part of Harmony.
-
-
-* Tester
-
-The developer has promoted release candidates to the =release/= directory. He or she claims those represent a complete high quality product at the given release level. The testers are going to prove the developers to be wrong about that claim. If testers can't disprove this claim, the testers will make a release branch at the next minor release number for the given major release version.
-
-- The tester reads the spec, and writes a complete set of feature tests.
-
-- The tester uses the Mosaic test tool, and writes a set of tests, first for the individual functions that make up the program, then for functions in groups.
-
-- The tester accumulates tests for each bug that ever comes back on a release.
-
-- The tester collects tests from the developer when they are offered.
-
-- The tester writes other tests as he or she sees fit.
-
-- When the tests pass, one presumes, the tester will create a release branch.
-
-* Separation of roles.
-
-A tester never patches code in the =developer/= directory, instead the tester files issues. A tester could propose a code fix on another branch, and then point the developers at it in the issue report.
-
-A developer never writes into =tester/=, instead a developer adds to the =experiment/= and offers to share tests. A developer can propose tests on another branch, and then point testers at it.
-
-It is up the project manager how strict role assignments will be.
-
-As mentioned before, one person can play multiple roles. For example, it makes perfect sense for a developer with a local copy of the repo, to have an IDE open as a tester, so that he or she can run tests on release candidates before pushing them. However, in when doing this, the test code might be read only. The developer is merely running it and has no plans to push changes to it.
-
-#+BEGIN_EXPORT html
-</div>
-#+END_EXPORT
+++ /dev/null
-#+TITLE: 02 - RT Prescriptive Code Format Guide (Version 3)
-#+AUTHOR: Thomas Walker Lynch
-#+DATE: 2025-12-05
-#+OPTIONS: toc:2 num:nil
-
-#+HTML_HEAD_EXTRA: <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
-#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../style/rt_dark_doc.css">
-
-#+BEGIN_EXPORT html
-<div class="page">
-#+END_EXPORT
-
-* Purpose
-
-The goal is consistency, readability, and predictability across all
-languages and tools.
-
-This document covers:
-
-1. Naming conventions
-2. Object vs. Instance Nomenclature
-3. Vertical comma lists
-4. Enclosure spacing
-5. Line breaks and indentation
-6. Cross-language guidance
-
-* Object vs. Instance Nomenclature
-
-In the RT world, we reserve the word 'object' for its general English meaning, as its technical meaning in programming often causes confusion. When discussing data that is manipulated solely through a defined interface, use the term **instance**.
-
-- **Object:** Anything that can be described or reasoned about. A 'math object' is anything defined using mathematics, and a 'Python object' is anything that can be described with Python syntax.
-- **Instance:** Data that is only accessed or manipulated through a defined interface. This term is used to clearly denote data encapsulation and separation of concerns.
-
-
-* Identifer Naming Conventions
-
-** Identifier Naming
-
-- Types, modules: *PascalCase*
-- Functions, variables: *snake_case*
-- Globals: UPPER_SNAKE_CASE
-
-** Proper Noun and Acronyms
-
-Even in PascalCase and snake_case, they remain capitalized, as per the English language convention.
-
-E.g.s
-
-- IEEE_publication_count
-- person_Sara_novelties_list
-
-
-** Suffix Semantics
-Optionally suffixes are added to variable names to suggest type or interface.
-
-- =*_dp :: directory path, not specified if relative or absolute
-- =*_dpr :: relative directory path
-- =*_dpa :: absolute directory path
-
-- =*_fp :: file path, not specified if relative or absolute
-- =*_fpr :: relative file path
-- =*_fpa :: absolute file path
-
-If the file system node type is not specifically specified
-
-- =*_fs_nod_p :: file system node path, not specified if relative or absolute
-- =*_fs_nod_pr :: relative file system node path
-- =*_fs_nod_pa :: absolute file system node path
-
-- =*_list= :: generic ordered items
-- =*_seq= :: ordered items accessed by index
-
-- =*_map= :: a keyed container
-- =*_dict :: a keyed container
-
-- =*_count= :: number of elements
-- =*_flag= :: boolean
-
-- = *_Type :: names specific type, where the type name is given in PascalCase, as is the norm for types. E.g.s =name_Array= or =name_Map= for the cases that name is an instance of a defined Array or Map type.
-
-Add a container type suffix instead of making variables names plural. For example,
-
-- =name_seq= :: a sequence of zero or more names, used in place of =names=.
-
-
-* Comma separated list
-
-RT code format treats the comma in a list as belonging to the item that caused the comma to be needed.
-
-** Horizontal Comma List
-
-For lists on a single line, the comma is preceded by a space and abuts the item it follows.
-
-#+BEGIN_SRC c
- int x ,y ,z;
-#+END_SRC
-
-Note the space before the comma, and the comma abuts the item that caused the comma to be needed. This applies to language statements and data values alike.
-
-** Vertical Comma List
-
-For lists spanning multiple lines, the comma is placed *before* the item on the new line, aligned with the item's indentation.
-
-#+BEGIN_SRC c
-result = some_function(
- first_argument
- ,second_argument
- ,third_argument
-);
-#+END_SRC
-
-Example in Python:
-
-#+BEGIN_SRC python
-items = [
- first_item
- ,second_item
- ,third_item
-]
-#+END_SRC
-
-- Two-space indent.
-- Comma at column after indentation.
-- All items aligned except the first, as it does not have a comma before it.
-- This convention works identically across C, Python, Bash arrays, JSON-like data, etc.
-
-* Enclosure Spacing
-
-This rule applies on a line by line basis.
-
-** General Rules
-
-**No Space Between Adjacent Enclosures:** Generally, there is no space between adjacent enclosure punctuation (e.g., `f(g(x))`).
-
-** Single-Level Enclosures
-
-For enclosures that do not contain other enclosures (e.g., a simple `if(condition)`), there is **no space padding** inside the enclosure punctuation.
-
-Conforming:
-
-#+BEGIN_SRC c
-if(condition){
- do_something();
-}
-#+END_SRC
-
-Bad, non-conforming:
-
-#+BEGIN_SRC c
-if(condition) {
- do_something();
-}
-#+END_SRC
-
-Bad, non-conforming:
-
-#+BEGIN_SRC c
-if ( condition ) {
- do_something ( );
-}
-#+END_SRC
-
-** Multi-Level Enclosures
-
-For enclosures that contain other enclosures (e.g., `if( f(g(x)) )`), one space of padding is applied only to the **level one (outermost)** enclosure punctuation. All other levels follow the single-level rule (no padding).
-
-#+BEGIN_SRC c
-if( f(g(x)) ){
- do_something();
-}
-#+END_SRC
-
-In this example, the =if= has a three-level enclosure structure. The outermost parentheses of the =if= condition get one space of padding, while the inner parentheses for =f(...)= and =g(...)= get no padding.
-
-** Unmatched Enclosure Punctuation
-
-Format the enclosure punctuation that is present, as though it were matched. Treat an orphaned opening enclosure punctuation as though it were closed at the end of the line. Treat an extraneous closing, as though there were an opening at the beginning of the line.
-
-** Short Stuff Rule
-
-If a statement, such as an =if= block or a loop, can fit on a single line and is shorter than a reasonable line length (e.g., 40-60 characters), it should be kept on a single line without braces.
-
-#+BEGIN_SRC c
-if(x == 0) return;
-#+END_SRC
-
-* Indentation
-
-- Two spaces per indentation level.
-- Never use tabs.
-- Nest lines under the syntactic element that opened them.
-
-* Exercises
-
-To ensure a full understanding of the RT code format, please complete the following exercises.
-
-** Exercise 1: Comma and Function Call Formatting
-
-Reformat the following C code snippet to strictly adhere to the RT code format rules. Pay close attention to the horizontal and vertical comma lists, and the enclosure spacing for the function call.
-
-#+BEGIN_SRC c
-void my_function(int a, int b, int c) {
- int result = calculate_value(a, b, c);
- printf("Result: %d, a: %d, b: %d, c: %d\n", result, a, b, c);
-}
-
-result = my_function(
- rediculously_long_first_argument,
- rediculously_long_second_argument,
- rediculously_long_third_argument
-);
-#+END_SRC
-
-** Exercise 2: Multi-Level Enclosure and Short Stuff Rule
-
-Reformat the following C code snippet. The `if` statement should use the multi-level enclosure rule, and the `for` loop body should use the short stuff rule.
-
-#+BEGIN_SRC c
-if (check_permissions(user_id, file_path) && is_valid(file_path)) {
- for (int i = 0; i < 10; i++) {
- if (i % 2 == 0) {
- printf("Even: %d\n", i);
- }
- }
-}
-#+END_SRC
-
-#+BEGIN_EXPORT html
-</div>
-#+END_EXPORT
+++ /dev/null
-#+TITLE: 03 - Naming and Directory Conventions
-#+AUTHOR: RT
-#+DATE: 2025-11-21
-#+OPTIONS: toc:2 num:nil
-#+HTML_HEAD_EXTRA: <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
-#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../style/rt_dark_doc.css">
-
-#+BEGIN_EXPORT html
-<div class="page">
-#+END_EXPORT
-
-A directory name is taken a property for a set of files. Consequently, directory names are rarely plural. E.g. suppose we have a number of test files in a directory. The directory would be named =test=. As each file in the directory has the property of being a test.
-
-It would be nice if we could attach multiple properties to a file as part of the file system framework, but conventional file systems do not support this. Consequently, when needed, people add a second property to a file use dot extensions to the file's name. Hence, we get something like =sqrt.c= in a directory called =source=. So the first property is that the file is source code, and the second property is that it is C code.
-
-We could extent the dot suffix model of adding a property to file by using multiple dot suffixes. Our C makefile structure makes use of this.
-
-So what is a reasonable primary property for a set of files? Perhaps:
-
-- Who uses each file with this property. Home directories are named like this.
-- The role of the people using the file. This is a more generic version of the prior rule. The =developer= and =tester= directories were named in this manner.
-- What program are the files for. Thus we might name a directory a bunch of files for the cc compiler `cc`.
-- The generic category of program said files are for. Thus we end up with directories called =src= or =executable=.
-
-As for the names =src= and =executable= those come from times when almost all programs were compiled. We prefer instead the names =authored= and =made=. =authored= files are those written by humans (or these days, perhaps AI), while =made= files are products of tools. For a Python program, we put packages in =authored= with a module called =CLI.py= for the command line interface. Then we link from =made= into =authored= so as to give the program a name.
-
-The RT C coding environment does not use separate source and header files. Instead a variable is set that gates off the implementation if the source code is to be used as a header. Hence, all of our C source fits fine within and =authored= directory.
-
-
-
-#+BEGIN_EXPORT html
-</div>
-#+END_EXPORT
+++ /dev/null
-#+TITLE: 04 - Language Addenda (C, Python, Bash)
-#+AUTHOR: RT
-#+DATE: 2025-11-21
-#+OPTIONS: toc:2 num:nil
-#+HTML_HEAD_EXTRA: <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
-#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../style/rt_dark_doc.css">
-
-#+BEGIN_EXPORT html
-<div class="page">
-#+END_EXPORT
-
-
-* Purpose
-The RT code format is language-agnostic, but actual languages differ in
-syntax and constraints.
-
-This document explains how the RT rules are applied in:
-
-1. C
-2. Python
-3. Bash
-
-For each language we answer:
-
-1. What carries over directly from =02_RT_Code_Format.org=.
-2. What must be adapted.
-3. What extra discipline is required.
-
-* 1. C Addendum
-
-** 1.1 Control Structure and File Layout
-
-The detailed RT C file structure is described in the dedicated =
-RT_C_control_structure= document. The core ideas:
-
-1. Each module has an *Interface* section and an *Implementation*
- section in the same file.
-2. The sections are toggled using preprocessor macros (e.g. =FACE=).
-3. Interface declarations are processed even when included multiple
- times; the implementation is compiled only when used as an
- implementation.
-
-This approach:
-
-1. Keeps the interface and implementation in sync.
-2. Avoids maintaining parallel =.h= and =.c= files for each module.
-3. Integrates smoothly with standardized makefiles.
-
-** 1.2 Indentation and Comma Lists
-
-C code follows the RT two-space indentation and vertical comma lists:
-
-#+BEGIN_SRC c
-result = some_function(
- first_argument
- ,second_argument_with_longer_name
- ,third_argument
-);
-#+END_SRC
-
-Rules:
-
-1. Two spaces per block indentation.
-2. The comma starts the line in vertical lists.
-3. Align continuation lines under the first symbol after the equals
- sign or opening parenthesis when feasible.
-
-** 1.3 Error Handling and Ownership
-
-Guidelines:
-
-1. Functions should document ownership of pointers and lifetimes.
-2. Prefer explicit =*_count= parameters over sentinel values when
- passing arrays.
-3. Return codes should be consistent (=0= success, non-zero failure) or
- use clearly documented enums.
-
-* 2. Python Addendum
-
-** 2.1 Indentation and Layout
-
-Python enforces indentation syntactically, so the RT two-space rule
-becomes:
-
-1. Use *two-space indentation* for all Python code, even though four is
- common in the wider ecosystem.
-2. Vertical comma lists still place the comma at the start of the line,
- after the indentation.
-
-Example:
-
-#+BEGIN_SRC python
-items = [
- first_item
- ,second_item
- ,third_item
-]
-#+END_SRC
-
-** 2.2 Modules and CLI Separation
-
-Python scripts distinguish between:
-
-1. *Work functions* (importable API).
-2. *CLI entry points* (argument parsing, printing, exit codes).
-
-Pattern:
-
-1. Put reusable logic into functions and classes.
-2. Put argument parsing and =if __name__ == "__main__":= in the CLI
- section.
-3. Keep side effects out of import time.
-
-** 2.3 Error Handling
-
-1. Raise exceptions for exceptional conditions.
-2. Catch exceptions at the CLI boundary and convert them into user
- messages and exit codes.
-3. Avoid catching broad =Exception= unless it is immediately converted
- into a controlled failure.
-
-* 3. Bash Addendum
-
-** 3.1 Shebang and Safety
-
-Bash scripts should start with:
-
-#+BEGIN_SRC sh
-#!/usr/bin/env bash
-set -euo pipefail
-#+END_SRC
-
-Explanation:
-
-1. =-e= :: Exit on error.
-2. =-u= :: Treat unset variables as errors.
-3. =-o pipefail= :: Propagate errors across pipelines.
-
-** 3.2 Functions vs. Top-Level Code
-
-RT-style Bash separates:
-
-1. A small top-level CLI harness (argument parsing, usage, dispatch).
-2. A set of functions that implement the work.
-
-Pattern:
-
-1. Parse arguments into variables.
-2. Call a main function with explicit parameters.
-3. Avoid relying on global mutable state where possible.
-
-** 3.3 Logging and Diagnostics
-
-1. Use =printf= or =echo= for user-facing messages.
-2. Send debug or trace output to stderr (=>&2=).
-3. Make it obvious when the script is changing system state (e.g.
- mounting, creating users, modifying firewall rules).
-
-* 4. Using the Addenda
-
-When in doubt:
-
-1. Start with =02_RT_Code_Format.org= for the core rules.
-2. Apply the relevant language section here.
-3. If a language requires deviation from the generic rules, document
- that deviation in this file instead of ad-hoc decisions.
-
-#+BEGIN_EXPORT html
-</div>
-#+END_EXPORT
+++ /dev/null
-<!DOCTYPE html>
-<html lang="en">
- <head>
- <meta charset="UTF-8">
- <title>RT Prescriptive Code Format Guide</title>
- <script src="setup.js"></script>
- <script>
- window.StyleRT.include('RT/theme');
- window.StyleRT.include('RT/layout/article_tech_ref');
- </script>
- </head>
- <body>
- <RT-article>
- <RT-title
- author="Thomas Walker Lynch"
- date="2026-03-05"
- title="RT Prescriptive Code Format Guide (Version 4)">
- </RT-title>
-
- <RT-TOC level="1"></RT-TOC>
-
- <h1>Object vs. Instance Nomenclature</h1>
- <p>
- We reserve the word 'object' for its general English meaning. When discussing data that is manipulated solely through a defined interface, use the term <RT-term>instance</RT-term>.
- </p>
-
- <h1>Identifier Naming Conventions</h1>
- <ul>
- <li>Types, modules: <RT-code>PascalCase</RT-code></li>
- <li>Functions, variables: <RT-code>snake_case</RT-code></li>
- <li>Globals: <RT-code>UPPER_SNAKE_CASE</RT-code></li>
- </ul>
- <p>
- <em>Note for Lisp/elisp:</em> Use a hyphen <RT-code>-</RT-code> as the primary identifier separator. Use an underscore <RT-code>_</RT-code> to separate logically related portions of the identifier.
- </p>
- <p>
- <em>Note for C:</em> Use a center dot <RT-code>·</RT-code> for ad hoc namespaces within identifiers (e.g., <RT-code>TM·Arr</RT-code>). In Python, map this to an underscore (<RT-code>TM_Arr</RT-code>).
- </p>
-
- <h2>Suffix Semantics</h2>
- <p>Add a container type suffix instead of making variables names plural. Never use plurals.</p>
- <ul>
- <li><RT-code>*_dp</RT-code> : directory path</li>
- <li><RT-code>*_fp</RT-code> : file path</li>
- <li><RT-code>*_list</RT-code> : generic ordered items</li>
- <li><RT-code>*_count</RT-code> : number of elements</li>
- </ul>
-
- <h1>Comma Separated Lists</h1>
- <h2>Horizontal Comma List</h2>
- <p>The comma is preceded by a space and abuts the item it follows.</p>
- <RT-code>
-int x ,y ,z;
- </RT-code>
-
- <h2>Vertical Comma List</h2>
- <p>The comma is placed <em>before</em> the item on the new line, aligned with the item's indentation.</p>
- <RT-code>
-result = some_function(
- first_argument
- ,second_argument
- ,third_argument
-);
- </RT-code>
-
- <h1>Enclosure Spacing</h1>
- <h2>Single-Level Enclosures</h2>
- <p>No space padding inside the enclosure punctuation.</p>
- <RT-code>
-if(condition){
- do_something();
-}
- </RT-code>
-
- <h2>Multi-Level Enclosures</h2>
- <p>One space of padding is applied <em>only</em> to the outermost enclosure punctuation.</p>
- <RT-code>
-if( f(g(x)) ){
- do_something();
-}
- </RT-code>
-
- <h2>Short Stuff Rule</h2>
- <p>If a statement can fit on a single line and is short, keep it on a single line without braces.</p>
- <RT-code>
-if(x == 0) return;
- </RT-code>
-
- <h1>Indentation</h1>
- <ul>
- <li>Strictly two spaces per indentation level.</li>
- <li>Never use tabs.</li>
- <li>Nest lines under the syntactic element that opened them.</li>
- </ul>
- </RT-article>
- </body>
-</html>
<li>Globals: <RT-code>UPPER_SNAKE_CASE</RT-code></li>
</ul>
- <h2>Primary and Secondary Separators (snake-kebab_case)</h2>
- <p>
- If a language supports the hyphen (<RT-code>-</RT-code>) in identifiers (such as Common Lisp and Emacs Lisp), the identifier is written in <RT-code>snake-kebab_case</RT-code>. The hyphen is used as the primary word separator. The underscore (<RT-code>_</RT-code>) is then used as a secondary separator to denote logically related portions or namespace boundaries within the identifier.
- </p>
- <p>
- Otherwise, if the language does not support hyphens in identifiers (such as C, Python, and Java), the identifier falls back to standard <RT-code>snake_case</RT-code> and only the underscore (<RT-code>_</RT-code>) is used for all separation. In C specifically, a center dot (<RT-code>·</RT-code>) is used for ad hoc namespaces.
- </p>
+ <h2>Proper Nouns and Acronyms</h2>
+ <p>
+ Even in <RT-code>PascalCase</RT-code> and <RT-code>snake_case</RT-code>, proper nouns and acronyms remain capitalized, as per standard English language conventions (e.g., <RT-code>IEEE_publication_count</RT-code>).
+ </p>
- <h2>Suffix Semantics</h2>
- <p>Add a container type suffix instead of making variable names plural. Never use plurals.</p>
- <ul>
- <li><RT-code>*_dp</RT-code> : directory path</li>
- <li><RT-code>*_fp</RT-code> : file path</li>
- <li><RT-code>*_list</RT-code> : generic ordered items</li>
- <li><RT-code>*_count</RT-code> : number of elements</li>
- </ul>
+ <h2>Expanded Suffix Semantics</h2>
+ <p>Add a container or type suffix instead of making variable names plural. Never use plurals.</p>
+ <ul>
+ <li><RT-code>*_dp</RT-code> : directory path</li>
+ <li><RT-code>*_dpr</RT-code> / <RT-code>*_dpa</RT-code> : relative / absolute directory path</li>
+ <li><RT-code>*_fp</RT-code> : file path</li>
+ <li><RT-code>*_fpr</RT-code> / <RT-code>*_fpa</RT-code> : relative / absolute file path</li>
+ <li><RT-code>*_fs_nod_p</RT-code> : file system node path (when type is unspecified)</li>
+ <li><RT-code>*_list</RT-code> / <RT-code>*_seq</RT-code> : generic ordered items / indexed items</li>
+ <li><RT-code>*_map</RT-code> / <RT-code>*_dict</RT-code> : keyed containers</li>
+ <li><RT-code>*_count</RT-code> : number of elements</li>
+ <li><RT-code>*_flag</RT-code> : boolean</li>
+ </ul>
+
+ <h2>Primary and Secondary Separators (snake-kebab_case)</h2>
+ <p>
+ If a language supports the hyphen (<RT-code>-</RT-code>) in identifiers (such as Common Lisp and Emacs Lisp), the identifier is written in <RT-code>snake-kebab_case</RT-code>. The hyphen is used as the primary word separator. The underscore (<RT-code>_</RT-code>) is then used as a secondary separator to denote logically related portions or namespace boundaries within the identifier.
+ </p>
+ <p>
+ Otherwise, if the language does not support hyphens in identifiers (such as C, Python, and Java), the identifier falls back to standard <RT-code>snake_case</RT-code> and only the underscore (<RT-code>_</RT-code>) is used for all separation. In C specifically, a center dot (<RT-code>·</RT-code>) is used for ad hoc namespaces.
+ </p>
+
+ <h2>Suffix Semantics</h2>
+ <p>Add a container type suffix instead of making variable names plural. Never use plurals.</p>
+ <ul>
+ <li><RT-code>*_dp</RT-code> : directory path</li>
+ <li><RT-code>*_fp</RT-code> : file path</li>
+ <li><RT-code>*_list</RT-code> : generic ordered items</li>
+ <li><RT-code>*_count</RT-code> : number of elements</li>
+ </ul>
<h1>Comma Separated Lists</h1>
- <h2>Horizontal Comma List</h2>
- <p>The comma is preceded by a space and abuts the item it follows.</p>
- <RT-code>
-int x ,y ,z;
- </RT-code>
- <h2>Vertical Comma List</h2>
- <p>The comma is placed <em>before</em> the item on the new line, aligned with the item's indentation.</p>
- <RT-code>
-result = some_function(
- first_argument
- ,second_argument
- ,third_argument
-);
- </RT-code>
+ <h2>Horizontal Comma List</h2>
+ <p>The comma is preceded by a space and abuts the item it follows.</p>
+ <RT-code>
+ int x ,y ,z;
+ </RT-code>
+
+ <h2>Vertical Comma List</h2>
+ <p>The comma is placed <em>before</em> the item on the new line, aligned with the item's indentation.</p>
+ <RT-code>
+ result = some_function(
+ first_argument
+ ,second_argument
+ ,third_argument
+ );
+ </RT-code>
<h1>Enclosure Spacing</h1>
- <h2>Single-Level Enclosures</h2>
- <p>No space padding inside the enclosure punctuation.</p>
- <RT-code>
-if(condition){
- do_something();
-}
- </RT-code>
- <h2>Multi-Level Enclosures</h2>
- <p>One space of padding is applied <em>only</em> to the outermost enclosure punctuation.</p>
- <RT-code>
-if( f(g(x)) ){
- do_something();
-}
- </RT-code>
+ <h2>Single-Level Enclosures</h2>
+ <p>No space padding inside the enclosure punctuation.</p>
+ <RT-code>
+ if(condition){
+ do_something();
+ }
+ </RT-code>
- <h2>Short Stuff Rule</h2>
- <p>If a statement can fit on a single line and is short, keep it on a single line without braces.</p>
- <RT-code>
-if(x == 0) return;
- </RT-code>
+ <h2>Multi-Level Enclosures</h2>
+ <p>One space of padding is applied <em>only</em> to the outermost enclosure punctuation.</p>
+ <RT-code>
+ if( f(g(x)) ){
+ do_something();
+ }
+ </RT-code>
+
+ <h2>Short Stuff Rule</h2>
+ <p>If a statement can fit on a single line and is short, keep it on a single line without braces.</p>
+ <RT-code>
+ if(x == 0) return;
+ </RT-code>
<h1>Indentation</h1>
<ul>
<li>Never use tabs.</li>
<li>Nest lines under the syntactic element that opened them.</li>
</ul>
+
+ <h2>Example: The CLI Pattern</h2>
+ <p>Here is an example demonstrating the separation of work logic from the command line interface.</p>
+ <RT-code>
+ def calculate_area(length ,width):
+ # The Work Function. Pure logic. Reusable by any other module.
+ return length * width
+
+ def CLI():
+ # The Command Line Interface. Parses strings, calls work, handles output.
+ import sys
+
+ if len(sys.argv) < 3:
+ print("Usage: ./area.py <len> <width>")
+ sys.exit(1)
+
+ # Parse Strings -> Native Types
+ l = int(sys.argv[1])
+ w = int(sys.argv[2])
+
+ # Invoke Work
+ result = calculate_area(l ,w)
+
+ # Output
+ print(f"Area: {result}")
+
+ if __name__ == "__main__":
+ CLI()
+ </RT-code>
+
+ <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.
+ </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>
+ <li><strong>CLI Function:</strong> The bridge between the OS and the Work Function. It is always named <RT-code>CLI()</RT-code>. It parses string arguments into native types, calls the Work Function, formats the output for the user, and translates exceptions into exit codes.</li>
+ </ul>
+ <p>When a module is executed directly, the only top-level action should be calling <RT-code>CLI()</RT-code>.</p>
+
+ <h1>Exercises</h1>
+ <p>To ensure a full understanding of the RT code format, please complete the following exercises.</p>
+
+
+ <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. Pay close attention to the horizontal and vertical comma lists, and the enclosure spacing for the function call.</p>
+ <RT-code>
+ void my_function(int a, int b, int c) {
+ int result = calculate_value(a, b, c);
+ printf("Result: %d, a: %d, b: %d, c: %d\n", result, a, b, c);
+ }
+
+ result = my_function(
+ rediculously_long_first_argument,
+ rediculously_long_second_argument,
+ rediculously_long_third_argument
+ );
+ </RT-code>
+
+ <h2>Exercise 2: Multi-Level Enclosure and Short Stuff Rule</h2>
+ <p>Reformat the following C code snippet. The <RT-code>if</RT-code> statement should use the multi-level enclosure rule, and the <RT-code>for</RT-code> loop body should use the short stuff rule.</p>
+ <RT-code>
+ if (check_permissions(user_id, file_path) && is_valid(file_path)) {
+ for (int i = 0; i < 10; i++) {
+ if (i % 2 == 0) {
+ printf("Even: %d\n", i);
+ }
+ }
+ }
+ </RT-code>
+
</RT-article>
</body>
</html>
As for the names <RT-code>src</RT-code> and <RT-code>executable</RT-code>, those come from times when almost all programs were compiled. We prefer instead the names <RT-code>authored</RT-code> and <RT-code>made</RT-code>. <RT-code>authored</RT-code> files are those written by humans (or these days, perhaps AI), while <RT-code>made</RT-code> files are products of tools. For a Python program, we put packages in <RT-code>authored</RT-code> with a module called <RT-code>CLI.py</RT-code> for the command line interface. Then we link from <RT-code>made</RT-code> into <RT-code>authored</RT-code> so as to give the program a name.
</p>
+ <p>
+ Hence, with the default makefile for C, compiler fodder is found in the <RT-code>authored/</RT-code> directory. File name extensions are used to signal to the build tools how the file is to be processed:
+ </p>
+ <ul>
+ <li><RT-code>.cli.c</RT-code> : Fodder made into a stand-alone executable.</li>
+ <li><RT-code>.lib.c</RT-code> : Library code source, compiled as an object file and added to the project archive.</li>
+ <li><RT-code>.mod.c</RT-code> : Kernel module sources.</li>
+ </ul>
+
<p>
The RT C coding environment does not use separate source and header files. Instead, a variable is set that gates off the implementation if the source code is to be used as a header. Hence, all of our C source fits fine within an <RT-code>authored</RT-code> directory.
</p>
+++ /dev/null
-window.RT_REPO_ROOT = "../";
-document.write('<script src="' + window.RT_REPO_ROOT + 'shared/style_directory_dict.js"></script>');
-document.write('<script src="' + window.RT_REPO_ROOT + 'shared/third_party/RT-style-JS_public/consumer/release/RT/core/loader.js"></script>');
-document.write('<script src="' + window.RT_REPO_ROOT + 'shared/third_party/RT-style-JS_public/consumer/release/RT/core/body_visibility_hidden.js"></script>');
+++ /dev/null
-
- body {
- font-family: 'Noto Sans JP', Arial, sans-serif;
- background-color: hsl(0, 0%, 0%);
- color: hsl(42, 100%, 80%);
- padding: 2rem;
- }
- .page {
- padding: 3rem;
- margin: 1.25rem auto;
- max-width: 46.875rem;
- background-color: hsl(0, 0%, 0%);
- box-shadow: 0 0 0.625rem hsl(42, 100%, 50%);
- }
- h1 {
- font-size: 1.5rem;
- text-align: center;
- color: hsl(42, 100%, 84%);
- text-transform: uppercase;
- margin-top: 1.5rem;
- }
- h2 {
- font-size: 1.25rem;
- color: hsl(42, 100%, 84%);
- text-align: center;
- margin-top: 2rem;
- }
- h3 {
- font-size: 1.125rem;
- color: hsl(42, 100%, 75%);
- margin-top: 1.5rem;
- }
- p, li {
- color: hsl(42, 100%, 90%);
- text-align: justify;
- margin-bottom: 1rem;
- }
- code {
- font-family: 'Courier New', Courier, monospace;
- background-color: hsl(0, 0%, 25%);
- padding: 0.125rem 0.25rem;
- color: hsl(42, 100%, 90%);
- }
-
projects / Harmony / commitdiff