* [BUG] ox-md image captions
@ 2023-02-27 10:02 Vladimir Alexiev
2023-02-27 18:52 ` Ihor Radchenko
0 siblings, 1 reply; 20+ messages in thread
From: Vladimir Alexiev @ 2023-02-27 10:02 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1124 bytes --]
I have an image caption like this:
#+label: fig:bsdd-graphql-voyager-refact-detail
#+caption: Refactored bSDD GraphQL Schema
[[./img/bsdd-graphql-voyager-refact-Classification-ClassificationProperty.png]]
ox-md exports it like this:
(see https://git.sr.ht/~bzg/org-mode/tree/main/item/lisp/ox-md.el#L595)
However, pandoc expects image captions to be formatted like this:
(see https://pandoc.org/MANUAL.html#images).
Consequently, all my captions are lost and replaced with "img".
Maybe ox-md should emit captions in both places?
Note: I checked, ox-gfm doesn't do anything different regarding image
captuions
---
[9.5.2 (release_9.5.2-25-gaf6f12 @ c:/Emacs/share/emacs/28.1/lisp/org/)]
Emacs : GNU Emacs 28.1 (build 52, x86_64-w64-mingw32) of 2022-04-04
Package: Org mode version 9.5.2 (release_9.5.2-25-gaf6f12 @
c:/Emacs/share/emacs/28.1/lisp/org/)
[-- Attachment #2: Type: text/html, Size: 1419 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-02-27 10:02 [BUG] ox-md image captions Vladimir Alexiev
@ 2023-02-27 18:52 ` Ihor Radchenko
2023-04-04 8:48 ` Ihor Radchenko
0 siblings, 1 reply; 20+ messages in thread
From: Ihor Radchenko @ 2023-02-27 18:52 UTC (permalink / raw)
To: Vladimir Alexiev; +Cc: emacs-orgmode
Vladimir Alexiev <vladimir.alexiev@ontotext.com> writes:
> I have an image caption like this:
>
> #+label: fig:bsdd-graphql-voyager-refact-detail
> #+caption: Refactored bSDD GraphQL Schema
> [[./img/bsdd-graphql-voyager-refact-Classification-ClassificationProperty.png]]
>
> ox-md exports it like this:
>
> 
>
> (see https://git.sr.ht/~bzg/org-mode/tree/main/item/lisp/ox-md.el#L595)
>
> However, pandoc expects image captions to be formatted like this:
>
> 
The current ox-md's behaviour has been introduced in 87b48e5a2824:
ox-md: Fix image transcoding
* lisp/ox-md.el (org-md-link): Do not confuse caption and alt-text.
Provide "img" as default alt-text.
...
... format "" ...
However, looking at
https://www.markdownguide.org/basic-syntax#adding-titles
You can optionally add a title for a link. This will appear as a
tooltip when the user hovers over the link. To add a title, enclose
it in quotation marks after the URL.
So, img is not really alt text, but the opposite.
The commit appears to be inaccurate.
I am inclined to change  to
 for links without description (links with description do
not obey caption in org export).
Any objections?
--
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>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-02-27 18:52 ` Ihor Radchenko
@ 2023-04-04 8:48 ` Ihor Radchenko
2023-04-04 19:34 ` Vladimir Alexiev
` (2 more replies)
0 siblings, 3 replies; 20+ messages in thread
From: Ihor Radchenko @ 2023-04-04 8:48 UTC (permalink / raw)
To: Vladimir Alexiev; +Cc: emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> I am inclined to change  to
>  for links without description (links with description do
> not obey caption in org export).
>
> Any objections?
Upon further investigation, I have found that our base MD reference we
follow in ox-md is defining image syntax as the following:
https://daringfireball.net/projects/markdown/syntax#img
Therefore, Org mode is doing everything right within the scope of MD
specification we follow. Pandoc does not.
In fact, looking closer at https://pandoc.org/MANUAL.html#images, I find
it very strange that alt text is used as image caption, not actual
title. In HTML, alt text is supposed to be displayed *instead* of the
image if the image cannot be viewed -- a feature often used as the base
of accessibility for blind users. See
https://www.w3schools.com/TAGS/att_alt.asp
Therefore, I see no bug on Org side.
Canceled.
--
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>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-04 8:48 ` Ihor Radchenko
@ 2023-04-04 19:34 ` Vladimir Alexiev
2023-04-04 19:41 ` Ihor Radchenko
2023-04-05 9:43 ` Morgan Willcock
2023-04-05 12:06 ` Max Nikulin
2 siblings, 1 reply; 20+ messages in thread
From: Vladimir Alexiev @ 2023-04-04 19:34 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1614 bytes --]
Maybe an option?
Saying "pandoc is in the wrong" doesn't do much to resolve the issue.
Despite my enormous love for orgmode, Pandoc is used a lot more widely for
scholarly publishing and interactive websites. See Quarto and Manubot.
On Tue, Apr 4, 2023, 11:46 Ihor Radchenko <yantar92@posteo.net> wrote:
> Ihor Radchenko <yantar92@posteo.net> writes:
>
> > I am inclined to change  to
> >  for links without description (links with description do
> > not obey caption in org export).
> >
> > Any objections?
>
> Upon further investigation, I have found that our base MD reference we
> follow in ox-md is defining image syntax as the following:
>
> 
>
> 
>
> https://daringfireball.net/projects/markdown/syntax#img
>
> Therefore, Org mode is doing everything right within the scope of MD
> specification we follow. Pandoc does not.
>
> In fact, looking closer at https://pandoc.org/MANUAL.html#images, I find
> it very strange that alt text is used as image caption, not actual
> title. In HTML, alt text is supposed to be displayed *instead* of the
> image if the image cannot be viewed -- a feature often used as the base
> of accessibility for blind users. See
> https://www.w3schools.com/TAGS/att_alt.asp
>
> Therefore, I see no bug on Org side.
> Canceled.
>
> --
> 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>
>
[-- Attachment #2: Type: text/html, Size: 2798 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-04 19:34 ` Vladimir Alexiev
@ 2023-04-04 19:41 ` Ihor Radchenko
2023-04-07 14:56 ` Max Nikulin
0 siblings, 1 reply; 20+ messages in thread
From: Ihor Radchenko @ 2023-04-04 19:41 UTC (permalink / raw)
To: Vladimir Alexiev; +Cc: emacs-orgmode
Vladimir Alexiev <vladimir.alexiev@ontotext.com> writes:
> Maybe an option?
I do not mind. Patches welcome.
See https://orgmode.org/worg/org-contribute.html
> Saying "pandoc is in the wrong" doesn't do much to resolve the issue.
Sure. But I did not see changing default Org's behaviour as justified in
such scenario.
> Despite my enormous love for orgmode, Pandoc is used a lot more widely for
> scholarly publishing and interactive websites. See Quarto and Manubot.
IMHO, it would make more sense if Pandoc had a toggle to treat captions
differently. As an alternative.
Of course, it should not stop us from providing Org export option.
--
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>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-04 8:48 ` Ihor Radchenko
2023-04-04 19:34 ` Vladimir Alexiev
@ 2023-04-05 9:43 ` Morgan Willcock
2023-04-05 10:04 ` Ihor Radchenko
2023-04-05 12:06 ` Max Nikulin
2 siblings, 1 reply; 20+ messages in thread
From: Morgan Willcock @ 2023-04-05 9:43 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Vladimir Alexiev, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> Upon further investigation, I have found that our base MD reference we
> follow in ox-md is defining image syntax as the following:
>
> 
>
> 
>
> https://daringfireball.net/projects/markdown/syntax#img
>
> Therefore, Org mode is doing everything right within the scope of MD
> specification we follow. Pandoc does not.
I don't think that Markdown has a single specification.
Perhaps it is a bug that ox-md is not following a specification, and
this would be fixed by using a specification and passing its test suite:
https://commonmark.org/
However, if ox-md is intentionally trying to match the behaviour of the
original Markdown.pl, the Pandoc format that matches this is
"markdown_strict" and not "markdown".
i.e. Pandoc's "markdown" format is not the same format which is
described at daringfireball.net:
https://pandoc.org/MANUAL.html#pandocs-markdown
--
Morgan Willcock
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-05 9:43 ` Morgan Willcock
@ 2023-04-05 10:04 ` Ihor Radchenko
2023-04-05 10:41 ` Morgan Willcock
0 siblings, 1 reply; 20+ messages in thread
From: Ihor Radchenko @ 2023-04-05 10:04 UTC (permalink / raw)
To: Morgan Willcock; +Cc: Vladimir Alexiev, emacs-orgmode
Morgan Willcock <morgan@ice9.digital> writes:
>> https://daringfireball.net/projects/markdown/syntax#img
>>
>> Therefore, Org mode is doing everything right within the scope of MD
>> specification we follow. Pandoc does not.
>
> I don't think that Markdown has a single specification.
Indeed. And the one in daringfireball is what we historically follow
since >10 years ago, when ox-md has been implemented.
> Perhaps it is a bug that ox-md is not following a specification, and
> this would be fixed by using a specification and passing its test suite:
Please provide concrete examples where ox-md does not follow
specification.
The title/caption issue herein does not qualify.
https://spec.commonmark.org/0.30/#images also defines
 with "title" being the title, as we currently use
it in ox-md when exporting captions.
> https://commonmark.org/
I agree that using CommonMark.org as the source of truth will make more
sense, given that the original daringfireball.net is not precise.
It would be helpful if someone examines whether ox-md is consistent with
CommonMark.
> However, if ox-md is intentionally trying to match the behaviour of the
> original Markdown.pl, the Pandoc format that matches this is
> "markdown_strict" and not "markdown".
>
> i.e. Pandoc's "markdown" format is not the same format which is
> described at daringfireball.net:
>
> https://pandoc.org/MANUAL.html#pandocs-markdown
Indeed. ox-md is certainly not aiming to export to Pandoc's markdown
flavour.
--
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>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-05 10:04 ` Ihor Radchenko
@ 2023-04-05 10:41 ` Morgan Willcock
2023-04-05 11:07 ` Ihor Radchenko
0 siblings, 1 reply; 20+ messages in thread
From: Morgan Willcock @ 2023-04-05 10:41 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Vladimir Alexiev, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> Please provide concrete examples where ox-md does not follow
> specification.
>
> The title/caption issue herein does not qualify.
> https://spec.commonmark.org/0.30/#images also defines
>  with "title" being the title, as we currently use
> it in ox-md when exporting captions.
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.
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.
--
Morgan Willcock
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-05 10:41 ` Morgan Willcock
@ 2023-04-05 11:07 ` Ihor Radchenko
2023-04-05 15:30 ` Vladimir Alexiev
2023-04-16 15:36 ` Ihor Radchenko
0 siblings, 2 replies; 20+ messages in thread
From: Ihor Radchenko @ 2023-04-05 11:07 UTC (permalink / raw)
To: Morgan Willcock; +Cc: Vladimir Alexiev, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1152 bytes --]
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.
[-- Attachment #2: markdown_comparison.pdf --]
[-- Type: application/pdf, Size: 95705 bytes --]
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0001-org-manual.org-Clarify-the-ox-md-uses-the-original-m.patch --]
[-- Type: text/x-patch, Size: 1566 bytes --]
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
[-- Attachment #4: Type: text/plain, Size: 224 bytes --]
--
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>
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-04 8:48 ` Ihor Radchenko
2023-04-04 19:34 ` Vladimir Alexiev
2023-04-05 9:43 ` Morgan Willcock
@ 2023-04-05 12:06 ` Max Nikulin
2023-04-05 13:05 ` Ihor Radchenko
2 siblings, 1 reply; 20+ messages in thread
From: Max Nikulin @ 2023-04-05 12:06 UTC (permalink / raw)
To: emacs-orgmode
On 04/04/2023 15:48, Ihor Radchenko wrote:
> Ihor Radchenko writes:
>
>> I am inclined to change  to
>>  for links without description (links with description do
>> not obey caption in org export).
>
> Upon further investigation, I have found that our base MD reference we
> follow in ox-md is defining image syntax as the following:
>
> 
>
> 
>
> https://daringfireball.net/projects/markdown/syntax#img
>
> Therefore, Org mode is doing everything right within the scope of MD
> specification we follow. Pandoc does not.
My reading of
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#the_title_attribute
is that caption should not be exported as title. Alt text is more
"visible" than title, but perhaps caption should be exported as text
adjacent to image.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-05 12:06 ` Max Nikulin
@ 2023-04-05 13:05 ` Ihor Radchenko
2023-04-05 15:15 ` Max Nikulin
0 siblings, 1 reply; 20+ messages in thread
From: Ihor Radchenko @ 2023-04-05 13:05 UTC (permalink / raw)
To: Max Nikulin; +Cc: emacs-orgmode
Max Nikulin <manikulin@gmail.com> writes:
>> Upon further investigation, I have found that our base MD reference we
>> follow in ox-md is defining image syntax as the following:
>>
>> 
>>
>> 
>>
>> https://daringfireball.net/projects/markdown/syntax#img
>>
>> Therefore, Org mode is doing everything right within the scope of MD
>> specification we follow. Pandoc does not.
>
> My reading of
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#the_title_attribute
> is that caption should not be exported as title. Alt text is more
> "visible" than title, but perhaps caption should be exported as text
> adjacent to image.
I will provide the linked text at the end of the message for future
reference.
For HTML, I agree that caption should ideally be exported as text adjacent
to image. That's what we actually do in `org-html--wrap-image'.
However, we are talking about MD export.
MD has nothing to do with how Pandoc's "implicit_figures" extension
modifies MD->HTML export. The original MD spec only talks about image
description and image title being exported to "alt" and "title" HTML
attributes.
Currently, Org's image link description will be exported to MD's image
link description and Org's image caption will be exported to MD's image
title. Doing otherwise by default is not entirely consistent.
Of course, the current default will also ignore #+caption altogether
unless the image link has no description. So, we may, in theory, play
around with the default.
On the other hand, by keeping the current default we also keep the
option to combine description and caption if we ever consider altering
our inline image rules during export (`org-export-inline-image-p').
I am still inclined towards keeping the current default, as not every
possible MD export user is doing it to consequently convert the MD to
HTML using Pandoc also having the "implicit_figures" Pandoc's extension
enabled.
We may provide a toggle for this, however. If someone is bothered enough
and sends a patch. Maybe #+ATTR_MD: also option.
----
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#the_title_attribute
The title attribute is not an acceptable substitute for the alt
attribute. Additionally, avoid duplicating the alt attribute's value
in a title attribute declared on the same image. Doing so may cause
some screen readers to announce the description twice, creating a
confusing experience.
The title attribute should also not be used as supplemental
captioning information to accompany an image's alt description. If
an image needs a caption, use the figure and figcaption elements.
The value of the title attribute is usually presented to the user as
a tooltip, which appears shortly after the cursor stops moving over
the image. While this can provide additional information to the
user, you should not assume that the user will ever see it: the user
may only have keyboard or touchscreen. If you have information
that's particularly important or valuable for the user, present it
inline using one of the methods mentioned above instead of using
title.
--
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>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-05 13:05 ` Ihor Radchenko
@ 2023-04-05 15:15 ` Max Nikulin
2023-04-05 15:22 ` Ihor Radchenko
0 siblings, 1 reply; 20+ messages in thread
From: Max Nikulin @ 2023-04-05 15:15 UTC (permalink / raw)
To: emacs-orgmode
On 05/04/2023 20:05, Ihor Radchenko wrote:
> MD has nothing to do with how Pandoc's "implicit_figures" extension
> modifies MD->HTML export. The original MD spec only talks about image
> description and image title being exported to "alt" and "title" HTML
> attributes.
My expectation is that Markdown
is exported to HTML
<img src="/path/to/img.jpg" alt="Alt text" title="Optional title">
If it is so then caption should not be exported as title and it is not
related to markdown extensions. Org caption should appear as text, it
should not require to hover image to see it as tooltip.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-05 15:15 ` Max Nikulin
@ 2023-04-05 15:22 ` Ihor Radchenko
0 siblings, 0 replies; 20+ messages in thread
From: Ihor Radchenko @ 2023-04-05 15:22 UTC (permalink / raw)
To: Max Nikulin; +Cc: emacs-orgmode
Max Nikulin <manikulin@gmail.com> writes:
> My expectation is that Markdown
>
> 
>
> is exported to HTML
>
> <img src="/path/to/img.jpg" alt="Alt text" title="Optional title">
>
> If it is so then caption should not be exported as title and it is not
> related to markdown extensions. Org caption should appear as text, it
> should not require to hover image to see it as tooltip.
That will certainly be a breaking change to export #+caption and
ordinary text in markdown.
I do not feel that it is justified.
--
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>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-05 11:07 ` Ihor Radchenko
@ 2023-04-05 15:30 ` Vladimir Alexiev
2023-04-16 15:36 ` Ihor Radchenko
1 sibling, 0 replies; 20+ messages in thread
From: Vladimir Alexiev @ 2023-04-05 15:30 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Morgan Willcock, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1622 bytes --]
I posted a Pandoc request: https://github.com/jgm/pandoc/issues/8752
On Wed, Apr 5, 2023 at 2:04 PM Ihor Radchenko <yantar92@posteo.net> wrote:
> 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.
>
>
> --
> 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>
>
[-- Attachment #2: Type: text/html, Size: 2303 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-04 19:41 ` Ihor Radchenko
@ 2023-04-07 14:56 ` Max Nikulin
2023-04-07 15:29 ` Vladimir Alexiev
0 siblings, 1 reply; 20+ messages in thread
From: Max Nikulin @ 2023-04-07 14:56 UTC (permalink / raw)
To: Vladimir Alexiev; +Cc: emacs-orgmode
On 05/04/2023 02:41, Ihor Radchenko wrote:
> IMHO, it would make more sense if Pandoc had a toggle to treat captions
> differently. As an alternative.
printf '\n' |
pandoc -f org -t markdown_strict
disables generation of <figcaption>.
I think, it is unlikely that users with mobile devices (touchscreen
only) have chance to notice title attribute. The only site where I check
image titles is https://xkcd.com/1179/ . Alt text describes image for
those who do not see image while caption should be apparent for those
who see it.
I believe that it is Org bug that it places caption as title, but there
is no better alternatives besides HTML. Duplicating caption as alt text,
as pandoc does, is a bug as well.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-07 14:56 ` Max Nikulin
@ 2023-04-07 15:29 ` Vladimir Alexiev
2023-04-07 17:21 ` Max Nikulin
2023-04-08 10:25 ` Ihor Radchenko
0 siblings, 2 replies; 20+ messages in thread
From: Vladimir Alexiev @ 2023-04-07 15:29 UTC (permalink / raw)
To: Vladimir Alexiev, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 104 bytes --]
Hi Max!
It's not about the tooltip in HTML:
figure captions are very important in scholarly publishing.
[-- Attachment #2: Type: text/html, Size: 207 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-07 15:29 ` Vladimir Alexiev
@ 2023-04-07 17:21 ` Max Nikulin
2023-04-08 10:29 ` Ihor Radchenko
2023-04-08 10:25 ` Ihor Radchenko
1 sibling, 1 reply; 20+ messages in thread
From: Max Nikulin @ 2023-04-07 17:21 UTC (permalink / raw)
To: Vladimir Alexiev, emacs-orgmode
On 07/04/2023 22:29, Vladimir Alexiev wrote:
> It's not about the tooltip in HTML:
> figure captions are very important in scholarly publishing.
I see and I do not like that Org exports caption as title (tooltip). On
the other hand neither original markdown nor GitHub flavored markdown
have notion of figure caption. Pandoc extension has the issue with
duplicated text in caption and alt. I have seen mention of <figcaption>
block in commonmark, but I have never tried it.
MarkDown is rather basic format and the closest approach it a paragraph
below an image despite they are not grouped into figure.
Figure 1. Caption
A workaround for Org is export snippet or block for the paragraph with
caption
#+md: Figure 1. Caption
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-07 15:29 ` Vladimir Alexiev
2023-04-07 17:21 ` Max Nikulin
@ 2023-04-08 10:25 ` Ihor Radchenko
1 sibling, 0 replies; 20+ messages in thread
From: Ihor Radchenko @ 2023-04-08 10:25 UTC (permalink / raw)
To: Vladimir Alexiev; +Cc: emacs-orgmode
Vladimir Alexiev <vladimir.alexiev@ontotext.com> writes:
> It's not about the tooltip in HTML:
> figure captions are very important in scholarly publishing.
I agree, but are you actually publishing scholar articles to MD? Caption
are correctly handled in Latex and ODT publishing - the most common
formats for scholary articles.
The problem with MD is that it does not have notion of captions and
hence we have to make up some kind of ad-hoc convention, which may or
may not work with specific article format you need to produce.
--
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>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-07 17:21 ` Max Nikulin
@ 2023-04-08 10:29 ` Ihor Radchenko
0 siblings, 0 replies; 20+ messages in thread
From: Ihor Radchenko @ 2023-04-08 10:29 UTC (permalink / raw)
To: Max Nikulin; +Cc: Vladimir Alexiev, emacs-orgmode
Max Nikulin <manikulin@gmail.com> writes:
> On 07/04/2023 22:29, Vladimir Alexiev wrote:
>> It's not about the tooltip in HTML:
>> figure captions are very important in scholarly publishing.
>
> I see and I do not like that Org exports caption as title (tooltip). On
> the other hand neither original markdown nor GitHub flavored markdown
> have notion of figure caption. Pandoc extension has the issue with
> duplicated text in caption and alt. I have seen mention of <figcaption>
> block in commonmark, but I have never tried it.
>
> MarkDown is rather basic format and the closest approach it a paragraph
> below an image despite they are not grouped into figure.
>
> 
>
> Figure 1. Caption
In theory, we can directly use <figcaption> HTML tags + direct HTML in
the MD export. That will be actually the closest way. But direct HTML is
not well-received when using the MD in practice. For example, sourcehut,
GitHub, and Reddit do not allow arbitrary html fragments when rendering
MD (AFAIK).
> A workaround for Org is export snippet or block for the paragraph with
> caption
>
> #+md: Figure 1. Caption
A better workaround is a custom filter, or we may provide a
customization, if someone offers a patch.
--
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>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [BUG] ox-md image captions
2023-04-05 11:07 ` Ihor Radchenko
2023-04-05 15:30 ` Vladimir Alexiev
@ 2023-04-16 15:36 ` Ihor Radchenko
1 sibling, 0 replies; 20+ messages in thread
From: Ihor Radchenko @ 2023-04-16 15:36 UTC (permalink / raw)
To: Morgan Willcock; +Cc: Vladimir Alexiev, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> Indeed.
> I tried to make this point more clear in the attached patch for Org manual.
Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=62996300e
--
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>
^ permalink raw reply [flat|nested] 20+ messages in thread
end of thread, other threads:[~2023-04-16 18:12 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-02-27 10:02 [BUG] ox-md image captions Vladimir Alexiev
2023-02-27 18:52 ` Ihor Radchenko
2023-04-04 8:48 ` Ihor Radchenko
2023-04-04 19:34 ` Vladimir Alexiev
2023-04-04 19:41 ` Ihor Radchenko
2023-04-07 14:56 ` Max Nikulin
2023-04-07 15:29 ` Vladimir Alexiev
2023-04-07 17:21 ` Max Nikulin
2023-04-08 10:29 ` Ihor Radchenko
2023-04-08 10:25 ` Ihor Radchenko
2023-04-05 9:43 ` Morgan Willcock
2023-04-05 10:04 ` Ihor Radchenko
2023-04-05 10:41 ` Morgan Willcock
2023-04-05 11:07 ` Ihor Radchenko
2023-04-05 15:30 ` Vladimir Alexiev
2023-04-16 15:36 ` Ihor Radchenko
2023-04-05 12:06 ` Max Nikulin
2023-04-05 13:05 ` Ihor Radchenko
2023-04-05 15:15 ` Max Nikulin
2023-04-05 15:22 ` Ihor Radchenko
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).