apex-ruby 1.0.18 → 1.0.20

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

@@ -0,0 +1,274 @@
+# Citation Examples and Expected Output
+
+This document contains example markdown with citations and
+the expected HTML output from different tools.
+
+## Test Document
+
+```markdown
+# Test Document with Citations
+
+This is a test document with various citation styles.
+
+## Pandoc Citations
+
+Blah blah [@doe99; @smith2000; @smith2004].
+
+See @doe99, pp. 33-35 and *passim*.
+
+Smith says blah [-@smith04].
+
+@smith04 says blah.
+
+@smith04 [p. 33] says blah.
+
+## MultiMarkdown Citations
+
+This is a statement that should be attributed to its source[p. 23][#Doe:2006].
+
+This is a statement that should be attributed to its source[][#Doe:2006].
+
+As per Doe.[#John Doe. *A Totally Fake Book 1*.  Vanity Press, 2006.]
+
+## mmark Citations
+
+This references [@RFC2535] and [@!RFC1034] (normative).
+
+Multiple citations: [@RFC1034;@RFC1035].
+
+Combined reference: [@RFC1034@STD3].
+
+## References Section
+
+<!-- REFERENCES -->
+
+```
+
+## Expected Output Formats
+
+### Pandoc Output (HTML)
+
+**Citations**:
+```html
+<p>Blah blah <span class="citation" data-cites="doe99 smith2000 smith2004">(Doe 1999; Smith 2000, 2004)</span>.</p>
+
+<p>See <span class="citation" data-cites="doe99">Doe (1999, 33–35)</span> and <em>passim</em>.</p>
+
+<p>Smith says blah <span class="citation" data-cites="smith04">(2004)</span>.</p>
+
+<p><span class="citation" data-cites="smith04">Smith (2004)</span> says blah.</p>
+
+<p><span class="citation" data-cites="smith04">Smith (2004, 33)</span> says blah.</p>
+
+```
+
+**Bibliography**:
+```html
+<div id="refs" class="references csl-bib-body hanging-indent" role="doc-bibliography">
+<div id="ref-doe99" class="csl-entry" role="doc-biblioentry">
+Doe, John. 1999. "Article Title." <i>Journal Name</i> 1: 1–10.
+</div>
+<div id="ref-smith2000" class="csl-entry" role="doc-biblioentry">
+Smith, Jane. 2000. <i>Book Title</i>. Publisher.
+</div>
+<div id="ref-smith2004" class="csl-entry" role="doc-biblioentry">
+———. 2004. "Another Article." <i>Journal</i> 2: 20–30.
+</div>
+</div>
+
+```
+
+### MultiMarkdown Output (HTML)
+
+**Citations**:
+```html
+<p>This is a statement that should be attributed to its source<a href="#Doe:2006" id="Doe:2006:1">[1]</a>.</p>
+
+<p>This is a statement that should be attributed to its source<a href="#Doe:2006" id="Doe:2006:2">[2]</a>.</p>
+
+<p>As per Doe.<a href="#Doe:2006" id="Doe:2006:3">[3]</a></p>
+
+```
+
+**Bibliography**:
+```html
+<div id="bibliography">
+<div id="Doe:2006">
+John Doe. <em>Some Big Fancy Book</em>.  Vanity Press, 2006.
+</div>
+</div>
+
+```
+
+### mmark Output (HTML/XML)
+
+**Citations** (in XML2RFC format):
+```xml
+<reference anchor="RFC2535">
+  <front>
+    <title>Domain Name System Security Extensions</title>
+    <author>
+      <organization>IETF</organization>
+    </author>
+    <date year="1999" month="March"/>
+  </front>
+</reference>
+
+```
+
+In HTML (converted):
+```html
+<p>This references <xref target="RFC2535" /> and <xref target="RFC1034" /> (normative).</p>
+
+<p>Multiple citations: <xref target="RFC1034" />; <xref target="RFC1035" />.</p>
+
+```
+
+**Bibliography** (in backmatter):
+```html
+<section id="references">
+  <references>
+    <reference anchor="RFC2535">
+      <front>
+        <title>Domain Name System Security Extensions</title>
+        ...
+      </front>
+    </reference>
+    <reference anchor="RFC1034">
+      <front>
+        <title>Domain Names - Concepts and Facilities</title>
+        ...
+      </front>
+    </reference>
+  </references>
+</section>
+
+```
+
+## Bibliography File Examples
+
+### BibTeX Example
+
+```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 Example
+
+```json
+[
+  {
+    "id": "doe99",
+    "type": "article-journal",
+    "author": [
+      {
+        "family": "Doe",
+        "given": "John"
+      }
+    ],
+    "issued": {
+      "date-parts": [[1999]]
+    },
+    "title": "Article Title",
+    "container-title": "Journal Name",
+    "volume": "1",
+    "page": "1-10"
+  },
+  {
+    "id": "smith2000",
+    "type": "book",
+    "author": [
+      {
+        "family": "Smith",
+        "given": "Jane"
+      }
+    ],
+    "issued": {
+      "date-parts": [[2000]]
+    },
+    "title": "Book Title",
+    "publisher": "Publisher"
+  }
+]
+
+```
+
+### CSL YAML Example
+
+```yaml
+- id: doe99
+  type: article-journal
+  author:
+    - family: Doe
+      given: John
+  issued:
+    date-parts:
+      - - 1999
+  title: Article Title
+  container-title: Journal Name
+  volume: 1
+  page: 1-10
+
+- id: smith2000
+  type: book
+  author:
+    - family: Smith
+      given: Jane
+  issued:
+    date-parts:
+      - - 2000
+  title: Book Title
+  publisher: Publisher
+
+```
+
+## Testing Commands
+
+To test what different tools produce:
+
+```bash
+# Pandoc
+pandoc test.md --citeproc --bibliography refs.bib -o test-pandoc.html
+
+# MultiMarkdown (if available)
+multimarkdown test.md -o test-mmd.html
+
+# mmark (if available)
+mmark test.md > test-mmark.xml
+
+```
+
+## Notes
+
+1. **Pandoc** uses CSL (Citation Style Language) for
+
+   formatting, which provides very flexible styling
+
+2. **MultiMarkdown** uses a simpler format, with references
+
+   defined inline or in a separate section
+
+3. **mmark** is specifically designed for RFC documents and
+
+   has special handling for RFC/I-D references
+
+4. All tools generate different HTML structures, so Apex
+
+   should aim for compatibility with the most common format
+   (Pandoc-style) while supporting the syntaxes from all
+   tools