Dave Jarvis' Repositories

git clone https://repo.autonoma.ca/repo/keenwrite.com.git
keenwrite.com / Commits / 7fcf641
blog/2025/08/18/feature-matrix/index.Rmd
To render Mermaid 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 disadvantages.
+a pragmatic solution, it has drawbacks.
### Images, dimensions
support it.
-Note that **Text, underline** is deliberately unsupported by KeenWrite.
-Historically, underlining was developed to compensate for shortcomings
-in early typewriter technology. Namely, a lack of bold or italics. If users
-ache for that newsstand tabloid feel, they'll need to look elsewhere.
+Note that **Text, colour** mixes content (what is written) and presentation
+(how the writing appears), and is therefore unsupported by KeenWrite.
+
+**Text, underline** is also unsupported by KeenWrite. Historically,
+underlining was developed to compensate for shortcomings in early typewriter
+technology. Namely, a lack of bold or italics. If users ache for that newsstand
+tabloid feel, they'll need to look elsewhere.
# Diagram code blocks
blog/2025/08/18/feature-matrix/index.html
}
</style>
-<meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/><meta content="1739" name="count"/><title>Text format feature matrix</title></head><body><h1 id="markdown">Markdown</h1>
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/><meta content="1747" name="count"/><title>Text format feature matrix</title></head><body><h1 id="markdown">Markdown</h1>
<div class="byline">
<p>Dave Jarvis, Aug 25, 2025</p>
<p>The purpose of this page is to help dispel the notion that Markdown is inferior
to other text formats for technical documentation. Rather, they each have their
-own strengths and weaknesses. Further, the page provides the starting point for
-an objective way to evaluate various formats for specific needs. Keep in mind
-that tools such as pandoc can do a terrific job at converting between formats.</p>
+own strengths and weaknesses. The table provides an objective way to evaluate
+formats for specific needs. Keep in mind that tools such as pandoc can do a
+terrific job at converting between formats.</p>
<p>Full disclosure: I developed KeenWrite, a desktop Markdown editor and
command-line application. While the feature matrix is fairly comprehensive, if
you spot a critical omission, <a href="/contact.shtml">contact me</a>.</p>
<p>The <a href="matrix.ods">downloadable</a> feature matrix is an unweighted comparison of
various plain text systems:</p>
-<p><span class="caption">Feature matrix comparison</span></p>
<p>
</p><table>
<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">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">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">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, 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">52</td><td align="left">59</td><td align="left">63</td><td align="left">48</td><td align="left">59</td><td align="left">40</td><td align="left">51</td><td align="left">36</td><td align="left">42</td><td align="left">53</td><td align="left">53</td><td align="left">57</td></tr>
+<tr><td align="left">Total</td><td align="left">50</td><td align="left">59</td><td align="left">63</td><td align="left">48</td><td align="left">59</td><td align="left">40</td><td align="left">51</td><td align="left">36</td><td align="left">42</td><td align="left">53</td><td align="left">53</td><td align="left">57</td></tr>
</tbody>
</table>
marking up instructions for drawing a diagram, technical or otherwise.</p>
<h3 id="diagrams-variables-interpolated">Diagrams, variables, interpolated</h3>
-<p>The <strong>Diagrams, variables, interpolated</strong> row means the ability to reference
-interpolated variables within diagrams. For example, a genealogy diagram could
-include family names from an externally defined character sheet:</p>
+<p>The <strong>Diagrams, variables, interpolated</strong> row means embedding interpolated
+variables into diagrams. For example, a genealogy diagram could include family
+names from an externally defined character sheet:</p>
<pre><code>``` diagram-blockdiag
blockdiag {
<h3 id="diagrams-mermaid">Diagrams, Mermaid</h3>
<p>The <strong>Diagrams, Mermaid</strong> rows signify various aspects of exporting diagrams
-codified using the text-based Mermaid syntax.</p>
+coded using the text-based Mermaid syntax.</p>
<ul>
<li><strong>Raster</strong> -- Diagrams render as pixel-based images.</li>
<p>To render Mermaid 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 disadvantages.</p>
+a pragmatic solution, it has drawbacks.</p>
<h3 id="images-dimensions">Images, dimensions</h3>
<p>The <strong>Images, dimensions</strong> row captures the ability to resize images in the
equations, and sections are algorithms, musical scores, lyrics, source
listings, and more. If users can add and refer to their own cross-reference
-labels, including internationalizd ones, the <strong>Cross-references, custom</strong>
+labels, including internationalized ones, the <strong>Cross-references, custom</strong>
row is marked with a <code>Y</code>.</p>
<p>Existing Markdown implementations have fairly similar syntaxes for
<code>Y</code>.</p>
<h3 id="curls-quotation-marks-comprehensive">Curls quotation marks, comprehensive</h3>
-<p>The <strong>Curls quotations marks, comprehensive</strong> row describes systems that can
-curl single quotes correctly. Phrases such as “fish ’n’ chips,” “’Bout that
+<p>The <strong>Curls quotations marks, comprehensive</strong> row describes systems that
+properly format quotation marks. Phrases such as “fish ’n’ chips,” “’Bout that
time I says, ‘Boys! I been thinkin’ ’bout th’ Universe,’” or quotations that
span multiple paragraphs must be curled.</p>
<p>KeenWrite integrates KeenQuotes, a natural language parsing library that can
-determine how to curl single quotes, double quotes, contractions, and mark
-primes. Systems must pass KeenQuote’s test suite using naturally entered
-quotation marks (i.e., " and ') to be marked as a <code>Y</code>.</p>
+determine how to format single quotation marks, double quotes, contractions,
+and mark primes. Systems must pass KeenQuote’s test suite using naturally
+entered quotation marks (i.e., " and ') to be marked as a <code>Y</code>.</p>
<h3 id="collate-chapters">Collate chapters</h3>
<p>The <strong>Collate chapters</strong> row describes whether individual document files---in
built-in functionality, it is marked as <code>N</code>, regardless of whether extensions
support it.</p>
-<p>Note that <strong>Text, underline</strong> is deliberately unsupported by KeenWrite.
-Historically, underlining was developed to compensate for shortcomings
-in early typewriter technology. Namely, a lack of bold or italics. If users
-ache for that newsstand tabloid feel, they’ll need to look elsewhere.</p>
+<p>Note that <strong>Text, colour</strong> mixes content (what is written) and presentation
+(how the writing appears), and is therefore unsupported by KeenWrite.</p>
+<p><strong>Text, underline</strong> is also unsupported by KeenWrite. Historically,
+underlining was developed to compensate for shortcomings in early typewriter
+technology. Namely, a lack of bold or italics. If users ache for that newsstand
+tabloid feel, they’ll need to look elsewhere.</p>
<h1 id="diagram-code-blocks">Diagram code blocks</h1>
<p>KeenWrite distinguishes between diagrams and source code listings by prefixing
blog/2025/08/18/feature-matrix/matrix.csv
"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 --",Y,Y,Y,N,N,N,N,Y,Y,Y,Y,Y
-"Text, dashes, em ---",Y,Y,Y,Y,Y,N,N,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,52,59,63,48,59,40,51,36,42,53,53,57
+Total,50,59,63,48,59,40,51,36,42,53,53,57
blog/2025/08/18/feature-matrix/matrix.ods
Binary files differ

Updates dashes tallies

Author Dave Jarvis <email>
Date 2025-08-25 01:09:55 GMT-0700
Commit 7fcf64178bad76f73f9cfec2067942ba52a6f90e
Parent 75f0279
Delta 35 lines added, 31 lines removed, 4-line increase