apex-ruby 1.0.17 → 1.0.20

data/ext/apex_ext/apex_src/documentation/app-transformed/Citations.md

@@ -0,0 +1,340 @@
+# Citations and Bibliography
+
+Apex supports citations and bibliographies with multiple syntax styles and bibliography formats. Citations are processed in **MultiMarkdown** and **unified** modes.
+
+## Quick Start
+
+**1. Create a bibliography file:**
+
+Create a BibTeX file (`references.bib`):
+```bibtex
+@article{doe99,
+  author = {Doe, John},
+  title = {Article Title},
+  journal = {Journal Name},
+  year = {1999},
+  volume = {1},
+  pages = {1--10}
+}
+
+@book{smith2000,
+  author = {Smith, Jane},
+  title = {Book Title},
+  publisher = {Publisher},
+  year = {2000}
+}
+```
+
+**2. Add citations to your document:**
+
+```markdown
+---
+bibliography: references.bib
+---
+
+See [@doe99] for details. Smith discusses this in [@smith2000].
+
+## References
+
+<!-- REFERENCES -->
+```
+
+**3. Configure in Marked:**
+
+You can add bibliography files to a list in **Settings->Processor->Citations**, or specify them in document metadata (as shown above). When you open a document with citations, Apex will automatically process them using the configured bibliography files.
+
+## Citation Syntaxes
+
+Apex supports three citation syntax styles, automatically detected in unified mode:
+
+### Pandoc Syntax
+
+Pandoc-style citations use square brackets with `@` prefix:
+
+**Basic citation:**
+```markdown
+See [@doe99] for details.
+```
+
+**Multiple citations:**
+```markdown
+See [@doe99; @smith2000; @smith2004] for more information.
+```
+
+**Author in text:**
+```markdown
+@smith04 says blah.
+```
+
+**Author suppressed (year only):**
+```markdown
+Smith says blah [-@smith04].
+```
+
+**With locator (page numbers):**
+```markdown
+@smith04 [p. 33] says blah.
+See @doe99, pp. 33-35 and *passim*.
+```
+
+**Output:**
+```html
+<p>See <span class="citation" data-cites="doe99">(Doe, John 1999)</span> for details.</p>
+<p>See <span class="citation" data-cites="doe99 smith2000 smith2004">(Doe, John 1999; Smith, Jane 2000, 2004)</span> for more information.</p>
+<p><span class="citation" data-cites="smith04">Smith, John (2004)</span> says blah.</p>
+<p>Smith says blah <span class="citation" data-cites="smith04">(2004)</span>.</p>
+```
+
+### MultiMarkdown Syntax
+
+MultiMarkdown-style citations use `#` prefix:
+
+**Basic citation:**
+```markdown
+This is a statement[#Doe:2006].
+```
+
+**With locator:**
+```markdown
+This is a statement[p. 23][#Doe:2006].
+```
+
+**Empty locator:**
+```markdown
+This is a statement[][#Doe:2006].
+```
+
+**Inline citation:**
+```markdown
+As per Doe.[#John Doe. *A Totally Fake Book 1*. Vanity Press, 2006.]
+```
+
+**Output:**
+```html
+<p>This is a statement<span class="citation" data-cites="Doe:2006">(Doe:2006)</span>.</p>
+<p>This is a statement[p. 23]<span class="citation" data-cites="Doe:2006">(Doe:2006)</span>.</p>
+```
+
+### mmark Syntax
+
+mmark-style citations use `@` prefix (similar to Pandoc but with different conventions):
+
+**Basic citation:**
+```markdown
+This references [@RFC2535].
+```
+
+**Normative citation:**
+```markdown
+This references [@!RFC1034] (normative).
+```
+
+**Multiple citations:**
+```markdown
+Multiple citations: [@RFC1034;@RFC1035].
+```
+
+**Combined reference:**
+```markdown
+Combined reference: [@RFC1034@STD3].
+```
+
+**Output:**
+```html
+<p>This references <span class="citation" data-cites="RFC2535">(RFC2535)</span>.</p>
+<p>Multiple citations: <span class="citation" data-cites="RFC1034">(RFC1034)</span>;<span class="citation" data-cites="RFC1035">(RFC1035)</span>.</p>
+```
+
+## Bibliography Formats
+
+Apex supports three bibliography formats:
+
+### BibTeX (`.bib`)
+
+Standard BibTeX format:
+
+```bibtex
+@article{doe99,
+  author = {Doe, John},
+  title = {Article Title},
+  journal = {Journal Name},
+  year = {1999},
+  volume = {1},
+  pages = {1--10}
+}
+
+@book{smith2000,
+  author = {Smith, Jane},
+  title = {Book Title},
+  publisher = {Publisher},
+  year = {2000}
+}
+```
+
+### CSL JSON (`.json`)
+
+Citation Style Language JSON format:
+
+```json
+[
+  {
+    "id": "doe99",
+    "type": "article-journal",
+    "title": "Article Title",
+    "author": [
+      {
+        "family": "Doe",
+        "given": "John"
+      }
+    ],
+    "container-title": "Journal Name",
+    "issued": {
+      "date-parts": [[1999]]
+    },
+    "volume": "1",
+    "page": "1-10"
+  }
+]
+```
+
+### CSL YAML (`.yml`, `.yaml`)
+
+Citation Style Language YAML format:
+
+```yaml
+- id: doe99
+  type: article-journal
+  title: Article Title
+  author:
+    - family: Doe
+      given: John
+  container-title: Journal Name
+  issued:
+    date-parts:
+      - - 1999
+  volume: 1
+  page: 1-10
+```
+
+## Specifying Bibliography
+
+### Settings Configuration
+
+Add bibliography files to a list in **Settings->Processor->Citations**. These files will be available for all documents you process. You can add multiple files, and Apex will search through them when processing citations.
+
+### Document Metadata
+
+You can also specify bibliography files in document metadata, which will override or supplement the settings:
+
+**YAML front matter:**
+```markdown
+---
+bibliography: references.bib
+---
+
+See [@doe99] for details.
+```
+
+**Multiple files:**
+```markdown
+---
+bibliography:
+  - refs1.bib
+  - refs2.bib
+---
+
+See [@doe99] for details.
+```
+
+**MultiMarkdown metadata:**
+```markdown
+Bibliography: references.bib
+
+See [@doe99] for details.
+```
+
+**Pandoc title block:**
+```markdown
+% Bibliography: references.bib
+
+See [@doe99] for details.
+```
+
+## Bibliography Generation
+
+Bibliography is automatically generated from all cited entries and inserted at the `<!-- REFERENCES -->` marker:
+
+```markdown
+See [@doe99] and [@smith2000] for details.
+
+## References
+
+<!-- REFERENCES -->
+```
+
+**Output:**
+```html
+<p>See <span class="citation" data-cites="doe99">(Doe, John 1999)</span> and <span class="citation" data-cites="smith2000">(Smith, Jane 2000)</span> for details.</p>
+
+<h2>References</h2>
+<div id="refs" class="references csl-bib-body">
+<div id="ref-doe99" class="csl-entry">Doe, John 1999. <em>Article Title</em>. <em>Journal Name</em> 1: 1--10</div>
+<div id="ref-smith2000" class="csl-entry">Smith, Jane 2000. <em>Book Title</em>. Publisher</div>
+</div>
+```
+
+If no `<!-- REFERENCES -->` marker is found, the bibliography is appended to the end of the document.
+
+## Citation Options
+
+### Link Citations
+
+Enable **Settings->Processor->Link Citations** to make citations link to their bibliography entries:
+
+**Output:**
+```html
+<p>See <a href="#ref-doe99" class="citation" data-cites="doe99">(Doe, John 1999)</a> for details.</p>
+```
+
+### Suppress Bibliography
+
+Enable **Settings->Processor->Suppress Bibliography** to suppress bibliography output while still processing citations.
+
+### Citation Style (CSL)
+
+Specify a Citation Style Language file in **Settings->Processor->CSL File** to control citation and bibliography formatting.
+
+CSL files can also be specified in metadata:
+```markdown
+---
+bibliography: refs.bib
+csl: apa.csl
+---
+```
+
+## Mode Support
+
+**Unified mode:**
+- All citation syntaxes supported (auto-detected)
+- All bibliography formats supported
+- Citations enabled by default when bibliography is provided
+
+**MultiMarkdown mode:**
+- MultiMarkdown citation syntax (`[#key]`)
+- All bibliography formats supported
+- Citations enabled by default when bibliography is provided
+
+**CommonMark/GFM modes:**
+- Citations disabled (pure CommonMark/GFM)
+
+**Kramdown mode:**
+- Citations disabled (Kramdown uses different citation system)
+
+## Performance
+
+Citations are only processed when a bibliography is actually provided (via settings or metadata). This ensures no performance impact when citations aren't being used.
+
+## Related
+
+- [Syntax](Syntax) - Citation syntax reference
+- [Modes](Modes) - Mode-specific citation support

data/ext/apex_ext/apex_src/documentation/app-transformed/Credits.md

@@ -0,0 +1,11 @@
+# Credits
+
+Apex builds upon the work of several excellent Markdown projects:
+
+- [CommonMark](https://commonmark.org) - Specification and reference implementation for a standardized Markdown syntax
+- [cmark-gfm](https://github.com/github/cmark-gfm) - GitHub's fork of cmark with GitHub Flavored Markdown extensions
+- [Kramdown](https://kramdown.gettalong.org) - A fast and extensible Markdown processor
+- [MultiMarkdown 6](https://fletcher.github.io/MultiMarkdown-6) - An extension of the Markdown syntax
+- [TextIndex](https://mattgemmell.scot/) by Matt Gemmell, a syntax for creating indices
+
+Apex brings together the best features from all of these projects into a unified, high-performance processor.

data/ext/apex_ext/apex_src/documentation/app-transformed/Header-IDs.md

@@ -0,0 +1,234 @@
+# Header IDs
+
+Apex automatically generates unique IDs for all headers, making it easy to link to specific sections. Different processor modes use different ID generation rules.
+
+## Automatic Generation
+
+By default, Apex generates header IDs automatically. You can disable this in **Settings->Processor->Generate Header IDs**.
+
+## ID Formats
+
+Apex supports three ID formats, each matching the behavior of different Markdown processors. You can select the format in **Settings->Processor->Header ID Format**:
+
+### GFM Format (Default)
+
+Used by default in unified and GFM modes. Matches GitHub's header ID generation:
+
+**Rules:**
+- Spaces become single dashes
+- Em dashes (—) and en dashes (–) are removed
+- Punctuation is removed
+- Other whitespace is removed
+- Diacritics are normalized to ASCII equivalents (é → e, ñ → n, etc.)
+- **Emojis are converted to their textual names** (e.g., 😄 → "smile", 🚀 → "rocket")
+- Leading and trailing dashes are trimmed
+- Result is lowercased
+
+**Examples:**
+```markdown
+# Emoji Support
+→ id="emoji-support"
+
+# 😄 Emoji Support
+→ id="smile-emoji-support"
+
+# 🚀
+→ id="rocket"
+
+# 👍 👎
+→ id="thumbsup-thumbsdown"
+
+# Hello—World
+→ id="helloworld"
+
+# C++ Programming
+→ id="c-programming"
+
+# Déjà Vu
+→ id="deja-vu"
+```
+
+**Note:** Emoji-to-name conversion matches Pandoc's GFM behavior, ensuring emojis in headers are represented as readable text in IDs. This only applies to GFM format; MMD and Kramdown formats preserve emojis as-is or remove them according to their respective rules.
+
+### MultiMarkdown Format
+
+Used in MultiMarkdown mode. Preserves dashes and diacritics:
+
+**Rules:**
+- Spaces are removed (not converted to dashes)
+- All dash types (regular, em, en) are preserved
+- Diacritics are preserved (UTF-8)
+- Punctuation is removed
+- Leading and trailing dashes are preserved
+- Result is lowercased
+
+**Examples:**
+```markdown
+# Header—One
+→ id="header—one"
+
+# Hello World
+→ id="helloworld"
+
+# Déjà Vu
+→ id="déjà-vu"
+```
+
+### Kramdown Format
+
+Used in Kramdown mode. More aggressive punctuation handling:
+
+**Rules:**
+- Spaces become single dashes (one dash per space)
+- Em dashes (—) and en dashes (–) are removed
+- Diacritics are removed (not normalized)
+- Punctuation becomes dashes (except trailing punctuation is removed)
+- If punctuation is followed by a space, the space is skipped
+- Leading dashes are trimmed
+- Trailing dashes are preserved
+- Result is lowercased
+
+**Examples:**
+```markdown
+# Hello, World!
+→ id="hello-world"
+
+# C++ Programming
+→ id="c-programming"
+
+# Test (Example)
+→ id="test-example"
+```
+
+## Setting ID Format
+
+### By Mode
+
+Each mode automatically sets the appropriate ID format:
+- GFM mode → GFM format
+- MultiMarkdown mode → MultiMarkdown format
+- Kramdown mode → Kramdown format
+- Unified mode → GFM format (default)
+
+### Override in Unified Mode
+
+In unified mode, you can override the default GFM format by selecting a different option in **Settings->Processor->Header ID Format**:
+
+- GFM format (default)
+- MultiMarkdown format
+- Kramdown format
+
+## Manual Header IDs
+
+You can manually specify header IDs using several syntaxes:
+
+### MultiMarkdown Syntax
+
+```markdown
+### Heading 1 [heading1]
+```
+
+### Kramdown Syntax
+
+```markdown
+### Heading 1 {#heading1}
+```
+
+### Inline Attribute List (IAL)
+
+```markdown
+### Heading 1 {: #heading1}
+```
+
+Manual IDs take precedence over auto-generated IDs.
+
+## Anchor Tags vs. IDs
+
+By default, Apex adds `id` attributes directly to header elements:
+
+```html
+<h1 id="my-header">My Header</h1>
+```
+
+You can generate `<a>` anchor tags instead by enabling **Settings->Processor->Header Anchors**:
+
+This produces:
+
+```html
+<h1><a id="my-header" href="#my-header">My Header</a></h1>
+```
+
+This format is compatible with some Markdown processors that use anchor tags.
+
+## Examples
+
+### GFM Format
+
+```markdown
+# Getting Started with Apex
+# Advanced Features
+# C++ Integration
+```
+
+Becomes:
+
+```html
+<h1 id="getting-started-with-apex">Getting Started with Apex</h1>
+<h1 id="advanced-features">Advanced Features</h1>
+<h1 id="c-integration">C Integration</h1>
+```
+
+### MultiMarkdown Format
+
+```markdown
+# Getting Started with Apex
+# Advanced Features
+# C++ Integration
+```
+
+With MultiMarkdown format selected:
+
+```html
+<h1 id="gettingstartedwithapex">Getting Started with Apex</h1>
+<h1 id="advancedfeatures">Advanced Features</h1>
+<h1 id="cintegration">C Integration</h1>
+```
+
+### Kramdown Format
+
+```markdown
+# Getting Started with Apex
+# Advanced Features
+# C++ Integration
+```
+
+With Kramdown format selected:
+
+```html
+<h1 id="getting-started-with-apex">Getting Started with Apex</h1>
+<h1 id="advanced-features">Advanced Features</h1>
+<h1 id="c-integration">C Integration</h1>
+```
+
+## Linking to Headers
+
+Once headers have IDs, you can link to them:
+
+```markdown
+[Link to section](#getting-started-with-apex)
+```
+
+Or with wiki links (requires wiki links to be enabled in **Settings->Processor->Wiki Links**):
+
+```markdown
+[[Document#getting-started-with-apex]]
+```
+
+## Table of Contents
+
+Apex's TOC generation automatically uses the same ID format as your headers. See [Syntax](Syntax) for TOC details.
+
+## Related
+
+- [Modes](Modes) - How modes affect ID generation
+- [Syntax](Syntax) - Manual ID syntax