apex-ruby 1.0.6

data/ext/apex_ext/apex_src/documentation/transform_for_app.example.md

@@ -0,0 +1,260 @@
+# Documentation Transformation Instructions for App Usage
+
+This file contains instructions for transforming Apex documentation from command-line focused to app-focused (e.g., for Marked.app). Copy this file to `transform_for_app.md` and edit it as needed for your specific app.
+
+## General Transformation Rules
+
+### 1. Replace CLI Flags with Settings References
+
+Replace all command-line flags with app settings paths using the format: `Settings->Category->Setting Name`
+
+**Examples:**
+- `--plugins` → `Settings->Processor->Include Plugins`
+- `--mode unified` → Select `unified` in **Settings->Processor->Mode**
+- `--meta-file FILE` → Select a metadata file in **Settings->Processor->Metadata File**, or specify a file in document metadata
+- `--bibliography FILE` → Add bibliography files to the list in **Settings->Processor->Citations**, or specify in document metadata
+
+**Patterns to replace:**
+- `--[no-]flag` → `Settings->Category->Setting Name` (with enable/disable context)
+- `--flag VALUE` → Set the value in **Settings->Category->Setting Name**
+- `apex document.md --flag` → Use **Settings->Category->Setting Name** in the app
+
+### 2. Remove Command-Line Examples
+
+Remove all code blocks that contain only command-line examples. These are not relevant in an app context where the app handles execution.
+
+**What to remove:**
+- Code blocks showing `apex` commands
+- Code blocks showing command-line usage examples
+- Examples like:
+  ```bash
+  apex document.md --mode unified
+  apex --plugins document.md
+  ```
+
+**What to keep:**
+- Code blocks showing Markdown syntax examples
+- Code blocks showing configuration file examples (YAML, JSON, etc.)
+- Code blocks showing actual code (Python, Ruby, etc.)
+
+### 3. Remove References to Command Line Options
+
+- Remove all links to "Command Line Options" page
+- Remove phrases like "See [Command Line Options](Command-Line-Options) for details"
+- Replace with app-specific instructions or remove entirely
+
+### 4. Rewrite Usage Instructions
+
+Transform instructions from "how to run commands" to "how to use the app":
+
+**Before:**
+> Use the `--mode` flag to select the processor mode.
+
+**After:**
+> Select the processor mode from **Settings->Processor->Mode**.
+
+**Before:**
+> Run `apex document.md --plugins` to enable plugins.
+
+**After:**
+> Enable plugins by checking **Settings->Processor->Include Plugins**.
+
+## Page-Specific Transformations
+
+### Multi-File-Documents
+
+**Key changes:**
+1. Indicate that Marked will automatically detect the file format for merge documents
+2. Specify that mmd-merge documents must start with a `#merge` line to be automatically detected
+3. Replace CLI examples with app usage instructions
+
+**Example transformation:**
+- Add: "Marked will automatically detect the file format for merge documents."
+- Add: "MMD merge documents must start with a `#merge` line to be automatically detected by Marked."
+- Replace: "Use `apex --combine file1.md file2.md`" → "Select multiple files and enable **Settings->Processor->Combine Files**"
+
+### Plugins
+
+**Key changes:**
+1. Indicate that Marked has an "Install Plugins" option that allows selecting a plugin directory and automatically installing to `~/.config/apex/plugins`
+2. Mention that Marked lists available plugins in a Plugins panel within Processor settings
+3. Remove all references and links to "Command Line Options"
+4. Replace CLI installation examples with app-based installation instructions
+
+**Example transformation:**
+- Add: "Marked provides an **Install Plugins** option that allows you to select a plugin directory on your disk and have it automatically installed to `~/.config/apex/plugins`."
+- Add: "Marked will list available plugins in a **Plugins panel** within the Processor settings."
+- Remove: "Install plugins using `apex --install-plugin ID-or-URL`"
+
+### Modes
+
+**Key changes:**
+1. Rewrite to indicate that modes (unified, multimarkdown, commonmark, kramdown, gfm) can be selected from the Settings->Processor panel
+2. Keep the descriptions of the modes the same
+3. Remove CLI command examples
+4. Remove links to "Command Line Options"
+
+**Example transformation:**
+- Replace: "Use `--mode unified` to enable unified mode" → "Select `unified` from **Settings->Processor->Mode**"
+- Keep: All mode descriptions and feature lists
+- Remove: All `apex --mode` examples
+
+### Header IDs
+
+**Key changes:**
+1. Reference a Settings->Processor->Header IDs option that will be a dropdown for selecting the header ID mode
+2. Remove CLI command examples
+3. Remove links to "Command Line Options"
+
+**Example transformation:**
+- Replace: "Use `--id-format gfm`" → "Select `gfm` from **Settings->Processor->Header ID Format**"
+- Replace: "Disable with `--no-ids`" → "Disable in **Settings->Processor->Generate Header IDs**"
+
+### Citations
+
+**Key changes:**
+1. Mention that bibliography files can be added to a list in Settings->Processor->Citations, or specified in document metadata
+2. Remove CLI command examples
+3. Remove links to "Command Line Options"
+
+**Example transformation:**
+- Replace: "Use `--bibliography refs.bib`" → "Add bibliography files to the list in **Settings->Processor->Citations**, or specify in document metadata"
+- Keep: All citation syntax examples
+
+### Syntax
+
+**Key changes:**
+1. Replace all CLI flag references with Settings references
+2. Remove CLI command examples
+3. Remove links to "Command Line Options"
+4. Keep all syntax examples and feature descriptions
+
+**Example transformation:**
+- Replace: "Use `--sup-sub` to enable" → "Enable in **Settings->Processor->Superscript/Subscript**"
+- Replace: "Use `--autolink` to enable" → "Enable **Settings->Processor->Autolinks**"
+- Remove: All `apex --flag` command examples
+
+### Inline-Attribute-Lists
+
+**Key changes:**
+1. Remove CLI references
+2. Remove links to "Command Line Options"
+3. Keep all syntax examples
+
+### Metadata-Transforms
+
+**Key changes:**
+1. Remove CLI references
+2. Remove links to "Command Line Options"
+3. Keep all transform syntax examples and descriptions
+
+### Credits
+
+**Key changes:**
+- No specific app-focused transformations needed (primarily lists external projects)
+- Keep content as-is
+
+## Settings Path Structure
+
+Use this structure for Settings references:
+
+```
+Settings->Category->Setting Name
+```
+
+**Categories:**
+- **General**: General app settings (e.g., Show Progress)
+- **Processor**: Processing options (e.g., Mode, Plugins, Header IDs)
+- **Output**: Output formatting options (e.g., Standalone HTML, CSS File)
+
+**Examples:**
+- `Settings->Processor->Mode`
+- `Settings->Processor->Include Plugins`
+- `Settings->Processor->Header ID Format`
+- `Settings->Processor->Citations`
+- `Settings->Output->Standalone HTML`
+- `Settings->Output->CSS File`
+
+## Formatting Guidelines
+
+### Settings References
+
+- Use **bold** for Settings paths: **Settings->Processor->Mode**
+- Use **bold** for UI elements: **Plugins panel**, **Install Plugins** option
+- Use regular text for descriptive phrases: "select from", "enable by checking"
+
+### Code Blocks
+
+- Keep Markdown syntax examples in code blocks
+- Keep configuration file examples (YAML, JSON) in code blocks
+- Remove command-line execution examples
+- When showing app usage, use descriptive text instead of code blocks
+
+### Links
+
+- Remove links to "Command Line Options"
+- Keep internal links to other documentation pages (Syntax, Modes, etc.)
+- Update links to reference app features where appropriate
+
+## Quality Checklist
+
+After transformation, verify:
+
+- [ ] All CLI flags replaced with Settings references
+- [ ] All command-line examples removed
+- [ ] All links to "Command Line Options" removed
+- [ ] App-specific instructions added where appropriate
+- [ ] Markdown syntax examples preserved
+- [ ] Configuration examples preserved
+- [ ] Page-specific transformations applied
+- [ ] Settings paths use consistent formatting
+- [ ] Text flows naturally without CLI references
+- [ ] No broken internal links
+
+## Example: Before and After
+
+### Before (CLI-focused)
+
+```markdown
+## Enabling Plugins
+
+Plugins are disabled by default. To enable them, use the `--plugins` flag:
+
+```bash
+apex document.md --plugins
+```
+
+You can also install plugins using:
+
+```bash
+apex --install-plugin kbd
+```
+
+See [Command Line Options](Command-Line-Options) for all plugin-related flags.
+```
+
+### After (App-focused)
+
+```markdown
+## Enabling Plugins
+
+Plugins are disabled by default. Enable plugins by checking **Settings->Processor->Include Plugins**.
+
+You can also enable plugins in document metadata (in the document's front matter):
+
+```yaml
+---
+title: Plugin demo
+plugins: true
+---
+```
+
+Marked provides an **Install Plugins** option that allows you to select a plugin directory on your disk and have it automatically installed to `~/.config/apex/plugins`. Marked will list available plugins in a **Plugins panel** within the Processor settings.
+```
+
+## Notes
+
+- This transformation is designed for apps like Marked.app that provide a GUI for Apex
+- The goal is to make documentation user-friendly for app users who don't use the command line
+- Settings paths are suggestions and should be adjusted to match your app's actual settings structure
+- Some pages may need additional app-specific context beyond these general rules

data/ext/apex_ext/apex_src/examples/bracketed_spans_demo.md

@@ -0,0 +1,119 @@
+# Bracketed Spans Demo
+
+Bracketed spans are a Pandoc-inspired feature that allows you to create HTML `<span>` elements with attributes using the syntax `[text]{IAL}`. The text inside the brackets is processed as markdown, and the IAL (Inline Attribute List) provides HTML attributes.
+
+## Basic Usage
+
+This is [some *text*]{.highlight} with a class.
+
+This is [another example]{#custom-id .important} with an ID
+and class.
+
+This is [text with **bold**]{.bold-style} that processes
+markdown inside.
+
+## Attributes
+
+You can use all standard IAL attribute types:
+
+### IDs
+
+This is [text]{#my-id} with just an ID.
+
+### Classes
+
+This is [text]{.class1 .class2 .class3} with multiple
+classes.
+
+### Key-Value Attributes
+
+This is [text]{key="value" title="Tooltip"} with custom
+attributes.
+
+This is [text]{data-id="123" aria-label="Description"} with
+data and ARIA attributes.
+
+### Combined Attributes
+
+This is [text]{#my-id .highlight .important key="value"}
+combining all attribute types.
+
+## Markdown Processing
+
+The text inside brackets is fully processed as markdown:
+
+- [**Bold text**]{.bold}
+- [*Italic text*]{.italic}
+- [`Code spans`]{.code}
+- [Text with [nested brackets]]{.nested}
+
+## Nested Brackets
+
+Bracketed spans support nested brackets. The parser
+correctly matches the outer brackets:
+
+This is [Text with [nested brackets]]{.nested} that
+preserves the inner brackets.
+
+This is [Text with [multiple [levels] of
+nesting]]{.multi-level} that handles deep nesting.
+
+This is [Text with [inner] and [more inner]
+brackets]{.multiple-nested} that handles multiple nested
+pairs.
+
+## Reference Links Take Precedence
+
+If the bracketed text matches a reference link definition,
+it will be treated as a link instead of a span:
+
+This is [a link][example] that should be a link, not a span.
+
+[example]: https://example.com
+
+This is [another link][example2] with a title.
+
+[example2]: https://example.org "Example Site"
+
+## Use Cases
+
+### Styling Inline Text
+
+You can [highlight important text]{.highlight .important}
+inline.
+
+You can [mark text as new]{.new} or
+[deprecated]{.deprecated}.
+
+### Adding Metadata
+
+You can [add data attributes]{data-type="note" data-id="42"}
+for JavaScript.
+
+You can [add ARIA labels]{aria-label="Important notice"} for
+accessibility.
+
+### Semantic Markup
+
+You can [mark text as a term]{.term} or
+[citation]{.citation}.
+
+## Examples in Context
+
+Here's a paragraph with [highlighted text]{.highlight},
+[important text]{.important}, and [a term]{.term}.
+
+Here's a list with styled items:
+
+- [First item]{.first}
+- [Second item]{.second}
+- [Third item]{.third}
+
+## Notes
+
+- Bracketed spans are enabled by default in unified mode
+- Use `--spans` to enable in other modes
+- Use `--no-spans` to disable in unified mode
+- Reference links always take precedence over spans
+- Markdown inside spans is fully processed
+

data/ext/apex_ext/apex_src/examples/emoji_span_plugin.yml

@@ -0,0 +1,11 @@
+---
+id: emoji-span
+description: Wrap :emoji: markers in a span for styling
+phase: post_render
+pattern: "(:[a-zA-Z0-9_+-]+:)"
+replacement: "<span class=\"emoji\">$1</span>"
+flags: "i"
+priority: 200
+timeout_ms: 0
+---
+

data/ext/apex_ext/apex_src/examples/example.html

@@ -0,0 +1,53 @@
+<h1>Apex Markdown Example</h1>
+<p>This is a comprehensive example document showing various Markdown features supported by Apex.</p>
+<h2>Basic Formatting</h2>
+<p>This is a paragraph with **bold text**, *italic text*, and ***bold italic text***.</p>
+<p>You can also use `inline code` within paragraphs.</p>
+<h2>Headings</h2>
+<h3>Level 3</h3>
+<h4>Level 4</h4>
+<h5>Level 5</h5>
+<h6>Level 6</h6>
+<h2>Lists</h2>
+<h3>Unordered Lists</h3>
+<p>- Item 1
+- Item 2
+  - Nested item
+  - Another nested item
+- Item 3</p>
+<h3>Ordered Lists</h3>
+<p>1. First item
+2. Second item
+3. Third item</p>
+<h2>Code Blocks</h2>
+<pre><code class="language-python">def hello_world():
+    print(&quot;Hello, World!&quot;)
+    return 42
+
+result = hello_world()
+</code></pre>
+<pre><code class="language-javascript">function greet(name) {
+    console.log(`Hello, ${name}!`);
+}
+
+greet(&quot;Apex&quot;);
+</code></pre>
+<h2>Links and Images</h2>
+<p>[Apex on GitHub](https://github.com)</p>
+<p>![Sample Image](https://placehold.co/600x400)</p>
+<h2>Blockquotes</h2>
+<p>&gt; This is a blockquote.
+&gt; It can span multiple lines.
+&gt;
+&gt; And contain multiple paragraphs.</p>
+<h2>Horizontal Rules</h2>
+<p>---</p>
+<h2>Special Characters</h2>
+<p>HTML characters like &lt;tag&gt; and &amp; are automatically escaped.
+Quotes like &quot;these&quot; are handled properly.</p>
+<h2>More Features (Coming Soon)</h2>
+<p>- [ ] Task lists
+- [x] Basic Markdown
+- [ ] Tables
+- [ ] Footnotes
+- [ ] Definition lists</p>

data/ext/apex_ext/apex_src/examples/example.md

@@ -0,0 +1,85 @@
+# Apex Markdown Example
+
+This is a comprehensive example document showing various
+Markdown features supported by Apex.
+
+## Basic Formatting
+
+This is a paragraph with **bold text**, *italic text*, and
+***bold italic text***.
+
+You can also use `inline code` within paragraphs.
+
+## Headings
+
+### Level 3
+#### Level 4
+##### Level 5
+###### Level 6
+
+## Lists
+
+### Unordered Lists
+
+- Item 1
+- Item 2
+  - Nested item
+  - Another nested item
+- Item 3
+
+### Ordered Lists
+
+1. First item
+2. Second item
+3. Third item
+
+## Code Blocks
+
+```python
+def hello_world():
+    print("Hello, World!")
+    return 42
+
+result = hello_world()
+
+```
+
+```javascript
+function greet(name) {
+    console.log(`Hello, ${name}!`);
+}
+
+greet("Apex");
+
+```
+
+## Links and Images
+
+[Apex on GitHub](https://github.com)
+
+![Sample Image](https://placehold.co/600x400)
+
+## Blockquotes
+
+> This is a blockquote.
+> It can span multiple lines.
+>
+> And contain multiple paragraphs.
+
+## Horizontal Rules
+
+---
+
+## Special Characters
+
+HTML characters like <tag> and & are automatically escaped.
+Quotes like "these" are handled properly.
+
+## More Features (Coming Soon)
+
+- [ ] Task lists
+- [x] Basic Markdown
+- [ ] Tables
+- [ ] Footnotes
+- [ ] Definition lists
+

data/ext/apex_ext/apex_src/examples/fenced_divs_demo.md

@@ -0,0 +1,158 @@
+# Pandoc Fenced Divs Demo
+
+This document demonstrates all features of the Pandoc fenced
+divs extension.
+
+## Basic Fenced Div
+
+A simple fenced div with ID and class:
+
+::::: {#special .sidebar}
+Here is a paragraph.
+
+And another paragraph with more content.
+:::::
+
+## Fenced Div with Multiple Classes
+
+::::: {.warning .important .highlight}
+This is a warning div with multiple classes.
+:::::
+
+## Fenced Div with Attributes
+
+::::: {#mydiv .container key="value" data-id="123"}
+This div has an ID, a class, and custom attributes.
+:::::
+
+## Single Unbraced Word (Treated as Class)
+
+::: sidebar
+This is a div with a single unbraced word treated as a class
+name.
+:::
+
+## Fenced Div with Trailing Colons
+
+According to the spec, attributes may optionally be followed
+by another string of consecutive colons:
+
+::::: {#special .sidebar} ::::
+Here is a paragraph with trailing colons after the
+attributes.
+
+And another.
+::::::::::::::::::
+
+## Nested Divs
+
+Fenced divs can be nested. Opening fences must have
+attributes:
+
+::: Warning ::::::
+This is a warning.
+
+::: Danger
+This is a warning within a warning.
+:::
+::::::::::::::::::
+
+## Complex Nested Example
+
+::::: {#outer .container} ::::
+Outer div content.
+
+::: {.inner .nested}
+First inner div.
+
+::: {.deep}
+Deeply nested div.
+:::
+:::
+
+More outer content.
+::::::::::::::::::
+
+## Div with All Attribute Types
+
+::::: {#complex-id .class1 .class2 .class3 key1="value1"
+key2='value2' data-test="123"}
+This div demonstrates:
+
+- ID (#complex-id)
+- Multiple classes (.class1, .class2, .class3)
+- Custom attributes (key1, key2, data-test)
+
+:::::
+
+## Div Separated by Blank Lines
+
+This paragraph is before the div.
+
+::::: {.separated}
+This div is properly separated by blank lines from the
+preceding paragraph.
+:::::
+
+This paragraph is after the div.
+
+## Minimal Div (3 Colons Minimum)
+
+::: {.minimal}
+This uses the minimum 3 colons for the fence.
+:::
+
+## Div with Quoted Values
+
+::::: {#quoted .test attr1="quoted value" attr2='single
+quoted'}
+This div has attributes with quoted values containing
+spaces.
+:::::
+
+## Multiple Divs in Sequence
+
+::: {.first}
+First div.
+:::
+
+::: {.second}
+Second div.
+:::
+
+::: {.third}
+Third div.
+:::
+
+## Div with Empty Content
+
+::: {.empty}
+:::
+
+## Div with Only ID
+
+::: {#only-id}
+This div has only an ID, no classes.
+:::
+
+## Div with Only Classes
+
+::: {.only-classes .multiple}
+This div has only classes, no ID.
+:::
+
+## Div with Mixed Content
+
+::::: {#mixed .content}
+This div contains:
+
+- A list item
+- Another list item
+
+And a paragraph.
+
+> A blockquote
+
+And more content.
+:::::
+

data/ext/apex_ext/apex_src/examples/kbd.md

@@ -0,0 +1,8 @@
+Lorem ipsum dolor sit amet, consectetur adipisicing elit,
+sed do eiusmod tempor incididunt ut labore et dolore magna
+aliqua. Ut enim ad minim veniam, quis nostrud exercitation
+ullamco laboris nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in {% kbd $@3 %}
+voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+Excepteur sint occaecat cupidatat non proident, sunt in
+culpa qui officia deserunt mollit anim id est laborum.