Dings-Feature-Render-Ir-Html

I am a Feature.

Also

- I am a Todo.

- I am a Work-Item.

About

• My State is Done.

Design-Context

This Work-Item uses the following Design-Context:

• All-Dings-Overview
• All-Dings-HLD
• All-Dings-LLD
• Dings-English
• Dings-Coding-Style

The Design-Documentation Structure was introduced by:

• Dings-Feature-Design

The Design-Context should be provided to ChatGPT and Codex when working on this Work-Item.

Start-Situation

The Dings-System already has a dings-gpt render Command, that renders between Dings-Channels.

The current Render-Channels are:

• Md
• Ir
• Sm1
• Sm2

The current Render-Paths include:

• Md-Ir
• Md-Sm1
• Md-Sm2
• Ir-Md
• Ir-Sm1
• Ir-Sm2
• Sm1-Sm2

The old Html Generation is currently available through:

• dings html generate -a

The old Html Generation renders the Markdown-Document-View (Work-Dir) to Html (Day) and adds Presentation Elements, for Example a Side-Bar.

Goal

The Goal of this Work-Item is to add Html as a new Render-Target for dings-gpt render.

The first new Render-Path shall be:

• Ir-Html

The Html Generation shall be based on the existing Ir Layer, because the Ir Layer already contains the parsed Document-Structure.

This avoids parsing Markdown again in the Html Renderer.

Design-Decision

The first Html Render-Path is Ir-Html, not Md-Html.

The intended Pipeline is:

Md -> Ir -> Html

The Responsibilities are:

• Md-Ir: Parse Markdown-Files into structured Ir Files.
• Ir-Html: Render structured Ir Files into Html Files.

Scope

This Work-Item includes:

• Add the Html Render-Channel.
• Add the Ir-Html Render-Path.
• Render Ir Document-Structure to Html.
• Preserve the existing Human-readable Document-View.
• Preserve or rebuild the existing Html Presentation Elements, for Example Side-Bar and Links.
• Preserve numbered Display-Math Equations from the legacy Html Generator.
• Add Help-Text for the new Render-Path.
• Add Use-Cases for Ir-Html.
• Update All-Dings-HLD, if the high-level Render-Model changes.
• Update All-Dings-LLD, if Render-Paths, Files or Commands change.

Non-Goals

This Work-Item does not implement a semantic Html View from sm1 or sm2.

The following Render-Paths are possible Future Work, but are not part of this Work-Item:

• Sm1-Html
• Sm2-Html

This Work-Item does not directly embed full sm1 or sm2 Semantic-Data into the generated Html Files.

This Work-Item does not remove the old dings html generate -a Command, unless this is required for a clean Migration.

Implementation Result: dings-gpt render Ir-Html is the Html Render-Path used by the current make render Flow. The legacy dings html generate -a Command remains available.

Html Views

The first Html View is the Document-View.

The Document-View is based on the Ir Document-Structure and renders:

• Headings
• Paragraphs
• Lists
• Links
• Images
• Code-Blocks
• Anchors
• Inline Code
• Inline Emphasis and Strong
• Inline and Display Math
• Numbered Display-Math Equations
• Block-Quotes
• Tables
• Presentation Elements

Later semantic Html Views may render or embed:

• Explicit Document-Truth from sm1
• Derived Semantic-View from sm2
• Names
• Classes
• Relations
• Claims

Command-Line-Interface

The intended new Command is:

dings-gpt render Ir-Html

Compatibility Syntax should follow the existing dings-gpt render Rules, for Example:

dings-gpt render 'Ir->Html'
dings-gpt render Ir Html

If Selection-Support exists or is added, single Dings-Objects may be rendered explicitly.

The default Behavior should be consistent with the existing dings-gpt render Command.

Use-Cases

Executable Use-Cases for this Work-Item should be stored in:

• 300101006.use-cases.bash

The Use-Cases should cover at least:

• Render all Ir Files to Html.
• Render one selected Dings-Object to Html, if Selection-Support exists.
• Verify that generated Html Files exist.
• Verify that Headings, Links and Anchors are rendered.
• Verify that numbered Display-Math Equations are rendered with the Number on the right.
• Verify that the Help-Text documents Ir-Html.

Acceptance-Criteria

This Work-Item is done when:

• dings-gpt render knows the Html Channel.
• dings-gpt render supports the Ir-Html Render-Path.
• Ir-Html renders Html from existing Ir Files.
• The generated Html contains the relevant Document-Structure.
• The generated Html preserves important Presentation Elements.
• The generated Html preserves numbered Display-Math Equations.
• The Help-Text documents the new Render-Path.
• Use-Cases for Ir-Html exist.
• All-Dings-HLD is updated, if needed.
• All-Dings-LLD is updated, if needed.