It would be great if Pandoc put alt text from images into Word's "Alt Text" Description panel. This would allow authors create accessible documents because the alt text can be used by people reliant on assistive technology (for example, a screen reader) to understand the image. This should happen for inline images and also images placed on their own lines. A markdown example would be:

![a pony running through a meadow](images/pony.png)

The text "a pony running through a meadow" would be placed into the Description panel of Word's Alt Text panel. WebAIM has an article on this here: http://webaim.org/techniques/word/ Although the screen shots are old, I've just checked the claims about using the Description panel rather than the Title one and they're still correct. Manually adding alt text to images in Word documents is painful, so this feature, if possible to implement, would be very welcome.

For some reason, the docx writer currently uses the title text instead of the alt text. Not sure whether this is intended behaviour or not. Meanwhile, you can use the title text, as in:

![alt text](foo.jpg "title text")

I have a similar problem, described on StackOverflow: How to set an image's alt-text with pandoc for docx conversion

The thing is, that the title-attribute (from an accessibility view) always is redundant information, as no general pattern has emerged during the many years of its existence on how to use it. For example, some screenreaders announce it automatically, some don't, and some browsers display it on hover, some don't, and keyboard-only users will never see it.

From an accessibility point of view, thus, the title-attribute should completely be rejected, and all relevant information must be somewhere else (e.g. the alt-attribute). This means that setting the title-attribute so the Docx-Writer can use it results in redundant information in other writers (e.g. HTML), which is unwanted for screenreader-users (who have to bear and filter a lot of information on one sequential auditive channel already anyway).

So IMHO the title-attribute should be neglected completely by Pandoc.

Here are many blog posts about the title topic, e.g.:

• HTML5 Accessibility Chops: title attribute use and abuse
• I thought title text improved accessibility. I was wrong.

The title attribute shouldn't be completely rejected because it does have limited use. The Paciello Group's Using the HTML title attribute – updated shows these use cases. Additionally, WCAG 2.0's Using the title attribute of the frame and iframe elements document explicitly states that the title attribute should be used to give accessible names to iframes. I put an HTML page together yesterday to test screen reader support for the title attribute on iframes and it works well.

@lierdakil @jkr do you know why the docx writer currently uses the title text instead of the alt text? is there any undocumented reason for that or just an oversight?