all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Ihor Radchenko <yantar92@posteo.net>
To: Max Nikulin <manikulin@gmail.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: [BUG] ox-md image captions
Date: Wed, 05 Apr 2023 13:05:50 +0000	[thread overview]
Message-ID: <871qkyjx75.fsf@localhost> (raw)
In-Reply-To: <u0jo7t$ike$1@ciao.gmane.io>

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:
>> 
>> ![Alt text](/path/to/img.jpg)
>> 
>> ![Alt text](/path/to/img.jpg "Optional title")
>> 
>> 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>


  reply	other threads:[~2023-04-05 13:04 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
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 [this message]
2023-04-05 15:15         ` Max Nikulin
2023-04-05 15:22           ` Ihor Radchenko

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=871qkyjx75.fsf@localhost \
    --to=yantar92@posteo.net \
    --cc=emacs-orgmode@gnu.org \
    --cc=manikulin@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.