* [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 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 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-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-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-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-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
* 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
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).