Re: [BUG] ox-md image captions

[Ihor Radchenko]

Morgan Willcock <morgan@ice9.digital> writes:

> If ox-md is trying to do the same thing as Markdown.pl then it doesn't
> really make sense to compare it to CommonMark.

Most likely, ox-md is following Markdown.pl simply because there was no
better standard at the time ox-md was written.

I now looked up a comparison between markdown flavours (see the attached)
and I do not see why we should abandon following the original markdown.
CommonMark and other markdown flavours usually extend things on top of
the original implementation. So, following Markdown.pl should be the
most universal option. We leave more specific exporters for advanced
markdown flavours to external packages.

> The only point am I trying to make is that both ox-md and Pandoc need to
> deal in the same unambiguous specification in order to inter-operate.
>
> For Pandoc, the matching specification needs to be selected to ensure
> that the correct one is used, but nothing based on Markdown.pl can be
> unambiguous in this scenario because Markdown.pl has no unambiguous
> specification.

Indeed.
I tried to make this point more clear in the attached patch for Org manual.

markdown_comparison.pdf
Description: Adobe PDF document

>From 17eaaa6d4cdd9964b6f7d4f96c8020a8a8eb07ec Mon Sep 17 00:00:00 2001
Message-Id: 
<17eaaa6d4cdd9964b6f7d4f96c8020a8a8eb07ec.1680692739.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Wed, 5 Apr 2023 13:04:44 +0200
Subject: [PATCH] org-manual.org: Clarify the ox-md uses the original markdown
 spec

* doc/org-manual.org (Markdown Export): Make it more clear that we are
using the original Markdown spec.  Link to Wikipedia article
describing different Markdown favours.
---
 doc/org-manual.org | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 80a259184..9736bb3b7 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -14313,10 +14313,16 @@ ** Markdown Export
 
 The Markdown export back-end, "md", converts an Org file to Markdown
 format, as defined at https://daringfireball.net/projects/markdown/.
+This is the original Markdown specification, developed by John Gruber
+and Aaron Swartz.
 
-Since it is built on top of the HTML back-end (see [[*HTML Export]]), it
-converts every Org construct not defined in Markdown syntax, such as
-tables, to HTML.
+Since "md" back-end is built on top of the HTML back-end (see [[*HTML
+Export]]), it converts every Org construct not defined in Markdown
+syntax, such as tables, to HTML.
+
+Do note that the original markdown syntax has differences with other
+commonly used Markdown flavors.  See
+https://en.wikipedia.org/wiki/Markdown for more details.
 
 *** Markdown export commands
 :PROPERTIES:
-- 
2.40.0

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>