From: Thomas Walker Lynch Date: Mon, 22 Jun 2026 08:52:28 +0000 (+0000) Subject: Pascal case namespaces for build environment, RT -> RT-style for doc link X-Git-Url: https://git.reasoningtechnology.com/%27%20%20%20resolved_path%20%20%20%27?a=commitdiff_plain;h=refs%2Fheads%2Fcore_developer_branch;p=RT-style Pascal case namespaces for build environment, RT -> RT-style for doc link --- diff --git a/administrator/document/how-to_release.html b/administrator/document/how-to_release.html index e2e8a60..6bea02a 100644 --- a/administrator/document/how-to_release.html +++ b/administrator/document/how-to_release.html @@ -5,7 +5,7 @@ Release howto '); +}; diff --git a/developer/authored/Core.copy/utility.js b/developer/authored/Core.copy/utility.js new file mode 100644 index 0000000..d6f2ddd --- /dev/null +++ b/developer/authored/Core.copy/utility.js @@ -0,0 +1,109 @@ +/* + General utilities for the RT Style library. +*/ + +window.RT = window.RT || {}; + +// --- DEBUG SYSTEM --- +window.RT.debug = { + + // all debug messages enabled +/* + active_tokens: new Set([ + 'style', 'layout', 'pagination' + ,'selector', 'config', 'error' + ,'term' + ,'scroll' + ]), + + active_tokens: new Set([ + 'term' + ]), +*/ + + active_tokens: new Set([ + ]), + + log: function(token, message) { + if (this.active_tokens.has(token)) { + console.log(`[RT:${token}]`, message); + } + }, + + warn: function(token, message) { + if (this.active_tokens.has(token)) { + console.warn(`[RT:${token}]`, message); + } + }, + + error: function(token, message) { + console.error(`[RT:${token}] CRITICAL:`, message); + }, + + enable: function(token) { this.active_tokens.add(token); console.log(`Enabled: ${token}`); }, + disable: function(token) { this.active_tokens.delete(token); console.log(`Disabled: ${token}`); } +}; + +// --- UTILITIES --- +window.RT.utility = { + // --- FONT PHYSICS --- + measure_ink_ratio: function(target_font, ref_font = null) { + const debug = window.RT.debug; + debug.log('layout', `Measuring ink ratio for ${target_font}`); + + const canvas = document.createElement('canvas'); + const ctx = canvas.getContext('2d'); + + if (!ref_font) { + const bodyStyle = window.getComputedStyle(document.body); + ref_font = bodyStyle.fontFamily; + } + + const get_metrics = (font) => { + ctx.font = '100px ' + font; + const metrics = ctx.measureText('M'); + return { + ascent: metrics.actualBoundingBoxAscent, + descent: metrics.actualBoundingBoxDescent + }; + }; + + const ref_m = get_metrics(ref_font); + const target_m = get_metrics(target_font); + + const ratio = ref_m.ascent / target_m.ascent; + + return { + ratio: ratio, + baseline_diff: ref_m.descent - target_m.descent + }; + }, + + // --- COLOR PHYSICS --- + is_color_light: function(color_string) { + // 1. HSL Check + if (color_string.startsWith('hsl')) { + const numbers = color_string.match(/\d+/g); + if (numbers && numbers.length >= 3) { + const lightness = parseInt(numbers[2]); + return lightness > 50; + } + } + + // 2. RGB Check + const rgb = color_string.match(/\d+/g); + if (!rgb) { + return true; + } + + const r = parseInt(rgb[0]); + const g = parseInt(rgb[1]); + const b = parseInt(rgb[2]); + const luma = (r * 299 + g * 587 + b * 114) / 1000; + return luma > 128; + }, + + is_block_content: function(element) { + return element.textContent.trim().includes('\n'); + } +}; diff --git a/developer/authored/Document.copy/RT0 b/developer/authored/Document.copy/RT0 new file mode 120000 index 0000000..2a6dec2 --- /dev/null +++ b/developer/authored/Document.copy/RT0 @@ -0,0 +1 @@ +/home/Thomas/subu_data/developer/project/RT-style-JS_public/shared/linked-project/RT-style-JS_public/consumer/release/RT \ No newline at end of file diff --git a/developer/authored/Document.copy/style_manual.html b/developer/authored/Document.copy/style_manual.html new file mode 100644 index 0000000..41ff112 --- /dev/null +++ b/developer/authored/Document.copy/style_manual.html @@ -0,0 +1,420 @@ + + + + + RT Style System: Reference Manual + + + + + + + + + + + + + + Table of custom tags + +

Style tag reference

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TagDescription
<RT-article>Article container.
<RT-title> + Title block and metadata. +
<RT-TOC>Compiles TOC.
<RT-index>Compiles an alphabetical glossary of defined terms.
<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-footnote>Inline text to be extracted and rendered at the bottom of the page.
<RT-cite>Bibliographic citation marker.
<RT-ref>Dynamic cross reference to another element in the document.
<RT-page>Automatically inserted pagination container.
<RT-chapter>Chapter heading with implied page break.
<RT-page-break>Explicit page break directive. Must be explicitly closed.
+ + 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 meaning 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 invented." +

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

+ + + +

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

References, citations, and indexing

+ +

Footnotes

+

+ Use <RT-footnote> to author footnote content directly inline with the text it references. During the layout phase, the pagination engine extracts the text, replaces the element with an invisible structural marker, and compiles a formatted footnote container at the bottom of the active <RT-page>. +

+ +

Citations

+

+ Use <RT-cite> with the ref attribute to insert bibliographic citations. This ensures formatting remains consistent and separates citation data from standard prose. +

+ + ... formalized as Basic Law V . + + +

Dynamic cross referencing

+

+ A person authoring a technical document frequently refers back to tables, equations, or previous sections. Use <RT-ref target="element-id"> to link to specific content. This tag dynamically retrieves the numbering or caption of the target element, maintaining correct references even if preceding elements shift during editing. +

+ +

Glossary indexing

+

+ Use <RT-index> at the end of the document to compile a glossary. Similar to the TOC compiler, this tag scans the DOM for automatic definition anchors produced by the term module and generates an alphabetized list of defined terms and neologisms. +

+ + Navigation and layout + +

Automatic table of contents

+

+ Use <RT-TOC> to insert a compiled 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. +

+ + +

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 produces a standardized, styled header block with the document title and metadata. +

+ +

Attributes

+ + +

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

+ +

Manual page breaks and chapters

+

+ A person can assert explicit control over the layout engine using the <RT-page-break></RT-page-break> tag. This tag forces the engine to close the current page and push all subsequent content to the top of the next page. Standard HTML5 parsing requires this custom tag to be explicitly closed; self-closing syntax will fail. +

+

+ For major document divisions, use <RT-chapter>. The semantic processor translates this tag into an <RT-page-break> followed by an <h1 class="RT-chapter">. This ensures the chapter starts on a new page, inherits standard typography, and is automatically indexed by the TOC engine. +

+ + 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 are enabled or disabled in two ways: by editing the active_tokens set in utility.js, or at runtime by calling: +

+ + + window.RT.debug.enable('term') + window.RT.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. +

+ + + Manifest + + 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 conventions +

Headings are first letter capitalized. Remaining words are as they would be in English prose.

+ + Exercises + +
    +
  1. +

    + Term occurrences: If an author tags a word with <RT-term> five times in a document, how many times will the term be visually decorated by the styling engine? How does a person force the engine to decorate a later occurrence? +

    +
    2. +
  2. +

    + Term normalization: A person writes <RT-term>Parse Tree</RT-term> in paragraph one, and <RT-term>parse tree</RT-term> in paragraph two. Will the system assign a definition anchor to the second occurrence? +

    +
    3. +
  3. +

    + TOC compilation: What happens if a person places an <RT-TOC> tag without a level attribute before the first heading of a section? +

    +
    4. +
  4. +

    + Code and math formatting: How does the RT system determine whether to render an <RT-code> or <RT-math> element inline with the text versus as a standalone block? +

    +
    5. +
  5. +

    + Pagination logic: When the script bundles elements into an <RT-page> container, how does the soft limit pagination handle a heading that falls at the very bottom of the page capacity? +

    +
    6. +
+ + + + diff --git a/developer/authored/Element.copy/TOC.js b/developer/authored/Element.copy/TOC.js new file mode 100644 index 0000000..2f3bc6f --- /dev/null +++ b/developer/authored/Element.copy/TOC.js @@ -0,0 +1,162 @@ +/* + Processes tags. + Populates each with headings found below it. + + Attributes: + level="N" : Explicitly sets the target heading level (1-6). + e.g., level="1" collects H1s. level="2" collects H2s. + Stops collecting if it hits a heading of (level - 1) or higher. + + Default (No attribute): + Context Aware. Looks backwards for the nearest heading H(N). + Targets H(N+1). Stops at the next H(N). + +First heading 1 1 + First heading 2 2 + Next heading 2 2 +Next heading 2 3 + +*/ + +window.RT = window.RT || {}; + +window.RT.TOC = function(){ + const debug = window.RT.debug || { log: function(){} }; + const TOC_seq = document.querySelectorAll('rt-toc'); + + TOC_seq.forEach( (container ,TOC_index) => { + container.style.display = 'block'; + + // 1. Parse attribute: single number N or range A-B + const attr_val = container.getAttribute('level'); + let start_level, end_level; + + if (attr_val) { + const rangeMatch = attr_val.match(/^(\d)-(\d)$/); + if (rangeMatch) { + const a = parseInt(rangeMatch[1]); + const b = parseInt(rangeMatch[2]); + if (a >= 1 && a <= 6 && b >= 1 && b <= 6 && a <= b) { + start_level = a; + end_level = b; + if (debug.log) debug.log('TOC', `TOC #${TOC_index} range: H${a}-H${b}`); + } else { + if (debug.log) debug.log('TOC', `Invalid range "${attr_val}" → implicit mode`); + } + } else { + const single = parseInt(attr_val); + if (!isNaN(single) && single >= 1 && single <= 6) { + start_level = single; + end_level = single; + if (debug.log) debug.log('TOC', `TOC #${TOC_index} single level: H${single}`); + } else { + if (debug.log) debug.log('TOC', `Invalid level "${attr_val}" → implicit mode`); + } + } + } + + // 2. Implicit mode (no attribute or invalid) + if (start_level === undefined || end_level === undefined) { + let context_level = 0; + let prev = container.previousElementSibling; + while (prev) { + const match = prev.tagName.match(/^H([1-6])$/); + if (match) { + context_level = parseInt(match[1]); + break; + } + prev = prev.previousElementSibling; + } + const target_level = Math.min(context_level + 1, 6); + start_level = target_level; + end_level = target_level; + if (debug.log) debug.log('TOC', `TOC #${TOC_index} implicit target: H${target_level}`); + } + + // 3. Collect all matching headings until a higher-level heading stops us + const headings = []; + let next_el = container.nextElementSibling; + while (next_el) { + const match = next_el.tagName.match(/^H([1-6])$/); + if (match) { + const found_level = parseInt(match[1]); + + // Stop if we hit a heading that is a parent of the lowest level we collect + if (found_level < start_level) break; + + // Collect if within the requested range + if (found_level >= start_level && found_level <= end_level) { + // Ensure it has an id + if (!next_el.id) { + next_el.id = `TOC-ref-${TOC_index}-${found_level}-${headings.length}`; + } + headings.push({ el: next_el, level: found_level }); + } + } + next_el = next_el.nextElementSibling; + } + + // 4. Build the container (title + list) + container.innerHTML = ''; + const title = document.createElement('h1'); + title.textContent = start_level === 1 ? 'Table of Contents' : 'Section Contents'; + title.style.textAlign = 'center'; + container.appendChild(title); + + if (headings.length === 0) return; // nothing to show + + // Top-level list + const topList = document.createElement('ul'); + topList.style.listStyle = 'none'; + topList.style.paddingLeft = '0'; + container.appendChild(topList); + + // Stack of