Make WordPress Core

Opened 15 years ago

Closed 14 years ago

#8256 closed enhancement (fixed)

Caption and alternative text should not be the same

Reported by: frankie-roberto's profile frankie-roberto Owned by:
Milestone: 2.9 Priority: normal
Severity: normal Version: 2.8
Component: Gallery Keywords: has-patch tested
Focuses: Cc:


The caption field currently doubles up as alternative text ('alt text'). This break accessibility guidelines, and the draft HTML5 specification (see

See also discussion at

Attachments (2)

media_img_caption_shortcode_no_alt.diff (1.3 KB) - added by Sam_a 14 years ago.
Caption shortcode prints image alternative text only if distinct from caption, allowing override via 'wp_img_caption_print_duplicate_alt' filter
insert-img-toggle-caption.png (27.4 KB) - added by Sam_a 14 years ago.
Example of Insert Image dialog UI allowing author to toggle caption display (unrelated to patch!)

Download all attachments as: .zip

Change History (20)

#1 @azaozz
15 years ago

Or rather the image alt attribute uses the caption text for initial value, as most people would set caption but not alt. The "alt text" is editable from the Edit Image popup or in the HTML editor.

The alternative would be to set it to the image's file name (IMHO quite useless) or to leave it empty.

Don't see how setting alt and a caption under the image would break accessibility guidelines or the HTML5 draft.

#2 @frankie-roberto
15 years ago

Interesting, I didn't even realise that there was an edit image popup that was different from the add image/image gallery popup.

My suggestion would be to add an extra field to the add image popup labelled something like 'alternative text (used when image not present)' which is then saved to the database. Alternatively, it'd be better to leave it empty, and then let people edit it in the HTML/image edit popup.

The reason that using the caption as the initial value for the alt text is that captions are displayed beneath the image, wheres the alt text is meant to be a replacement for the image (when images are turned off or unavailable). Having the caption be the same as the alt text means that screenreaders would read out the same text twice!

The relevant bits from the HTML5 draft (which really just describes more explicitly how alt text is meant to work in HTML4) are:

"In many cases, the image is actually just supplementary, and its presence merely reinforces the surrounding text. In these cases, the alt attribute must be present but its value must be the empty string. In general, an image falls into this category if removing the image doesn't make the page any less useful, but including the image makes it a lot easier for users of visual browsers to understand the concept."

"In these cases, it would be wrong to include alternative text that consists of just a caption. If a caption is to be included, then either the title attribute can be used, or the figure and legend elements can be used. In the latter case, the image would in fact be a phrase or paragraph with an alternative graphical representation, and would thus require alternative text."

"In general, if an image is decorative but isn't especially page-specific, for example an image that forms part of a site-wide design scheme, the image should be specified in the site's CSS, not in the markup of the document.

However, a decorative image that isn't discussed by the surrounding text still has some relevance can be included in a page using the img element. Such images are decorative, but still form part of the content. In these cases, the alt attribute must be present but its value must be the empty string.

Examples where the image is purely decorative despite being relevant would include things like a photo of the Black Rock City landscape in a blog post about an event at Burning Man, or an image of a painting inspired by a poem, on a page reciting that poem." is also relevant.

#3 @Sam_a
14 years ago

The HTML5 spec says that, for images that are a "graphical representation of some of the surrounding text", the alternative text should be empty (rather than duplicating the surrounding text); and that for images where alternative text is required, the text should be a descriptive substitute/replacement for the image and "should never contain text that could be considered the image's caption, title, or legend" (which should be included elsewhere in the markup).

So maybe we should change it such that in the case where the WP "insert image" dialog inserts an image and printed caption together, the alt text should be empty (rather than duplicating the caption).

Until then, you can always write your own alt text and captions in either the HTML or visual editors.

#4 @frankie-roberto
14 years ago

Hi, I agree that leaving the alt empty would be a better default when inserting an image with a caption from the dialog. An alternative would be to add an alt text field to the dialog, but it'd take some explaining and I'm not sure how many people would fill it in.

Whilst people can currently fill in their own alt text in the HTML/visual editor, a lot of people won't understand the important of good alt text, and so it'd be better to have a less harmful default (to avoid screen readers reading out the same text twice).

#5 @Denis-de-Bernardy
14 years ago

  • Milestone 2.8 deleted
  • Resolution set to wontfix
  • Status changed from new to closed

"for images that are a "graphical representation of some of the surrounding text", the alternative text should be empty (rather than duplicating the surrounding text)"

#6 @janeforshort
14 years ago

  • Resolution wontfix deleted
  • Status changed from closed to reopened
  • Type changed from defect (bug) to enhancement
  • Version set to 2.8

Reopening this ticket because it's an issue that I hear about fairly regularly. For accessibility purposes, the alt text should be filled in. Yes, some people don't bother. But it shouldn't be linked to the caption, because many people want to include alt text but not a caption. Having to go into edit the image after initial upload is a terrible user experience, and many people don't even realize they can click the image in the visual editor to get the edit link. We may wind up pushing this until 2.9 if no one patches it, and we'll include it as part of the media overhaul, but the ticket should stay open.

#7 @Denis-de-Bernardy
14 years ago

I disagree. The caption and the alt text serve the very same purpose: To describe the image. The ticket should remain closed as a result.

I hear about this too on my end, but those who enquire about it have one point in common: They invariably have little clue of what they're doing, and are seeking to add alt text because they read, on some random SEO forum, that it would benefit their site.

The fact is, that's wrong. It won't. Worse, if they enter the same text in there, it's a repeated statement. Much like keyword keyword keyword would get discounted in Altavista, the same alt and caption won't do them much good in Google. And it'll make the page feel awkward to a blind user.

It won't even help them in Google Images, since the surrounding text is also considered...

Letting you close the ticket.

#8 @janeforshort
14 years ago

  • Milestone set to 2.8

#9 @janeforshort
14 years ago

  • Milestone changed from 2.8 to 2.9

I still disagree with Denis-de-Bernardy. Caption and alt both describe, but they do not serve same function. Alt is for accessibility and caption has a display style attached to it (theme dependent). Many people want to include an alt tag for accessibility purposes without putting a visual caption on their images.

However, I'm punting due to time constraints.

#10 @aaroncampbell
14 years ago

  • Cc aaroncampbell added

#11 @aaroncampbell
14 years ago

Just to quickly add my two cents, I've done some work for companies that need to meet rather strict accessibility guidelines. For example, National Center for Technology Innovation is partially government funded via education grants. They absolutely *must* have alt text for every image.

We really need to allow users this functionality. I'll try to post more specific thoughts on it later, but there's definitely a need out there.

#12 @Denis-de-Bernardy
14 years ago

I still fail to see the point in add a non-empty alt text for images that are merely redundant with a nearby field that actually gets displayed. :-|

It's like... for an image with no caption, fine. But for an image with a caption given by the user, it feels grossly unneeded. Or then, a mere ("Image").

#13 @aaroncampbell
14 years ago

Here's an example that will hopefully explain how they're different. It's based off an old blonde joke (not sure why this was the first example that popped into my head). Say I had a picture of a monitor with lines of Wite-out all over the screen. I might put the capture "Blonde hard at work" or "Blondes and technology" but that's not enough if the person can't see the picture. I'd probably put Alt text like "Computer monitor with Wite-out on the screen" or the more generic "Monitor covered in correction fluid"

They each have their place, one describes the image (for those that can't see it) and one *could* describe the image, but may just as easily describe thoughts about the image, ask questions about the image ("What was he thinking?"), offer commentary on the image, crack jokes about the image, etc.

I know it was a strange example, but I'm sure I could look at a few sites and come up with more if it would be helpful. I think the real question is "What's the best way to solve this while keeping as much backward compatibility as possible?"

#14 @aaroncampbell
14 years ago

Sorry to reply to myself here, but after adding my two cents I went to look at my wife's blog. She's not tech savvy, just an average user, so I look at her use patterns a lot to try to understand how "most people" might use things. She has a post about our trip to WordCamp SF called Knights Who Eat Spam Alot that has six images in a gallery at the end. Some work as you expected, the caption describes the image. In this case one says This One's For You Dad - The Street From "Bullet" another says Us North of The City and another (though this one's on the fence a little) says A Not So Golden Bridge. However, for the other three the caption does NOT describe the image, and the image is absolutely needed to understand what she's talking about. For these it would be important to have alt text:
One says Geek art and it's a smooth sphere with very detailed scenery carved out of it, one says Has Anyone Seen My Safety Pin? and is a picture of a 20 foot tall safety pin sculpture, and one says Hard At Work In SD and shows a worker at the San Diego airport completely asleep in his cart on the runway.

For more examples, look back through some of the posts on her blog...she uses a lot of pictures.

#15 @bobeaston
14 years ago

  • Cc bob@… added

14 years ago

Caption shortcode prints image alternative text only if distinct from caption, allowing override via 'wp_img_caption_print_duplicate_alt' filter

#16 @Sam_a
14 years ago

  • Keywords has-patch tested added

Patch (tested successfully in trunk) changes caption shortcode's output:

  • If image's alternative text is identical to caption text, alt text is removed (as alt=""), but you can force keeping it instead by passing TRUE via 'wp_img_caption_print_duplicate_alt' filter
  • If the image's alt text is disinct from caption text, it's left as is.

I think this behavior is more consistent with the HTML 5 guidelines.

I still hope the alt/caption difficulties can be worked out somehow in the 2.9 media UI redesign. I reported some of the same issues as Jane in another ticket (#8888): the Insert Image Attachment dialog inserts either a caption and duplicate alt text or no caption and no alt text.

#17 @bobeaston
14 years ago

You beat me to the job of resolving this issue. I've just been looking at media.php.

Yes, your fix is more consistent with HTML 5, but it is also very valid for HTML 4 and for /WCAG 2. It is perfectly valid for alt="" when the image is not essential to understanding, such as a decorative or "eye candy" images, spacer gifs, etc. The entire difficulty with trying to make a choice automatically is that no machine understands how to answer "Is the image essential?"

Your code is almost OK, but does not fix the current problem. In fact, in one circumstance it can produce an undesirable outcome.

Your code depends on alt text already existing. Where does that alt text come from? There's no entry field for alt in the upload form. The only place a person can currently add legitimate alt text is on the very obscure "Advanced Settings" form of the edit image code.

Currently media.php offers entry fields only for title and caption on the upload form. media.php then populates $alt with the return from the caption entry field, and then copies that value into the caption shortcode. So, you see, alt is virtually guaranteed to be identical to caption. If someone had consciously crafted the caption to be useful alt text, your change makes it null, the unwanted outcome.

As an accessibility consultant (my professional job for many years), I would resolve the problem in the upload form, the first thing the typical user sees. There, I would:

  1. Add a radio button with yes/no values and the question "Is the image essential to understanding?"
  1. Offer an input field for alternative text with help that says "Describes the image when it can’t be seen." I would also add a -more- link to the help text pointing to /an excellent codex page.
  1. Mark the alternative text entry field with an asterisk, denoting required, and add the aria required attributes.
  1. Populate $alt with either provided text or with null dependent on how the "essential" question was answered.
  1. Remove the required asterisk from the title entry field and change its help text to "Additional information. Appears as hover / tooltip text."
  1. Change the help text for the caption field to "Yet more information – i.e. photo credit."
  1. Assign the value entered for caption to the caption shortcode instead of assigning it to $alt first.

14 years ago

Example of Insert Image dialog UI allowing author to toggle caption display (unrelated to patch!)

#18 @ryan
14 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed
Note: See TracTickets for help on using tickets.