Dave Jarvis' Repositories

git clone https://repo.autonoma.ca/repo/keenwrite.com.git
keenwrite.com / Commits / 9f14d75
blog/2025/08/18/feature-matrix/bootstrap.R
+source( 'csv.R' )
+
blog/2025/08/18/feature-matrix/build.sh
+#!/usr/bin/env bash
+
+java -jar /tmp/keenwrite.jar \
+ -i index.Rmd \
+ -o index.xhtml \
+ --curl-quotes=rsquo \
+ --variables=$(pwd)/metadata.yaml \
+ --r-script=$(pwd)/bootstrap.R \
+ --r-dir=$(pwd) \
+ --html-head="$(pwd)/head.html" \
+ --html-foot="$(pwd)/foot.html"
+
+mv index.xhtml index.html
blog/2025/08/18/feature-matrix/csv.R
+# -----------------------------------------------------------------------------
+# Copyright 2020, White Magic Software, Ltd.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# Converts CSV to Markdown.
+#
+# Reads a CSV file and converts the contents to a Markdown table. The
+# file must be in the working directory as specified by setwd.
+#
+# @param f The file name to convert.
+# @param decimals Rounded decimal places (default 2).
+# @param totals Include total sums (default TRUE).
+# @param align Right-align numbers (default TRUE).
+# -----------------------------------------------------------------------------
+csv2md <- function( f, decimals = 2, totals = T, align = T, caption = "" ) {
+ # Read the CVS data from the file; ensure strings become characters.
+ df <- read.table( f, sep=',', header=T, stringsAsFactors=F, check.names=F )
+
+ if( totals ) {
+ # Determine what columns can be summed.
+ number <- which( unlist( lapply( df, is.numeric ) ) )
+
+ # Use colSums when more than one summable column exists.
+ if( length( number ) > 1 ) {
+ f.sum <- colSums
+ }
+ else {
+ f.sum <- sum
+ }
+
+ # Calculate the sum of all the summable columns and insert the
+ # results back into the data frame.
+ df[ (nrow( df ) + 1), number ] <- f.sum( df[, number], na.rm=TRUE )
+
+ # pluralize would be heavyweight here.
+ if( length( number ) > 1 ) {
+ t <- "Totals"
+ }
+ else {
+ t <- "Total"
+ }
+
+ # Change the first column of the last line to "Total(s)".
+ df[ nrow( df ), 1 ] <- t
+
+ # Don't clutter the output with "NA" text.
+ df[ is.na( df ) ] <- ""
+ }
+
+ if( align ) {
+ is.char <- vapply( df, is.character, logical( 1 ) )
+ dashes <- paste( ifelse( is.char, ':---', '---:' ), collapse = '|' )
+ }
+ else {
+ dashes <- paste( rep( '---', length( df ) ), collapse = '|' )
+ }
+
+ # Use pandoc syntax for table captions.
+ if( caption != "" ) {
+ caption <- paste( '\n[', caption, ']\n', sep='' )
+ }
+
+ # Create a Markdown version of the data frame.
+ paste(
+ '|', paste( names( df ), collapse = '|'), '|', '\n',
+ '|', dashes, '|', '\n',
+ paste(
+ '|',
+ Reduce( function( x, y ) {
+ paste( x, format( y, nsmall = decimals ), sep = '|' )
+ }, df
+ ),
+ collapse = '|\n',sep=''
+ ),
+ '|',
+ caption,
+ sep=''
+ )
+}
+
blog/2025/08/18/feature-matrix/foot.html
+<footer>Goodbye, world!</footer>
+<script src="js/filename.js">
blog/2025/08/18/feature-matrix/head.html
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="description" content="cross-platform, open-source desktop editor">
+<meta name="keywords" content="markdown, text, editor, software">
+<meta name="robots" content="index, follow">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline';">
+<link rel="stylesheet" href="../../../../../styles/base.css">
+<style>
+table {
+ font-family: sans-serif;
+ margin: 0 auto;
+ border-collapse: collapse;
+}
+
+thead {
+ background-color: #666;
+ position: sticky;
+ top: 0px;
+}
+
+th, td {
+ padding: 0 0.5em;
+}
+
+th {
+ padding-top: .25em;
+ padding-bottom: .25em;
+}
+
+thead th:not(first-child) {
+ writing-mode: vertical-rl;
+ transform: rotate(180deg);
+}
+
+thead th:first-child {
+ transform: rotate(225deg) translate( 0%, 25% );
+}
+
+tbody td:not(:first-child) {
+ text-align: center;
+}
+
+tbody tr:nth-child(even) {
+ background-color: rgba(0, 0, 0, .25);
+}
+
+tbody tr:last-child td {
+ font-weight: bold;
+ border-top: 1px solid;
+}
+
+a, a:visited {
+ color: var( --link-colour );
+}
+
+a:link:hover, a:visited:hover {
+ color: var( --accent-colour );
+}
+
+div.byline {
+ font-size: 10pt;
+}
+</style>
blog/2025/08/18/feature-matrix/index.Rmd
+# Markdown
+
+::: byline
+Dave Jarvis, Aug 20, 2025
+:::
+
+Markdown is a versatile plain text document format, as these examples show:
+
+* [Impacts](https://impacts.to/downloads/lowres/impacts.pdf)
+* [autónoma](pdf/autónoma.pdf) (first page intentionally blank)
+* [Software Design](pdf/software-design.pdf)
+* [Dr. Jekyll and Mr. Hyde](pdf/jekyll-hyde.pdf)
+* [Last Will and Testament](pdf/last-will-and-testament.pdf)
+
+In this post, we'll compare a variety of plain text formats.
+
+Full disclosure: I developed KeenWrite, a Markdown editor. Although I've tried
+to keep the feature matrix objective, [contact me](/contact.shtml) if you spot
+an error.
+
+# Feature matrix
+
+`r# csv2md( 'matrix.csv', totals = F );`
+
+## Images, dimensions
+
+A pandoc extension to CommonMark allows for inline image dimensions:
+
+``` md
+![kitten](kitten.jpg){width=300}
+![kitten](kitten.jpg){#id .class width=300}
+```
+
+Similarly, fenced code blocks support attributes:
+
+ ``` diagram-plantuml { width=400px }
+ ```
+
+## Cross-references
+
+The **Cross-references** rows refer to built-in directives. If the plain text
+syntax assumes a specific typesetting system will be used, it is marked as `N`.
+A plain text format ought not to be bound to a specific typesetter. If the
+syntax is independent of a typesetting system, but needs an external typesetter
+to produce linked cross-reference, it is marked as `Y`.
+
+## Comprehensive quote curling
+
+Many software packages cannot curl single quotes correctly. Phrases such as
+"fish 'n' chips" or quotations that span multiple paragraphs cannot be curled.
+Software must pass KeenQuote's test suite to be marked as a `Y`.
+
+## Collate chapters
+
+The **Collate chapters** row describes whether individual document files---in
+the same directory---can be combined into a single work using built-in software
+tools without requiring them to reference each other. This approach, where a
+program handles the collation (e.g., via a command-line utility), simplifies
+the process and avoids a maintenance burden when adding or removing chapters.
+File systems are well-suited for grouping files. For example:
+
+``` bash
+keenwrite.bin \
+ --all \
+ --chapters="1-12,15,19-" \
+ -i chapter-01.md \
+ -o user-guide.pdf ...
+```
+
+## Text
+
+The **Text** rows refer to built-in directives. If the syntax does not offer
+the functionality out-of-the-box, it is marked as `N`, regardless of whether
+plugins or extensions support it.
+
+# Extending CommonMark
+
+## Limitations
+
+The CommonMark standard was frozen before core features were added that would have made it an easy choice over other plain text formats. Although CommonMark is extensible, such flexibility inevitably leads to fracturing and incompatibilities. Missing features include:
+
+* Consistent captions for figures, tables, equations, algorithms, music, etc.
+* Diagram code blocks
+* Extensible cross-references
+* Citations for bibliographic references
+
+## Consistent captions
+
+KeenWrite supports a double-colon syntax for captions, where the caption comes
+after the element being captioned. Consider the following text:
+
+``` markdown
+| Header | Header |
+|--------|--------|
+| Value | Value |
+
+:: Table caption
+
+![alt text](logo.svg)
+
+:: Image caption
+
+$$E=mc^2$$
+
+:: Equation caption
+```
+
+The blank lines before each caption are mandatory. Sample output:
+
+![document captions](captions.png)
+
+## Diagram code blocks
+
+KeenWrite distinguishes between diagrams and source code listings by prefixing
+diagrams with a `diagram-` prefix, such as:
+
+ ``` diagram-plantuml
+ @startuml
+ Alice -> Bob: Hello
+ @enduml
+ ```
+
+This has a few "benefits." First, it allows rendering diagram types using
+a service without having to codify all possible services. Second, when a new
+type of diagram is added, it's available immediately without needing to
+upgrade. Third, it clearly distinguishes between a code block intented to be
+rendered visually and one intended to be displayed as verbatim source code.
+
+Typically, source code is presented in code blocks that include the language
+name so that syntax highlighting can be applied:
+
+ ``` c
+ main() {
+ printf("hello, world");
+ }
+ ```
+
+GitHub created a _de facto_ standard prevents parsers from dynamically
+distinguishing between a diagram to render and source code to list. That is,
+does the following fenced code block specify a language syntax or should it
+draw a pie chart?
+
+ ``` mermaid
+ pie
+ title Turkish Empire Proportions, 1789
+ "Asia" : 66
+ "Africa" : 20
+ "Europe" : 14
+ ```
+
+While `mermaid-lang` could help, it creates a special case that needs to be
+programmed into Markdown parsers. KeenWrite's `diagram-` prefix side-steps the
+issue while keeping true to the human-readability aspect of Markdown. For this
+reason, using `mermaid` alone for a fenced code block will not draw a diagram.
+
+### Mermaid
+
+At time of writing, Mermaid diagrams cannot be rendered outside of a web
+browser environment by countless programs and libraries. To render such
+diagrams in AsciiDoc, a headless browser extension must be installed.
+AsciiDoctor launches the browser to draw the diagram. While this is
+a pragmatic solution, it has some disadvantages.
+
+
+
+## Cross-references
+
+## Citations
+
+# History
+
+John Gruber created Markdown based on decades of syntax conventions that had evolved in email, mailing lists, Usenet newsgroups, and elsewhere. His original goal was to make a text format that could be easily converted to HTML while remaining human-readable. Instead of `<em>emphasis</em>`, one writes `*emphasis*`. Gruber released a specification alongside a script that converts a Markdown document into valid HTML.
+
+The format gained popularity among developers, leading to its adoption for project README files, which significantly boosted its widespread use.
+
+However, specification ambiguities resulted in conversion software interpreting edge cases differently. This fragmentation prompted John MacFarlane to spearhead CommonMark, a Markdown standard aimed to eliminate ambiguities.
+
blog/2025/08/18/feature-matrix/index.html
-<html><head></head><body><p>Aug 20, 2025</p>
-<h1 id="markdown">Markdown</h1>
-<p>The following Markdown documents show its versatility:</p>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html lang="en" xmlns="http://www.w3.org/1999/xhtml"><head xmlns=""><meta content="width=device-width, initial-scale=1.0" name="viewport"/>
+<meta content="cross-platform, open-source desktop editor" name="description"/>
+<meta content="markdown, text, editor, software" name="keywords"/>
+<meta content="index, follow" name="robots"/>
+<meta content="default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline';" http-equiv="Content-Security-Policy"/>
+<link href="../../../../../styles/base.css" rel="stylesheet"/>
+<style>
+table {
+ font-family: sans-serif;
+ margin: 0 auto;
+ border-collapse: collapse;
+}
+
+thead {
+ background-color: #666;
+ position: sticky;
+ top: 0px;
+}
+
+th, td {
+ padding: 0 0.5em;
+}
+
+th {
+ padding-top: .25em;
+ padding-bottom: .25em;
+}
+
+thead th:not(first-child) {
+ writing-mode: vertical-rl;
+ transform: rotate(180deg);
+}
+
+thead th:first-child {
+ transform: rotate(225deg) translate( 0%, 25% );
+}
+
+tbody td:not(:first-child) {
+ text-align: center;
+}
+
+tbody tr:nth-child(even) {
+ background-color: rgba(0, 0, 0, .25);
+}
+
+tbody tr:last-child td {
+ font-weight: bold;
+ border-top: 1px solid;
+}
+
+a, a:visited {
+ color: var( --link-colour );
+}
+
+a:link:hover, a:visited:hover {
+ color: var( --accent-colour );
+}
+
+div.byline {
+ font-size: 10pt;
+}
+</style>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/><meta content="1053" name="count"/><title>Text format feature matrix</title></head><body><h1 id="markdown">Markdown</h1>
+<div class="byline">
+<p>Dave Jarvis, Aug 20, 2025</p>
+</div>
+<p>Markdown is a versatile plain text document format, as these examples show:</p>
<ul>
<li><a href="https://impacts.to/downloads/lowres/impacts.pdf">Impacts</a></li>
-<li><a href="pdf/autónoma.pdf">autónoma</a></li>
+<li><a href="pdf/autónoma.pdf">autónoma</a> (first page intentionally blank)</li>
<li><a href="pdf/software-design.pdf">Software Design</a></li>
-<li><a href="pdf/jekyll-hyde.pdf">Jekyll and Mr. Hyde</a></li>
+<li><a href="pdf/jekyll-hyde.pdf">Dr. Jekyll and Mr. Hyde</a></li>
<li><a href="pdf/last-will-and-testament.pdf">Last Will and Testament</a></li>
</ul>
-<p>Let's explore a feature matrix comparing common technical writing text formats,
-which I hope may dispel some misunderstandings.</p>
-<p>Full disclosure: I'm the main author of KeenWrite, a Markdown text editor.
-While I've tried to make this post unbiased, there may be errors. Please
-<a href="/contact.shtml">contact me</a> with your corrections or suggestions.</p>
-<h1 id="features">Features</h1>
-<h2 id="text">Text</h2>
-<p>The <strong>Text</strong> rows refer to built-in directives. If the syntax does not offer
-the functionality out-of-the-box, it is marked as <code>N</code>, regardless of whether
-plugins or extensions support it.</p>
+<p>In this post, we’ll compare a variety of plain text formats.</p>
+<p>Full disclosure: I developed KeenWrite, a Markdown editor. Although I’ve tried
+to keep the feature matrix objective, <a href="/contact.shtml">contact me</a> if you spot
+an error.</p>
+<h1 id="feature-matrix">Feature matrix</h1>
+<p>
+</p><table>
+<thead>
+<tr><th align="left">Feature matrix</th><th align="left">KeenWrite</th><th align="left">KeenWrite / ConTeXt</th><th align="left">KeenWrite / ConTeXt / R Markdown</th><th align="left">AsciiDoc</th><th align="left">AsciiDoc / extensions</th><th align="left">reStructuredText</th><th align="left">Sphinx</th><th align="left">pandoc</th><th align="left">pandoc / LaTeX</th><th align="left">pandoc / extensions / LaTeX</th><th align="left">pandoc / extensions / LaTeX</th><th align="left">pandoc / extensions / knitr / LaTeX</th></tr>
+</thead>
+<tbody>
+<tr><td align="left">Turing complete, R</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Images</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Images, dimensions</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Tables</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Tables, nested</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Math, SVG</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Math, KaTeX (HTML)</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Math, MathJax (HTML)</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Math, PDF</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Footnotes</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Endnotes</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Variables (attributes)</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Variables, interpolated</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Diagrams, text-based</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Diagrams, interpolated variables</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Diagrams, MermaidJS, raster, PDF</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Diagrams, MermaidJS, vector, PDF</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Diagrams, MermaidJS, HTML</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Captions, table</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Captions, image</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Captions, equation</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Captions, code block</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Captions, consistency</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Cross-references, section</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Cross-references, table</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Cross-references, figure</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Cross-references, equation</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Cross-references, custom</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Bibliographic references (citations)</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Metadata</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Metadata, external</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Metadata, editor-integrated</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">n/a</td><td align="left">n/a</td><td align="left">n/a</td><td align="left">n/a</td><td align="left">n/a</td><td align="left">n/a</td><td align="left">n/a</td></tr>
+<tr><td align="left">Content, external</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Content, conditional</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td></tr>
+<tr><td align="left">JSON parsing</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td></tr>
+<tr><td align="left">Export, plain text</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Export, XHTML</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Export, PDF</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Knuth–Plass algorithm</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Custom containers (annotations, roles)</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Interface, command-line</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Interface, graphical (with preview)</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Content vs. Presentation</td><td align="left">n/a</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">n/a</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Unicode</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Data plots, inline</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td></tr>
+<tr><td align="left">Curls quotation marks, natural</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Curls quotation marks, contextual</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Curls quotation marks, comprehensive</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Collate chapters</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Widespread syntax knowledge</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Community support</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Accessible HTML</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Glossary generator</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, colour</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, underline</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Text, overline</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Text, ligatures</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, hyperlink</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, superscripts</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, subscripts</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, strikethrough</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, strong</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, emphasis</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, monospace</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, inline nesting</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, quotation blocks</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, quotation blocks, nested</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, description lists</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, code blocks</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, code blocks, language</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, dashes, en --</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, dashes, em ---</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, ellipses …</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, arrows -&gt; =&gt; &lt;= &lt;-</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Text, (C) (R) (TM)</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td></tr>
+<tr><td align="left">Text, entities, numeric</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, entities, named</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Text, non-breaking spaces</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">N</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td><td align="left">Y</td></tr>
+<tr><td align="left">Total</td><td align="left">49</td><td align="left">58</td><td align="left">61</td><td align="left">47</td><td align="left">56</td><td align="left">39</td><td align="left">50</td><td align="left">36</td><td align="left">42</td><td align="left">52</td><td align="left">52</td><td align="left">55</td></tr>
+</tbody>
+</table>
+<p/>
+<h2 id="images-dimensions">Images, dimensions</h2>
+<p>A pandoc extension to CommonMark allows for inline image dimensions:</p>
+<pre><code class="language-md">![kitten](kitten.jpg){width=300}
+![kitten](kitten.jpg){#id .class width=300}
+</code></pre>
+<p>Similarly, fenced code blocks support attributes:</p>
+<pre><code>``` diagram-plantuml { width=400px }
+```
+</code></pre>
<h2 id="cross-references">Cross-references</h2>
<p>The <strong>Cross-references</strong> rows refer to built-in directives. If the plain text
syntax assumes a specific typesetting system will be used, it is marked as <code>N</code>.
A plain text format ought not to be bound to a specific typesetter. If the
syntax is independent of a typesetting system, but needs an external typesetter
to produce linked cross-reference, it is marked as <code>Y</code>.</p>
+<h2 id="comprehensive-quote-curling">Comprehensive quote curling</h2>
+<p>Many software packages cannot curl single quotes correctly. Phrases such as
+“fish ’n’ chips” or quotations that span multiple paragraphs cannot be curled.
+Software must pass KeenQuote’s test suite to be marked as a <code>Y</code>.</p>
<h2 id="collate-chapters">Collate chapters</h2>
<p>The <strong>Collate chapters</strong> row describes whether individual document files---in
the same directory---can be combined into a single work using built-in software
tools without requiring them to reference each other. This approach, where a
program handles the collation (e.g., via a command-line utility), simplifies
the process and avoids a maintenance burden when adding or removing chapters.
-File systems are well-suited for grouping files.</p>
+File systems are well-suited for grouping files. For example:</p>
+<pre><code class="language-bash">keenwrite.bin \
+ --all \
+ --chapters="1-12,15,19-" \
+ -i chapter-01.md \
+ -o user-guide.pdf ...
+</code></pre>
+<h2 id="text">Text</h2>
+<p>The <strong>Text</strong> rows refer to built-in directives. If the syntax does not offer
+the functionality out-of-the-box, it is marked as <code>N</code>, regardless of whether
+plugins or extensions support it.</p>
<h1 id="extending-commonmark">Extending CommonMark</h1>
<h2 id="limitations">Limitations</h2>
:: Equation caption
</code></pre>
-<p>Note the blank lines before the caption. Sample output:</p>
-<p><img src="captions.png" alt="captions" /></p>
+<p>The blank lines before each caption are mandatory. Sample output:</p>
+<p><img alt="document captions" src="captions.png"/></p>
<h2 id="diagram-code-blocks">Diagram code blocks</h2>
-<p>KeenWrite distinguishes between diagrams to draw and source code blocks to
-list by using a <code>diagram-</code> prefix, such as:</p>
+<p>KeenWrite distinguishes between diagrams and source code listings by prefixing
+diagrams with a <code>diagram-</code> prefix, such as:</p>
<pre><code>``` diagram-plantuml
@startuml
Alice -&gt; Bob: Hello
@enduml
```
</code></pre>
-<p>This has a few "benefits." First, it allows rendering diagram types using
+<p>This has a few “benefits.” First, it allows rendering diagram types using
a service without having to codify all possible services. Second, when a new
-type of diagram is added, it's available immediately without needing to
+type of diagram is added, it’s available immediately without needing to
upgrade. Third, it clearly distinguishes between a code block intented to be
-rendered as a figure and one intended to be displayed as verbatim source code.</p>
+rendered visually and one intended to be displayed as verbatim source code.</p>
<p>Typically, source code is presented in code blocks that include the language
name so that syntax highlighting can be applied:</p>
<pre><code>``` c
main() {
printf("hello, world");
}
```
</code></pre>
-<p>GitHub created a <em>de facto</em> standard that introduces a thorny problem. Does
-the following code block show the source code with syntax highlighting, like
-for other source code snippets, or does it draw the pie chart?</p>
+<p>GitHub created a <em>de facto</em> standard prevents parsers from dynamically
+distinguishing between a diagram to render and source code to list. That is,
+does the following fenced code block specify a language syntax or should it
+draw a pie chart?</p>
<pre><code>``` mermaid
pie
title Turkish Empire Proportions, 1789
"Asia" : 66
"Africa" : 20
"Europe" : 14
```
</code></pre>
-<p>Using <code>mermaid-lang</code> would solve the issue, although there'd be no equivalent
-for <code>c-lang</code>. Still, KeenWrite's <code>diagram-</code> prefix side-steps the problem.</p>
+<p>While <code>mermaid-lang</code> could help, it creates a special case that needs to be
+programmed into Markdown parsers. KeenWrite’s <code>diagram-</code> prefix side-steps the
+issue while keeping true to the human-readability aspect of Markdown. For this
+reason, using <code>mermaid</code> alone for a fenced code block will not draw a diagram.</p>
<h3 id="mermaid">Mermaid</h3>
+<p>At time of writing, Mermaid diagrams cannot be rendered outside of a web
+browser environment by countless programs and libraries. To render such
+diagrams in AsciiDoc, a headless browser extension must be installed.
+AsciiDoctor launches the browser to draw the diagram. While this is
+a pragmatic solution, it has some disadvantages.</p>
<h2 id="cross-references-1">Cross-references</h2>
<h2 id="citations">Citations</h2>
<h1 id="history">History</h1>
<p>John Gruber created Markdown based on decades of syntax conventions that had evolved in email, mailing lists, Usenet newsgroups, and elsewhere. His original goal was to make a text format that could be easily converted to HTML while remaining human-readable. Instead of <code>&lt;em&gt;emphasis&lt;/em&gt;</code>, one writes <code>*emphasis*</code>. Gruber released a specification alongside a script that converts a Markdown document into valid HTML.</p>
<p>The format gained popularity among developers, leading to its adoption for project README files, which significantly boosted its widespread use.</p>
<p>However, specification ambiguities resulted in conversion software interpreting edge cases differently. This fragmentation prompted John MacFarlane to spearhead CommonMark, a Markdown standard aimed to eliminate ambiguities.</p>
-</body></html>
+<footer>Goodbye, world!</footer>
+<script src="js/filename.js">
+</script></body></html>
blog/2025/08/18/feature-matrix/index.md
-Aug 20, 2025
-
-# Markdown
-
-The following Markdown documents show its versatility:
-
-* [Impacts](https://impacts.to/downloads/lowres/impacts.pdf)
-* [autónoma](pdf/autónoma.pdf)
-* [Software Design](pdf/software-design.pdf)
-* [Jekyll and Mr. Hyde](pdf/jekyll-hyde.pdf)
-* [Last Will and Testament](pdf/last-will-and-testament.pdf)
-
-Let's explore a feature matrix comparing common technical writing text formats,
-which I hope may dispel some misunderstandings.
-
-Full disclosure: I'm the main author of KeenWrite, a Markdown text editor.
-While I've tried to make this post unbiased, there may be errors. Please
-[contact me](/contact.shtml) with your corrections or suggestions.
-
-# Features
-
-
-
-## Text
-
-The **Text** rows refer to built-in directives. If the syntax does not offer
-the functionality out-of-the-box, it is marked as `N`, regardless of whether
-plugins or extensions support it.
-
-## Cross-references
-
-The **Cross-references** rows refer to built-in directives. If the plain text
-syntax assumes a specific typesetting system will be used, it is marked as `N`.
-A plain text format ought not to be bound to a specific typesetter. If the
-syntax is independent of a typesetting system, but needs an external typesetter
-to produce linked cross-reference, it is marked as `Y`.
-
-## Collate chapters
-
-The **Collate chapters** row describes whether individual document files---in
-the same directory---can be combined into a single work using built-in software
-tools without requiring them to reference each other. This approach, where a
-program handles the collation (e.g., via a command-line utility), simplifies
-the process and avoids a maintenance burden when adding or removing chapters.
-File systems are well-suited for grouping files.
-
-# Extending CommonMark
-
-## Limitations
-
-The CommonMark standard was frozen before core features were added that would have made it an easy choice over other plain text formats. Although CommonMark is extensible, such flexibility inevitably leads to fracturing and incompatibilities. Missing features include:
-
-* Consistent captions for figures, tables, equations, algorithms, music, etc.
-* Diagram code blocks
-* Extensible cross-references
-* Citations for bibliographic references
-
-## Consistent captions
-
-KeenWrite supports a double-colon syntax for captions, where the caption comes
-after the element being captioned. Consider the following text:
-
-``` markdown
-| Header | Header |
-|--------|--------|
-| Value | Value |
-
-:: Table caption
-
-![alt text](logo.svg)
-
-:: Image caption
-
-$$E=mc^2$$
-
-:: Equation caption
-```
-
-Note the blank lines before the caption. Sample output:
-
-![captions](captions.png)
-
-## Diagram code blocks
-
-KeenWrite distinguishes between diagrams to draw and source code blocks to
-list by using a `diagram-` prefix, such as:
-
- ``` diagram-plantuml
- @startuml
- Alice -> Bob: Hello
- @enduml
- ```
-
-This has a few "benefits." First, it allows rendering diagram types using
-a service without having to codify all possible services. Second, when a new
-type of diagram is added, it's available immediately without needing to
-upgrade. Third, it clearly distinguishes between a code block intented to be
-rendered as a figure and one intended to be displayed as verbatim source code.
-
-Typically, source code is presented in code blocks that include the language
-name so that syntax highlighting can be applied:
-
- ``` c
- main() {
- printf("hello, world");
- }
- ```
-
-GitHub created a _de facto_ standard prevents parsers from dynamically
-distinguishing between a diagram to render and source code to list. That is,
-does the following fenced code block specify a language syntax or should it
-draw a pie chart?
-
- ``` mermaid
- pie
- title Turkish Empire Proportions, 1789
- "Asia" : 66
- "Africa" : 20
- "Europe" : 14
- ```
-
-While `mermaid-lang` could help, it creates a special case that needs to be
-programmed into Markdown parsers. KeenWrite's `diagram-` prefix side-steps the
-issue while keeping true to the human-readability aspect of Markdown. For this
-reason, using `mermaid` alone for a fenced code block will not draw a diagram.
-
-### Mermaid
-
-At time of writing,
-
-
-
-## Cross-references
-
-## Citations
-
-# History
-
-John Gruber created Markdown based on decades of syntax conventions that had evolved in email, mailing lists, Usenet newsgroups, and elsewhere. His original goal was to make a text format that could be easily converted to HTML while remaining human-readable. Instead of `<em>emphasis</em>`, one writes `*emphasis*`. Gruber released a specification alongside a script that converts a Markdown document into valid HTML.
-
-The format gained popularity among developers, leading to its adoption for project README files, which significantly boosted its widespread use.
-
-However, specification ambiguities resulted in conversion software interpreting edge cases differently. This fragmentation prompted John MacFarlane to spearhead CommonMark, a Markdown standard aimed to eliminate ambiguities.
-
blog/2025/08/18/feature-matrix/matrix.csv
+Feature matrix,KeenWrite,KeenWrite / ConTeXt,KeenWrite / ConTeXt / R Markdown,AsciiDoc,AsciiDoc / extensions,reStructuredText,Sphinx,pandoc,pandoc / LaTeX,pandoc / extensions / LaTeX,pandoc / extensions / LaTeX,pandoc / extensions / knitr / LaTeX
+"Turing complete, R",N,Y,Y,N,Y,N,N,N,Y,Y,Y,Y
+Images,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Images, dimensions",N,N,N,Y,Y,Y,Y,Y,Y,Y,Y,Y
+Tables,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Tables, nested",N,N,N,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Math, SVG",Y,Y,Y,N,N,N,N,N,N,N,N,N
+"Math, KaTeX (HTML)",Y,Y,Y,N,Y,N,Y,N,N,N,N,N
+"Math, MathJax (HTML)",Y,Y,Y,N,Y,Y,Y,Y,Y,Y,Y,Y
+"Math, PDF",N,Y,Y,N,Y,N,Y,N,Y,Y,Y,Y
+Footnotes,Y,Y,Y,N,N,Y,Y,Y,Y,Y,Y,Y
+Endnotes,N,N,N,Y,Y,N,N,Y,Y,Y,Y,Y
+Variables (attributes),Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Variables, interpolated",Y,Y,Y,N,N,N,N,N,N,N,N,N
+"Diagrams, text-based",Y,Y,Y,Y,Y,N,Y,N,N,N,N,N
+"Diagrams, interpolated variables",Y,Y,Y,N,N,N,N,N,N,N,N,N
+"Diagrams, MermaidJS, raster, PDF",N,N,N,N,Y,N,N,N,N,N,N,N
+"Diagrams, MermaidJS, vector, PDF",N,N,N,N,N,N,N,N,N,N,N,N
+"Diagrams, MermaidJS, HTML",Y,Y,Y,N,Y,Y,Y,N,N,Y,Y,Y
+"Captions, table",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Captions, image",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Captions, equation",Y,Y,Y,N,Y,Y,Y,N,Y,Y,Y,Y
+"Captions, code block",N,N,N,Y,Y,N,Y,N,N,N,N,N
+"Captions, consistency",Y,Y,Y,N,N,Y,Y,N,N,N,N,N
+"Cross-references, section",Y,Y,Y,Y,Y,N,Y,N,N,Y,Y,Y
+"Cross-references, table",Y,Y,Y,Y,Y,Y,Y,N,N,Y,Y,Y
+"Cross-references, figure",Y,Y,Y,Y,Y,Y,Y,N,N,Y,Y,Y
+"Cross-references, equation",Y,Y,Y,N,N,Y,Y,N,N,Y,Y,Y
+"Cross-references, custom",N,Y,Y,N,N,N,N,N,N,N,N,N
+Bibliographic references (citations),N,N,N,Y,Y,Y,Y,N,N,Y,Y,Y
+Metadata,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Metadata, external",Y,Y,Y,N,N,N,N,N,N,N,N,N
+"Metadata, editor-integrated",Y,Y,Y,N,N,n/a,n/a,n/a,n/a,n/a,n/a,n/a
+"Content, external",N,N,Y,Y,Y,N,Y,N,N,Y,Y,Y
+"Content, conditional",N,N,Y,Y,Y,N,Y,N,N,N,N,Y
+JSON parsing,N,N,Y,N,Y,N,N,N,N,N,N,Y
+"Export, plain text",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Export, XHTML",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Export, PDF",N,Y,Y,N,Y,N,Y,N,Y,Y,Y,Y
+Knuth–Plass algorithm,N,Y,Y,N,N,N,N,N,Y,Y,Y,Y
+"Custom containers (annotations, roles)",Y,Y,Y,Y,Y,Y,Y,N,N,Y,Y,Y
+"Interface, command-line",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Interface, graphical (with preview)",Y,Y,Y,Y,Y,N,N,N,N,N,N,N
+Content vs. Presentation,n/a,Y,Y,N,N,N,Y,n/a,N,N,N,N
+Unicode,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Data plots, inline",N,N,Y,N,N,N,N,N,N,N,N,Y
+"Curls quotation marks, natural",Y,Y,Y,N,N,N,N,N,N,N,N,N
+"Curls quotation marks, contextual",Y,Y,Y,Y,Y,N,N,Y,Y,Y,Y,Y
+"Curls quotation marks, comprehensive",Y,Y,Y,N,N,N,N,N,N,N,N,N
+Collate chapters,Y,Y,Y,N,N,N,Y,N,N,N,N,N
+Widespread syntax knowledge,Y,Y,N,N,N,N,Y,Y,Y,Y,Y,Y
+Community support,N,N,N,Y,Y,Y,Y,Y,Y,Y,Y,Y
+Accessible HTML,N,N,N,N,N,Y,Y,N,N,N,N,N
+Glossary generator,N,N,N,N,N,Y,Y,N,N,Y,Y,Y
+"Text, colour",N,N,N,Y,Y,N,N,N,N,Y,Y,Y
+"Text, underline",N,N,N,Y,Y,Y,Y,N,N,N,N,N
+"Text, overline",N,N,N,Y,Y,N,N,N,N,N,N,N
+"Text, ligatures",N,Y,Y,N,N,N,N,N,Y,Y,Y,Y
+"Text, hyperlink",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, superscripts",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, subscripts",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, strikethrough",Y,Y,Y,Y,Y,N,N,Y,Y,Y,Y,Y
+"Text, strong",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, emphasis",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, monospace",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, inline nesting",Y,Y,Y,Y,Y,N,N,Y,Y,Y,Y,Y
+"Text, quotation blocks",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, quotation blocks, nested",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, description lists",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, code blocks",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, code blocks, language",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, dashes, en --",N,Y,Y,N,N,N,N,Y,Y,Y,Y,Y
+"Text, dashes, em ---",N,Y,Y,Y,Y,N,N,Y,Y,Y,Y,Y
+"Text, ellipses ...",Y,Y,Y,Y,Y,N,N,Y,Y,Y,Y,Y
+"Text, arrows -> => <= <-",N,N,N,Y,Y,N,N,N,N,N,N,N
+"Text, (C) (R) (TM)",N,N,N,Y,Y,N,N,N,N,N,N,N
+"Text, entities, numeric",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, entities, named",Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y,Y
+"Text, non-breaking spaces",N,N,N,N,N,N,N,Y,Y,Y,Y,Y
+Total,49,58,61,47,56,39,50,36,42,52,52,55
blog/2025/08/18/feature-matrix/matrix.ods
Binary files differ
blog/2025/08/18/feature-matrix/metadata.yaml
+document:
+ title: Text format feature matrix
+
blog/2025/08/18/feature-matrix/text-shoot-out.ods
Binary files differ
index.shtml
-<!DOCTYPE html>
-<html lang="en">
-<head>
- <title>KeenWrite</title>
- <meta charset="UTF-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="description" content="cross-platform, open-source desktop editor">
- <meta name="keywords" content="markdown, text, editor, software">
- <meta name="robots" content="index, follow">
- <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline';">
- <style><!--#include file="styles/base.css" --></style>
-</head>
-<body>
-<header>
- <img src="images/logo/title.svg" alt="KeenWrite" class="title">
- <p>
- A free, cross-platform desktop text editor for producing beautifully
- typeset PDF files.
- </p>
-</header>
-<main>
- <div class="downloads">
- <a href="downloads/keenwrite.bin"
- class="download"
- title="Download for 64-bit Linux (x86)"
- aria-label="Download for Linux"><img
- src="images/icons/linux.svg"
- alt="Download for Linux"
- class="download"></a>
- <a href="downloads/keenwrite.jar"
- class="download"
- title="Download for Java virtual machine"
- aria-label="Download for Java"><img
- src="images/icons/java.svg"
- alt="Download for Java"
- class="download"></a>
- <a href="downloads/KeenWrite.exe"
- class="download"
- title="Download for 64-bit Windows (x86)"
- aria-label="Download for Windows"><img
- src="images/icons/windows.svg"
- alt="Download for Windows"
- class="download"></a>
- <a href="downloads/keenwrite.app"
- class="download"
- title="Download for 64-bit MacOS (x86)"
- aria-label="Download for MacOS"><img
- src="images/icons/apple.svg"
- alt="Download for MacOS"
- class="download"></a>
- </div>
- <!--#config timefmt="%d-%b-%Y" -->
- <p class="version">
- <strong>Version <!--#include file="downloads/version.txt" --></strong>
- <br><!--#flastmod virtual="downloads/version.txt" -->
- <br><!--#exec cmd="./count.sh" --> downloads
- </p>
-</main>
-<nav>
- <ul>
- <li><a href="screenshots.html">screenshots</a></li>
- <li><a href="https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9KWzPIoWZMKu_">tutorials</a></li>
- <li><a href="https://gitlab.com/DaveJarvis/KeenWrite">sources</a></li>
- <li><a href="https://gitlab.com/DaveJarvis/KeenWrite/issues">issues</a></li>
- <li><a href="https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/README.md">documentation</a></li>
- </ul>
-</nav>
-<footer>
- &copy; 2023, White Magic Software, Ltd.
-</footer>
-</body>
-</html>
-

Adds matrix data, updates blog post

Author Dave Jarvis <email>
Date 2025-08-23 02:51:53 GMT-0700
Commit 9f14d75219757f89844db8447effdc44cd888bad
Parent ad9a167
Delta 648 lines added, 246 lines removed, 402-line increase