From 162b82ad45664b39bbaf9211d698a884a0f2ad20 Mon Sep 17 00:00:00 2001 From: Thomas Walker Lynch Date: Tue, 10 Mar 2026 12:36:08 +0000 Subject: [PATCH] . --- consumer/release/document/style_manual.html | 648 ++++++++++---------- document/style_manual.html | 16 +- 2 files changed, 319 insertions(+), 345 deletions(-) diff --git a/consumer/release/document/style_manual.html b/consumer/release/document/style_manual.html index cf6e7f2..7503831 100644 --- a/consumer/release/document/style_manual.html +++ b/consumer/release/document/style_manual.html @@ -1,338 +1,320 @@ - - - RT Style System: Reference Manual - - - - - - - - - - - - - - - - - - - - - - - -

Table of Custom Tags

- -

Style Tag Reference

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Tag	Description
<RT-article>	Article container.
<RT-title>	- Title block and metadata. -
<RT-TOC>	Generates TOC.
<RT-term>	Conventional term.
<RT-term-em>	Forces emphasis for a term even after first occurrence.
<RT-neologism>	Project specific term.
<RT-neologism-em>	Forces emphasis for a neologism even after first occurrence.
<RT-code>	Code span or code block.
<RT-math>	Inline or block math.
<RT-page>	Automatically inserted pagination tag.

- -

Architecture Overview

- The RT Style System is a client-side, JavaScript-driven publishing framework designed to turn raw HTML into high-readability technical documentation. Unlike standard CSS frameworks, RT uses JavaScript to handle complex layout tasks like ink-ratio balancing and dynamic pagination. -

- -

The Orchestrator

- The core of the system is style_orchestrator.js. It is placed at the bottom of the HTML <body>. Its job is to: -

Detect which modules are already loaded.
Load missing modules (defaulting to Dark Theme if none is specified).
Execute the Semantics Phase (styling tags).
Wait for MathJax (if present).
Execute the Layout Phase (pagination, page rendering).
Reveal the document.

- -

Semantic Tags

- The system relies on a specific set of custom tags in the RT- namespace to separate structure from presentation. -

- -

Terminology

- -

Conventional Terms

- Use <RT-term> for standard, industry accepted technical terms. The system decorates only the first occurrence of each unique term so that the first appearance functions as a definition point, and later appearances do not overload the page with styling. -

- - -The Singleton Pattern restricts instantiation... - - -

- Renders as: The Singleton Pattern restricts instantiation... -

- -

Neologisms

- Use <RT-neologism> for terms invented specifically for the current document or project. Neologisms are styled more strongly than conventional terms, visually distinguishing "jargon you should know" from "jargon we just made up." -

- - -We define the Hyper Tape as a construct... - - -

- Renders as: We define the Hyper Tape as a construct... -

- -

First Occurrence Rule

- The term system is intentionally conservative. For the tags <RT-term> and <RT-neologism>, only the first occurrence of a unique term is decorated. Subsequent mentions are rendered as normal prose. -

- -

- Uniqueness is tracked by normalizing the term text (trimmed, then lowercased). This means that Symbol and symbol count as the same term. -

- -

Forced Emphasis Variants

- Sometimes a later mention of a term should be emphasized again. For that purpose, the system provides explicit emphasis tags: -

- -

<RT-term-em>
<RT-neologism-em>

- -

- These variants are always decorated, even if the term appeared earlier. -

- -

Automatic Definition Anchors

- For first occurrences, the term module automatically assigns an id attribute if one does not already exist. This creates stable anchors for future indexing and linking. -

- - -We define a Symbol as... - - -

- The first occurrence will be given an id similar to def-symbol. For neologisms, an additional marker is used, for example def-neo-hyper-tape. -

- -

Technical Content

- -

Code

- Use <RT-code>. If placed inline, it acts like a span. If placed as a block (with newlines), it acts like a pre formatted block with a theme aware border. -

- - -# Block Code Example -def hello(): - return "World" - - -

Mathematics

- Use <RT-math>. The system auto detects if it is a block equation or inline variable and wraps it in MathJax delimiters. -

- Inline: Let x be the input. -

- Block: -

- - f(x) = \sum_{i=0}^{n} x_i - - -

Navigation & Layout

- -

Automatic Table of Contents

- Use <RT-TOC> to insert a generated table of contents. The tag scans the document forward from its current position to collect headings. -

- -

Explicit Mode

- Use the level="N" attribute to target a specific heading depth. -

<RT-TOC level="1">: Collects all <h1> elements until the end of the document. Best for the main document index.
<RT-TOC level="2">: Collects all <h2> elements until it encounters the next <h1>. Best for chapter summaries.

- -

Implicit Mode

- If no level is specified, the TOC scans backwards to find the nearest heading (for example H1) and assumes you want to collect children one level deeper (for example H2). -

- Note: Implicit mode can fail if placed before the first heading of a section. Use explicit levels for robust results. -

- -

The Title Block

- Use <RT-title> as the first element in your <body> (before the article container). This tag generates a standardized, styled header block with the document title and metadata. -

- -

Attributes

title (Required): The main heading of the document.
author (Optional): The author's name. Renders in a bold accent color.
date (Optional): The publication or revision date.

- -

Example

- - - - - -

- Renders as: A centered, high contrast H1 followed by a serif styled metadata row containing the author and date. -

- -

The Article Container

- The root element must be <RT-article>. This is the boundary for the pagination logic. -

- -

Pagination

- The script paginate_by_element.js scans the article. It calculates the height of every element (including margins) and bundles them into <RT-page> elements. -

- Soft Limit Pagination: The system attempts to keep headers with their following paragraphs. It will break a page early rather than stranding a header at the bottom. -

- -

Debugging

- -

Debug Tokens

- RT provides a lightweight debug logging system in utility.js. Logging is controlled by a set of active debug tokens. Each log message is assigned a token, and the message prints only if that token is enabled. -

- -

- Examples of common tokens include style, layout, pagination, selector, config, and term. -

- -

How Logging is Gated

- Normal log and warning output are gated. The methods debug.log(token,message) and debug.warn(token,message) will print only when the token exists in debug.active_tokens. -

- -

- This prevents the console from being flooded during normal use, while still allowing deep visibility during development. -

- -

Errors are Always Printed

- Errors are treated differently. The method debug.error(token,message) always prints, regardless of token state. These messages represent failures that require attention. -

- -

Enabling and Disabling Tokens

- Tokens may be enabled or disabled in two ways: by editing the active_tokens set in utility.js, or at runtime by calling: -

- - -window.StyleRT.debug.enable('term') -window.StyleRT.debug.disable('term') - - -

- For example, the term system (RT_term.js) uses the term token. When that token is enabled, the module will print messages describing how terms were detected and which term definitions were assigned IDs. -

- -

Themes

- The system supports hot swapping themes by changing the script import in the head. -

Dark: style/theme_dark_gold.js (Default)
Light: style/theme_light_gold.js

- -

Manifest

- -1. style_orchestrator.js (Example/default footer script) -2. utility.js (Math/Color physics) -3. article_tech_ref.js (Typography and CSS injection) -4. RT_code.js (Code block logic) -5. RT_math.js (MathJax wrapper) -6. RT_term.js (Term styling) -7. RT_TOC.js (Navigation generator) -8. paginate_by_element.js (Page splitter) -9. page_fixed_glow.js (Visual page container) - - - + + + RT Style System: Reference Manual + - - + + + + + + + + +

Table of Custom Tags

+ +

Style Tag Reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Tag	Description
<RT-article>	Article container.
<RT-title>	+ Title block and metadata. +
<RT-TOC>	Generates TOC.
<RT-term>	Conventional term.
<RT-term-em>	Forces emphasis for a term even after first occurrence.
<RT-neologism>	Project specific term.
<RT-neologism-em>	Forces emphasis for a neologism even after first occurrence.
<RT-code>	Code span or code block.
<RT-math>	Inline or block math.
<RT-page>	Automatically inserted pagination tag.

+ +

Architecture Overview

+ The RT Style System is a client-side, JavaScript-driven publishing framework designed to turn raw HTML into high-readability technical documentation. Unlike standard CSS frameworks, RT uses JavaScript to handle complex layout tasks like ink-ratio balancing and dynamic pagination. +

+ +

Pulling style files into a document

Put `setup.js` in the directory, and include it at the top of the document, + `setup.js` points at the style files and is installation specific.

+ + +

Semantic Tags

+ The system relies on a specific set of custom tags in the RT- namespace to separate structure from presentation. +

+ +

Terminology

+ +

Conventional Terms

+ Use <RT-term> for standard, industry accepted technical terms. The system decorates only the first occurrence of each unique term so that the first appearance functions as a definition point, and later appearances do not overload the page with styling. +

+ + + The Singleton Pattern restricts instantiation... + + +

+ Renders as: The Singleton Pattern restricts instantiation... +

+ +

Neologisms

+ Use <RT-neologism> for terms invented specifically for the current document or project. Neologisms are styled more strongly than conventional terms, visually distinguishing "jargon you should know" from "jargon we just made up." +

+ + + We define the Hyper Tape as a construct... + + +

+ Renders as: We define the Hyper Tape as a construct... +

+ +

First Occurrence Rule

+ The term system is intentionally conservative. For the tags <RT-term> and <RT-neologism>, only the first occurrence of a unique term is decorated. Subsequent mentions are rendered as normal prose. +

+ +

+ Uniqueness is tracked by normalizing the term text (trimmed, then lowercased). This means that Symbol and symbol count as the same term. +

+ +

Forced Emphasis Variants

+ Sometimes a later mention of a term should be emphasized again. For that purpose, the system provides explicit emphasis tags: +

+ +

<RT-term-em>
<RT-neologism-em>

+ +

+ These variants are always decorated, even if the term appeared earlier. +

+ +

Automatic Definition Anchors

+ For first occurrences, the term module automatically assigns an id attribute if one does not already exist. This creates stable anchors for future indexing and linking. +

+ + + We define a Symbol as... + + +

+ The first occurrence will be given an id similar to def-symbol. For neologisms, an additional marker is used, for example def-neo-hyper-tape. +

+ +

Technical Content

+ +

Code

+ Use <RT-code>. If placed inline, it acts like a span. If placed as a block (with newlines), it acts like a pre formatted block with a theme aware border. +

+ + + # Block Code Example + def hello(): + return "World" + + +

Mathematics

+ Use <RT-math>. The system auto detects if it is a block equation or inline variable and wraps it in MathJax delimiters. +

+ Inline: Let x be the input. +

+ Block: +

+ + f(x) = \sum_{i=0}^{n} x_i + + +

Navigation & Layout

+ +

Automatic Table of Contents

+ Use <RT-TOC> to insert a generated table of contents. The tag scans the document forward from its current position to collect headings. +

+ +

Explicit Mode

+ Use the level="N" attribute to target a specific heading depth. +

<RT-TOC level="1">: Collects all <h1> elements until the end of the document. Best for the main document index.
<RT-TOC level="2">: Collects all <h2> elements until it encounters the next <h1>. Best for chapter summaries.

+ +

Implicit Mode

+ If no level is specified, the TOC scans backwards to find the nearest heading (for example H1) and assumes you want to collect children one level deeper (for example H2). +

+ Note: Implicit mode can fail if placed before the first heading of a section. Use explicit levels for robust results. +

+ +

The Title Block

+ Use <RT-title> as the first element in your <body> (before the article container). This tag generates a standardized, styled header block with the document title and metadata. +

+ +

Attributes

title (Required): The main heading of the document.
author (Optional): The author's name. Renders in a bold accent color.
date (Optional): The publication or revision date.

+ +

Example

+ + + + + +

+ Renders as: A centered, high contrast H1 followed by a serif styled metadata row containing the author and date. +

+ +

The Article Container

+ The root element must be <RT-article>. This is the boundary for the pagination logic. +

+ +

Pagination

+ The script paginate_by_element.js scans the article. It calculates the height of every element (including margins) and bundles them into <RT-page> elements. +

+ Soft Limit Pagination: The system attempts to keep headers with their following paragraphs. It will break a page early rather than stranding a header at the bottom. +

+ +

Debugging

+ +

Debug Tokens

+ RT provides a lightweight debug logging system in utility.js. Logging is controlled by a set of active debug tokens. Each log message is assigned a token, and the message prints only if that token is enabled. +

+ +

+ Examples of common tokens include style, layout, pagination, selector, config, and term. +

+ +

How Logging is Gated

+ Normal log and warning output are gated. The methods debug.log(token,message) and debug.warn(token,message) will print only when the token exists in debug.active_tokens. +

+ +

+ This prevents the console from being flooded during normal use, while still allowing deep visibility during development. +

+ +

Errors are Always Printed

+ Errors are treated differently. The method debug.error(token,message) always prints, regardless of token state. These messages represent failures that require attention. +

+ +

Enabling and Disabling Tokens

+ Tokens may be enabled or disabled in two ways: by editing the active_tokens set in utility.js, or at runtime by calling: +

+ + + window.StyleRT.debug.enable('term') + window.StyleRT.debug.disable('term') + + +

+ For example, the term system (RT_term.js) uses the term token. When that token is enabled, the module will print messages describing how terms were detected and which term definitions were assigned IDs. +

+ +

Themes

+ The system supports hot swapping themes by changing the script import in the head. +

Dark: style/theme_dark_gold.js (Default)
Light: style/theme_light_gold.js

+ +

Manifest

+ + 1. style_orchestrator.js (Example/default footer script) + 2. utility.js (Math/Color physics) + 3. article_tech_ref.js (Typography and CSS injection) + 4. RT_code.js (Code block logic) + 5. RT_math.js (MathJax wrapper) + 6. RT_term.js (Term styling) + 7. RT_TOC.js (Navigation generator) + 8. paginate_by_element.js (Page splitter) + 9. page_fixed_glow.js (Visual page container) + + + + + + diff --git a/document/style_manual.html b/document/style_manual.html index ebf70b4..7503831 100644 --- a/document/style_manual.html +++ b/document/style_manual.html @@ -87,18 +87,10 @@ The RT Style System is a client-side, JavaScript-driven publishing framework designed to turn raw HTML into high-readability technical documentation. Unlike standard CSS frameworks, RT uses JavaScript to handle complex layout tasks like ink-ratio balancing and dynamic pagination.

The Orchestrator

- The core of the system is style_orchestrator.js. It is placed at the bottom of the HTML <body>. Its job is to: -

Detect which modules are already loaded.
Load missing modules (defaulting to Dark Theme if none is specified).
Execute the Semantics Phase (styling tags).
Wait for MathJax (if present).
Execute the Layout Phase (pagination, page rendering).
Reveal the document.

Pulling style files into a document

Put `setup.js` in the directory, and include it at the top of the document, + `setup.js` points at the style files and is installation specific.

Semantic Tags

-- 2.20.1