RubyGems - apex-ruby - Versions diffs - 1.0.29 → 1.0.31 - Mend

apex-ruby 1.0.29 → 1.0.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (490) hide show

data/ext/apex_ext/apex_src/docs/USER_GUIDE.md DELETED Viewed

@@ -1,803 +0,0 @@
-# Apex User Guide
-**Version 0.1.0**
-Apex is a unified Markdown processor that combines the best
-features of CommonMark, GitHub Flavored Markdown,
-MultiMarkdown, and Kramdown into a single, fast, C-based
-processor.
-## Quick Start
-### Installation
-```bash
-# Build from source
-git clone [apex-repo-url]
-cd apex
-mkdir build && cd build
-cmake ..
-make
-sudo make install
-```
-### Basic Usage
-```bash
-# Convert a file
-apex document.md > output.html
-# From stdin
-cat document.md | apex > output.html
-# Specify processor mode
-apex --mode gfm document.md
-apex --mode multimarkdown document.md
-```
-## Processor Modes
-Apex supports multiple processor modes for compatibility
-with different Markdown flavors:
-### CommonMark Mode (`--mode commonmark`)
-Pure CommonMark specification compliance. No extensions.
-```bash
-apex --mode commonmark document.md
-```
-### GFM Mode (`--mode gfm`)
-GitHub Flavored Markdown with:
-- Tables
-- Strikethrough (~~text~~)
-- Task lists (- [ ] Todo)
-- Autolinks
-- Hard line breaks
-```bash
-apex --mode gfm document.md
-```
-### MultiMarkdown Mode (`--mode multimarkdown` or `--mode mmd`)
-MultiMarkdown compatibility with:
-- Metadata blocks (YAML, MMD format)
-- Metadata variables `[%key]`
-- Footnotes
-- Tables
-- Smart typography
-- Math support
-```bash
-apex --mode mmd document.md
-```
-### Kramdown Mode (`--mode kramdown`)
-Kramdown compatibility with:
-- Attributes `{: #id .class}`
-- Definition lists
-- Footnotes
-- Smart typography
-- Math support
-```bash
-apex --mode kramdown document.md
-```
-### Unified Mode (`--mode unified`, default)
-All features enabled - the superset of all modes.
-```bash
-apex document.md
-# or explicitly:
-apex --mode unified document.md
-```
-## Features
-### Metadata Blocks
-Apex supports three metadata formats:
-**YAML Front Matter:**
-```yaml
----
-title: My Document
-author: John Doe
-date: 2025-12-04
----
-```
-**MultiMarkdown Metadata:**
-```
-Title: My Document
-Author: John Doe
-Date: 2025-12-04
-```
-**Pandoc Title Blocks:**
-```
-% My Document
-% John Doe
-% 2025-12-04
-```
-### Metadata Variables
-Use `[%key]` to insert metadata values anywhere in your
-document:
-```markdown
----
-title: Apex User Guide
-version: 0.1.0
----
-# [%title]
-Version: [%version]
-```
-Renders as:
-```html
-<h1>Apex User Guide</h1>
-<p>Version: 0.1.0</p>
-```
-### Wiki Links
-```markdown
-[[Page Name]]                   # Link to page
-[[Page Name|Display Text]]      # Custom display
-[[Page Name#Section]]           # Link to section
-```
-### Math Support
-**Inline math:**
-```markdown
-The equation $E = mc^2$ is famous.
-```
-**Display math:**
-```markdown
-$$
-\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
-$$
-```
-Math is wrapped in spans with appropriate classes for
-MathJax or KaTeX to render.
-### Critic Markup
-Track changes and annotations with three processing modes:
-**Markup Mode (default)** - Show changes with HTML tags:
-```markdown
-{++addition++}              # Added text → <ins>addition</ins>
-{--deletion--}              # Deleted text → <del>deletion</del>
-{~~old text~>new text~~}    # Substitution → <del>old</del><ins>new</ins>
-{==highlighted==}           # Highlighted text → <mark>highlighted</mark>
-{>>comment text<<}          # Comment → <span class="comment">comment</span>
-```
-**Accept Mode** (`--accept`) - Apply all changes, output
-clean text:
-```bash
-apex --accept document.md
-```
-- Additions: kept
-- Deletions: removed
-- Substitutions: new text kept
-- Highlights: text kept (markup removed)
-- Comments: removed
-**Reject Mode** (`--reject`) - Revert all changes, restore
-original:
-```bash
-apex --reject document.md
-```
-- Additions: removed
-- Deletions: kept
-- Substitutions: old text kept
-- Highlights: text kept (markup removed)
-- Comments: removed
-**Use cases**:
-- Review: `apex document.md` (show all markup)
-- Publish: `apex --accept document.md` (final version)
-- Rollback: `apex --reject document.md` (original version)
-### Tables
-GitHub Flavored Markdown tables:
-```markdown
-| Header 1 | Header 2 |
-| -------- | -------- |
-| Cell 1   | Cell 2   |
-```
-#### Inline tables from CSV/TSV
-You can turn inline CSV/TSV text into Markdown tables by
-using a fenced code
-block with the info string `table`. The delimiter is
-detected automatically:
-- If any non-blank line contains a tab, the block is treated
-  as TSV.
-- Otherwise, if any non-blank line contains a comma, the
-  block is treated as CSV.
-- If no tabs or commas are found, the block is left
-  unchanged as a normal
-  `table`-info fenced code block.
-```table
-header 1,header 2,header 3
-data 1,data 2,data 3
-,,data 2c
-```
-Optionally, you can use an HTML comment marker to indicate
-that the following
-non-blank lines up to the next blank line should be treated
-as CSV/TSV data:
-```markdown
-<!--TABLE-->
-header 1,header 2,header 3
-data 1,data 2,data 3
-,,data 2c
-```
-The same delimiter-detection rules apply to `<!--TABLE-->`
-blocks.
-### Task Lists
-```markdown
-- [ ] Todo item
-- [x] Completed item
-```
-### Footnotes
-**Reference-style footnotes**:
-```markdown
-Here's a footnote[^1].
-[^1]: This is the footnote content.
-```
-**Kramdown inline footnotes**:
-```markdown
-This is a footnote^[inline content here] in the text.
-```
-**MultiMarkdown inline footnotes**:
-```markdown
-This is a footnote[^inline content with spaces] in the text.
-```
-All styles produce properly formatted footnote sections with
-backlinks.
-### Abbreviations
-**Classic MMD syntax** (automatic replacement):
-```markdown
-*[HTML]: Hypertext Markup Language
-*[CSS]: Cascading Style Sheets
-HTML and CSS are essential.
-```
-**MMD 6 reference syntax**:
-```markdown
-[>MMD]: MultiMarkdown
-Using [>MMD] here and [>MMD] again.
-```
-**MMD 6 inline syntax** (no definition needed):
-```markdown
-This is [>(MD) Markdown] and [>(CSS) Cascading Style Sheets].
-```
-All produce `<abbr title="expansion">abbr</abbr>` tags.
-### Definition Lists
-Kramdown/PHP Markdown Extra syntax:
-```markdown
-Term
-: Definition text with **Markdown** support
-Apple
-: A fruit
-: A company
-```
-Renders as proper `<dl>`, `<dt>`, `<dd>` HTML.
-### Inline Attribute Lists (IAL)
-Kramdown syntax for adding attributes to elements:
-```markdown
-# Header {: #custom-id}
-Paragraph with class.
-{: .important}
-## Another Header {: #section-2 .highlight}
-```
-### Callouts
-Bear/Obsidian syntax:
-```markdown
-> [!NOTE] Title
-> This is a note callout
-> [!WARNING] Be Careful
-> Warning content
-> [!TIP] Pro Tip
-> Helpful advice
-> [!DANGER] Critical
-> Dangerous operation
-```
-Collapsible callouts:
-```markdown
-> [!NOTE]+ Expandable
-> Click to expand
-> [!NOTE]- Collapsed
-> Starts collapsed
-```
-### File Includes
-**Marked syntax**:
-```markdown
-<<[file.md]      # Include and process Markdown
-<<(code.py)      # Include as code block
-<<{raw.html}     # Include raw HTML
-```
-**MultiMarkdown transclusion**:
-```markdown
-{{file.md}}      # Include file
-{{*.md}}         # Wildcard include
-```
-**iA Writer syntax**:
-```markdown
-/image.png       # Intelligent include (detects type)
-/code.py         # Auto-detects as code block
-/document.md     # Auto-detects as Markdown
-```
-CSV and TSV files automatically convert to tables!
-### Table of Contents
-Multiple marker formats:
-```markdown
-<!--TOC-->              # Basic TOC
-<!--TOC max2 min1-->    # With depth control
-{{TOC}}                 # MMD style
-{{TOC:2-4}}            # With range
-```
-### Advanced Tables
-**Rowspan** (cells spanning multiple rows):
-```markdown
-| A   | B   |
-| --- | --- |
-| C   | D   |
-| ^^  | E   |
-```
-Cell C spans 2 rows (using `^^` marker).
-**Colspan** (cells spanning multiple columns):
-```markdown
-| A   | B   | C   |
-| --- | --- | --- |
-| D   |     |     |
-```
-Empty cells merge with previous cell.
-**Table captions**:
-```markdown
-[Table Caption]
-| A   | B   |
-| --- | --- |
-| C   | D   |
-```
-### Special Markers
-**Page breaks**:
-```markdown
-<!--BREAK-->            # HTML comment style
-{::pagebreak /}         # Kramdown style
-```
-**Autoscroll pauses** (for Marked's teleprompter mode):
-```markdown
-<!--PAUSE:5-->          # Pause for 5 seconds
-```
-**End-of-block marker**:
-```markdown
-- Item 1
-^
-- Item 2
-```
-Forces list separation.
-### GitHub Emoji
-```markdown
-Success! :rocket: :tada: :sparkles:
-I :heart: Markdown!
-```
-Supports 350+ GitHub emoji, converted to Unicode characters.
-## Command-Line Options
-```
-apex [options] [file]
-Options:
-  -m, --mode MODE        Processor mode: commonmark, gfm, mmd, kramdown, unified
-  -o, --output FILE      Write output to FILE
-  -s, --standalone       Generate complete HTML document (with <html>, <head>, <body>)
-  --style FILE           Link to CSS file in document head (implies --standalone)
-  --title TITLE          Document title (for standalone mode, default: "Document")
-  --pretty               Pretty-print HTML with indentation and whitespace
-  --accept               Accept all Critic Markup changes (apply edits)
-  --reject               Reject all Critic Markup changes (revert edits)
-  --no-tables            Disable table support
-  --no-footnotes         Disable footnote support
-  --no-smart             Disable smart typography
-  --no-math              Disable math support
-  --[no-]includes       Enable file inclusion (enabled by default in unified mode)
-  --hardbreaks           Treat newlines as hard breaks
-  -h, --help             Show help
-  -v, --version          Show version
-```
-### Output Modes
-**Fragment Mode (default)**: Outputs HTML body content only
-```bash
-apex document.md  # Compact HTML fragment
-```
-**Pretty Mode**: Formatted HTML with indentation
-```bash
-apex --pretty document.md  # Readable, indented HTML
-```
-**Standalone Mode**: Complete HTML5 document
-```bash
-apex --standalone document.md
-apex -s --title "My Doc" --style styles.css document.md
-```
-**Combined**: Beautiful complete documents
-```bash
-apex -s --pretty --title "Report" --style report.css doc.md
-```
-## Library Usage
-### C API
-```c
-#include <apex/apex.h>
-// Get default options
-apex_options options = apex_options_default();
-// Or get mode-specific options
-apex_options gfm_opts = apex_options_for_mode(APEX_MODE_GFM);
-// Convert
-const char *markdown = "# Hello\n\n**World**";
-char *html = apex_markdown_to_html(markdown, strlen(markdown), &options);
-// Use html...
-printf("%s\n", html);
-// Clean up
-apex_free_string(html);
-```
-### Objective-C (for Marked integration)
-```objective-c
-#import <NSString+Apex.h>
-// Convert with default unified mode
-NSString *html = [NSString convertWithApex:markdown];
-// Convert with specific mode
-NSString *gfmHtml = [NSString convertWithApex:markdown mode:@"gfm"];
-NSString *mmdHtml = [NSString convertWithApex:markdown mode:@"multimarkdown"];
-```
-## Performance
-Apex is built on cmark-gfm, which is highly optimized:
-- **Small documents (< 10KB)**: < 10ms
-- **Medium documents (< 100KB)**: < 100ms
-- **Large documents (< 1MB)**: < 1s
-## Compatibility
-### With MultiMarkdown
-- ✅ Metadata blocks (YAML, MMD, Pandoc formats)
-- ✅ Metadata variables `[%key]`
-- ✅ Tables (including advanced features)
-- ✅ Smart typography
-- ✅ Math support ($...$ and $$...$$)
-- ✅ File includes / transclusion (`{{file}}`)
-- ✅ Definition lists
-- ✅ Footnotes (reference and inline)
-- ✅ Abbreviations (classic and MMD 6 syntax)
-### With GitHub Flavored Markdown
-- ✅ Tables
-- ✅ Strikethrough (~~text~~)
-- ✅ Task lists (- [ ] / - [x])
-- ✅ Autolinks
-- ✅ Hard line breaks (in GFM mode)
-- ✅ Emoji (:emoji_name:)
-### With Kramdown
-- ✅ Smart typography
-- ✅ Math support
-- ✅ Footnotes (reference and inline ^[text])
-- ✅ Inline Attribute Lists `{: #id .class}`
-- ✅ Attribute List Definitions `{:ref: attrs}`
-- ✅ Definition lists (: syntax)
-- ✅ End-of-block markers (^)
-### With Marked (Special Syntax)
-- ✅ Callouts (Bear/Obsidian/Xcode styles)
-- ✅ File includes (<<[md], <<(code), <<{html})
-- ✅ Table of Contents markers
-- ✅ Page breaks (<!--BREAK-->)
-- ✅ Autoscroll pauses (<!--PAUSE:N-->)
-- ✅ Wiki links ([[Page]])
-### With iA Writer
-- ✅ File transclusion (/filename with auto-detection)
-- ✅ Image includes
-- ✅ Code includes
-- ✅ CSV/TSV to table conversion
-### With CommonMark
-- ✅ Full specification compliance
-- ✅ All standard syntax
-- ✅ Strict parsing when in CommonMark mode
-## Standalone HTML Documents
-Generate complete, self-contained HTML5 documents:
-```bash
-# Basic standalone document
-apex --standalone document.md
-# With custom title and CSS
-apex -s --title "My Report" --style report.css doc.md -o report.html
-# Pretty-formatted complete document
-apex -s --pretty --title "Beautiful Doc" doc.md
-```
-**Features**:
-- Complete HTML5 structure (<!DOCTYPE html>, <head>, <body>)
-- UTF-8 charset and responsive viewport
-- Custom document titles
-- External CSS linking or beautiful default inline styles
-Perfect for: documentation, reports, blogs, standalone files
-**Default styles include**:
-- Modern system font stack
-- Responsive centered layout (800px max-width)
-- Code block and table styling
-- Callout formatting
-- Print styles for page breaks
-## Pretty-Print HTML
-Format HTML with proper indentation for readability:
-```bash
-# Pretty fragment
-apex --pretty document.md
-# Pretty standalone
-apex -s --pretty document.md
-```
-**Features**:
-- 2-space indentation per nesting level
-- Block elements on separate lines
-- Inline elements preserved inline
-- Perfect for: debugging, source viewing, version control
-## Examples
-### Complete Document Example
-```markdown
----
-title: Example Document
-author: Brett Terpstra
-date: 2025-12-04
----
-# [%title]
-By [%author], updated [%date]
-## Features
-This document demonstrates **bold**, *italic*, and ~~strikethrough~~.
-### Math
-The famous equation: $E = mc^2$
-### Code
-```python
-def hello():
-    print("Hello, World!")
-```
-### Task List
-- [x] Complete documentation
-- [ ] Add more examples
-### Wiki Links
-See [[HomePage]] or [[API#Methods|API Documentation]].
-### Critic Markup
-Original text {~~with changes~>and improvements~~}.
-New {++addition++} and {--removal--}.
-{==Important note==} to highlight.
-### Footnotes
-This has a footnote[^1].
-[^1]: Footnote content here.
-```
-## Troubleshooting
-**Math not rendering**: Ensure MathJax or KaTeX is loaded in
-your HTML template
-**Wiki links as plain text**: Make sure `--mode unified` is
-set or wiki links are enabled
-**Critic markup not showing**: Verify `enable_critic_markup` is true in unified mode
-## Getting Help
-- GitHub Issues: [repo-url]/issues
-- Documentation: See `docs/` directory
-- Examples: See `tests/` directory
-## License
-BSD 2-Clause License
-Copyright (c) 2025 Brett Terpstra