apex-ruby 1.0.30 → 1.0.31

data/ext/apex_ext/apex_src/docs/IAL_FEATURES.md

@@ -1,210 +0,0 @@
-# Inline Attribute Lists (IALs) and Attribute List Definitions (ALDs)
-
-## Overview
-
-Apex supports Kramdown-style Inline Attribute Lists (IALs)
-and Attribute List Definitions (ALDs), allowing you to add
-HTML attributes to Markdown elements. This feature is
-available in **Kramdown** and **unified** modes.
-
-## Implementation Status
-
-✅ **Fully Implemented**
-
-### Block-Level IALs
-- ✅ Headings (on same line or next line)
-- ✅ Paragraphs
-- ✅ Lists (ordered and unordered)
-- ✅ Blockquotes
-- ✅ Code blocks
-- ✅ Tables
-
-### Inline IALs
-- ✅ Links
-- ✅ Images
-- ✅ Strong (bold) elements
-- ✅ Emphasis (italic) elements
-- ✅ Code spans
-- ✅ Nested inline elements
-
-### Attribute Types
-- ✅ IDs (`#id`)
-- ✅ Classes (`.class`, multiple classes supported)
-- ✅ Key-value pairs (`key="value"` or `key='value'` or
-
-  `key=value`)
-
-- ✅ Quoted and unquoted values
-- ✅ Escaped quotes in quoted values
-
-### ALDs (Attribute List Definitions)
-- ✅ ALD definition syntax (`{:ref-name: attributes}`)
-- ✅ ALD reference syntax (`{:ref-name}`)
-- ✅ Multiple references to same ALD
-- ✅ ALD extraction and lookup
-
-## Syntax Details
-
-### Block-Level IALs
-
-For block-level elements, IALs must appear immediately after
-the element (no blank line):
-
-```markdown
-Paragraph text.
-{: #para-id .class1 .class2 title="Title" lang="en"}
-
-```
-
-### Inline IALs
-
-For inline elements, IALs appear immediately after the
-element:
-
-```markdown
-[link](url){:.button title="Link Title"}
-**bold**{:.bold-style}
-*italic*{:.italic-style}
-`code`{:.code-class}
-
-```
-
-### Key-Value Pairs
-
-Supports three formats:
-
-- `key="value"` (double quotes)
-- `key='value'` (single quotes)
-- `key=value` (unquoted, no spaces)
-
-Examples:
-```markdown
-{: title="Important Note" lang="en" data-id="123"}
-{: title='Single Quotes' lang=en data-visible=true}
-
-```
-
-### ALDs
-
-Define once, reference multiple times:
-
-```markdown
-# Header 1
-{:my-style}
-
-# Header 2
-{:my-style}
-
-{:my-style: #section-title .important .highlight lang="en"}
-
-```
-
-## Technical Implementation
-
-### File: `src/extensions/ial.c`
-
-**Key Functions:**
-
-- `parse_ial_content()` - Parses IAL/ALD attribute strings
-- `apex_extract_alds()` - Extracts ALD definitions from text
-- `apex_process_ial_in_tree()` - Processes IALs in AST
-
-`process_span_ial_in_container()` - Recursive function for inline IALs
-
-- `find_ald()` - Looks up ALD references
-- `merge_attributes()` - Merges ALD attributes
-
-`attributes_to_html()` - Converts attributes to HTML string
-
-**Key Structures:**
-
-`apex_attributes` - Stores ID, classes, and key-value pairs
-
-- `ald_entry` - Linked list of ALD definitions
-
-### Element Matching
-
-The HTML renderer uses element indexing to correctly match
-attributes to elements, especially when multiple elements
-share the same fingerprint (e.g., same URL for links, same
-text for strong/emph elements).
-
-Separate counters are maintained for:
-
-- Links (`link_count`)
-- Images (`image_count`)
-- Strong (`strong_count`)
-- Emphasis (`emph_count`)
-- Code spans (`code_inline_count`)
-
-This ensures that when multiple links share the same URL,
-each one receives the correct attributes based on its
-position in the document.
-
-### Processing Order
-
-1. **Preprocessing**: ALDs are extracted from the text
-
-   before parsing
-
-2. **Parsing**: Markdown is parsed into AST by cmark-gfm
-3. **Postprocessing**: IALs are processed and attributes
-
-   attached to AST nodes
-
-4. **Rendering**: HTML is rendered with attributes injected
-
-   into tags
-
-### Recursive Processing
-
-Inline IALs are processed recursively to handle nested
-elements:
-
-- Paragraphs are processed first
-
-Then STRONG, EMPH, and LINK nodes are processed recursively
-
-This allows IALs to work with nested structures like `**bold with *italic*{:.nested} inside**{:.wrapper}`
-
-## Edge Cases Handled
-
-1. **Multiple elements with same URL/content**: Uses element
-
-   indexing to match correctly
-
-2. **Nested inline elements**: Recursive processing ensures
-
-   correct matching
-
-3. **Text after inline IAL**: IAL text is removed, following
-
-   text is preserved
-
-4. **Block-level spacing**: Proper space injection between
-
-   tag name and attributes
-
-5. **ALD references**: Simple word references (no `#`, `.`,
-
-   or `=`) are looked up as ALDs
-
-## Testing
-
-Comprehensive test coverage in `tests/test_runner.c`:
-
-Block-level IALs (headings, paragraphs, lists, blockquotes)
-
-- Inline IALs (links, images, strong, emphasis, code)
-- Key-value pairs
-- ALD definitions and references
-- Multiple IALs in same paragraph
-- Nested inline elements
-- Edge cases (whitespace, end of paragraph, etc.)
-
-## References
-
-[Maruku IAL Proposal](https://golem.ph.utexas.edu/~distler/maruku/proposal.html)
-
-[Kramdown IAL Documentation](https://kramdown.gettalong.org/syntax.html#block-ials)
-

data/ext/apex_ext/apex_src/docs/IAL_STATUS.md

@@ -1,344 +0,0 @@
-# IAL (Inline Attribute Lists) - Current Status
-
-## Overview
-
-Apex has **full support** for Kramdown Inline Attribute
-Lists (IAL) and Attribute List Definitions (ALDs). All
-features are implemented and working, including inline IALs
-for span-level elements.
-
-**Note:** This document is maintained for historical
-reference. For up-to-date documentation, see:
-
-[Wiki: Inline Attribute Lists](https://github.com/yourusername/apex.wiki/Inline-Attribute-Lists) (complete user guide)
-
-- [Docs: IAL Features](IAL_FEATURES.md) (technical
-
-  implementation details)
-
-## What Works ✅
-
-### Block-Level IAL (Following Line)
-
-IAL can be applied to blocks when placed on the line AFTER
-the block:
-
-```markdown
-## My Heading
-
-{: #custom-id .my-class}
-
-Paragraph text.
-{: #para-id .important}
-
-```
-
-**Supported blocks:**
-
-- ✅ Headings (H1-H6)
-- ✅ Paragraphs
-- ✅ Block quotes
-- ✅ Code blocks
-- ✅ Lists and list items
-- ✅ Tables (via IAL on following line)
-
-**Output:**
-
-```html
-<h2 id="custom-id" class="my-class">My Heading</h2>
-<p id="para-id" class="important">Paragraph text.</p>
-
-```
-
-### Attribute Types Supported
-
-- ✅ **IDs** - `#my-id`
-- ✅ **Classes** - `.class1 .class2`
-- ✅ **Key-value** - `key="value"` or `key='value'`
-- ✅ **ALD References** - `{:ref}` (if ALD defined)
-
-### Attribute List Definitions (ALD)
-
-```markdown
-{:note: .callout .callout-note #note-style}
-
-> This is a note
-{:note}
-
-```
-
-Works correctly!
-
-## What Now Works ✅ (Updated)
-
-### Inline IAL (Same Line for Headings)
-
-**NOW SUPPORTED:**
-
-```markdown
-## Heading {: #id .class}          ← ✅ Works
-
-```
-
-Headings can have IALs on the same line or the next line.
-
-### Span-Level IAL
-
-**NOW FULLY SUPPORTED:**
-
-```markdown
-This is [styled link](url){: .highlight} ← ✅ Works
-**bold text**{:.bold-style}              ← ✅ Works
-*italic text*{:.italic-style}            ← ✅ Works
-`code span`{:.code-class}                ← ✅ Works
-
-```
-
-All span-level elements (links, images, emphasis, strong,
-code) now support inline IALs.
-
-### Robust Element Matching ✅
-
-**FIXED:** The HTML renderer now uses **element indexing**
-with separate counters for each element type:
-
-- Links, images, strong, emphasis, and code spans each have
-
-  their own counter
-
-- Attributes are matched by element type and index position
-- Works correctly even when multiple elements share the same
-
-  URL or content
-
-**Example that now works:**
-
-```markdown
-Para 1.
-{: .first}
-
-Para 2.
-{: .second}
-
-```
-
-Both paragraphs correctly receive their attributes.
-
-## Current Implementation
-
-### Stage 1: AST Processing (`ial.c`)
-
-1. **Extract ALDs** - Find `{:ref: ...}` definitions and
-
-   store them
-
-2. **Process IAL Paragraphs** - Find `{: ...}` paragraphs
-
-**Extract Attributes** - Parse ID, classes, key-value pairs
-
-4. **Store in user_data** - Attach HTML attribute string to
-
-   node
-
-5. **Remove IAL Paragraphs** - Unlink and free pure IAL
-
-   paragraphs
-
-### Stage 2: HTML Rendering (`html_renderer.c`)
-
-1. **Collect Nodes** - Walk AST gathering nodes with
-
-   user_data, track element indices
-
-2. **Match by Type and Index** - Match HTML tags to AST
-
-   nodes using element type and index (✅ robust!)
-
-3. **Inject Attributes** - Insert attribute string into
-
-   opening tags with proper spacing
-
-4. **Skip Special Attrs** - Ignore `data-remove`,
-
-   `data-caption`, `colspan`, `rowspan`
-
-## Issues Resolved ✅
-
-### Issue 1: Element Matching - ✅ FIXED
-
-**Solution Implemented**: Element indexing with separate
-counters for each inline element type (links, images,
-strong, emphasis, code).
-
-**Result**: Reliable matching even when multiple elements
-share the same URL or content.
-
-### Issue 2: Inline Heading Syntax - ✅ FIXED
-
-**Solution Implemented**: IAL parsing for headings supports
-both same-line and next-line syntax.
-
-**Result**: `## Heading {: #id}` now works correctly.
-
-### Issue 3: Span-Level IAL - ✅ FIXED
-
-**Solution Implemented**: Recursive IAL processing for
-inline elements (links, images, strong, emphasis, code
-spans), including nested structures.
-
-**Result**: `[text]{: .class}`, `**bold**{:.style}`, and
-nested structures all work correctly.
-
-## Workarounds
-
-### For Headings
-
-Use the next-line syntax instead of inline:
-
-```markdown
-## My Heading
-
-{: #custom-id .header-class}
-
-```
-
-### For Emphasis/Spans
-
-Use raw HTML:
-
-```markdown
-This has <span class="highlight">styled content</span> inline.
-
-```
-
-Or use the HTML markdown attribute:
-
-```markdown
-<span markdown="span" class="highlight">*styled* content</span>
-
-```
-
-### For Multiple Elements
-
-Separate them with blank lines to improve matching:
-
-```markdown
-First paragraph.
-{: .first}
-
-Second paragraph.
-{: .second}
-
-Third paragraph.
-{: .third}
-
-```
-
-## Test Results
-
-### Working Tests
-
-```markdown
-# Test 1: Paragraph IAL
-Para.
-{: .works}
-→ <p class="works">Para.</p> ✅
-
-# Test 2: Heading IAL (next line)
-## Heading
-
-{: #works}
-→ <h2 id="works">Heading</h2> ✅
-
-# Test 3: Table IAL
-| A | B |
-|---|---|
-| 1 | 2 |
-
-{: .table-class}
-→ <table class="table-class">... ✅
-
-```
-
-### Previously Failing Tests (Now Working ✅)
-
-```markdown
-# Test 4: Inline heading IAL
-## Heading {: #works}
-→ <h2 id="works">Heading</h2> ✅
-
-# Test 5: Span IAL
-[text](url){: .works}
-→ <p><a href="url" class="works">text</a></p> ✅
-
-# Test 6: Multiple paragraphs
-Para 1.
-{: .first}
-Para 2.
-{: .second}
-→ Both get attributes correctly ✅
-
-```
-
-## Recommendations
-
-### For Production Use
-
-**DO:**
-
-- ✅ Use IAL on separate lines after blocks OR on same line
-
-  for headings
-
-- ✅ Use for headings, paragraphs, lists, blockquotes, tables
-- ✅ Use inline IALs for links, images, emphasis, strong,
-
-  code spans
-
-- ✅ Use ALDs for reusable attribute sets
-- ✅ Use key-value pairs for custom attributes
-- ✅ Test output to verify attributes applied (good practice)
-
-**DON'T:**
-
-- ❌ Put blank lines between block elements and their IALs
-
-  (IAL won't apply)
-
-- ❌ Use invalid attribute syntax (always use proper quotes
-
-  for values with spaces)
-
-## Comparison with Kramdown
-
-| Feature | Kramdown | Apex | Status |
-|---------|----------|------|--------|
-| Block IAL (next line) | ✅ | ✅ | ✅ Working |
-| Inline heading IAL | ✅ | ✅ | ✅ Implemented |
-| Span IAL | ✅ | ✅ | ✅ Implemented |
-| ALD (references) | ✅ | ✅ | ✅ Working |
-| All block types | ✅ | ✅ | ✅ Supported |
-| Key-value pairs | ✅ | ✅ | ✅ Supported |
-| Nested inline IALs | ✅ | ✅ | ✅ Supported |
-| Reliable matching | ✅ | ✅ | ✅ Fixed (element indexing) |
-
-## Conclusion
-
-IAL support is **fully functional and production-ready**.
-All Kramdown IAL features are implemented:
-
-- ✅ Block-level IALs (all block types)
-- ✅ Inline IALs (links, images, emphasis, strong, code)
-- ✅ Same-line and next-line syntax for headings
-- ✅ Attribute List Definitions (ALDs)
-- ✅ Key-value pairs
-- ✅ Nested inline elements
-- ✅ Robust element matching
-
-**Recommendation**: Ready for production use. For complete documentation, see [Wiki: Inline Attribute Lists](https://github.com/yourusername/apex.wiki/Inline-Attribute-Lists).
-
----
-
-*Last Updated: 2025-01-XX*
-*Status: Fully Implemented*
-