The "Title" matches the alt attribute for images in HTML.
The "Description" would match the "long description" for images in HTML and there are various ways of doing this in HTML. The Web Accessibility Initiative's tutorial on complex images describes a few ways of doing this: https://www.w3.org/WAI/tutorials/images/complex/ .
A technique not described in the above tutorial is using the details and summary elements inside the figcaption element below the image (img and figcaption being both wrapped in the figure element), so the long description is available through a disclosure widgets. This works both for screen reader users and other keyboard users. (An example in German can be found at https://digitalisierung.hdm-stuttgart.de/barrierefreiheit/gesetze-und-richtlinien/ .)

(Note also that "Description" should only be filled in for images that are too complex to be described using only an alt attribute. The alt attribute is always read; the long description is presented through a mechanism that a screenreader user can chose to ignore or skip. In many cases, this is a link.)

So we need to figure out what sort of HTML output we want to generate, since there are several options.

Once the "expected" LO behavior is clarified, then I will update the help page for the Description control in the Description dialog [1].  The entry for that control will also be included in the help page for the Options tab [2]. 

The existing text in [1] appears to have been written in 2003 and never updated. Perhaps corrections, clarifications, additions are needed. Will add NeedsUXEval.


[1] https://help.libreoffice.org/7.4/en-US/text/shared/01/05190100.html
[2] https://help.libreoffice.org/7.4/en-US/text/swriter/01/05060900.html

My take: LibreOffice is not an HTML editor and we do the required minimum. Wouldn't invest effort for the description. => NAB

@Heiko If LibreOffice is not an HTML editor, the proper response is to remove its HTML editing capabilities, not to declare this issue "not a bug". An accessible authoring tool is required to preserve accessibility features when exporting to or saving in other formats where corresponding features are available.

Each accessibility issue we ignore will increase the irrelevance of LibreOffice on the European market in 2025, when the European Accessibility Act comes into force. After 2025, LibreOffice will either (mostly) meet standard EN 301 549 or be replaced by a different product (most likely Microsoft Office) in both public administrations and companies in the European Union.

So I misinterpreted your "the long description is available through a disclosure widgets" with my reply "we do the required minimum"?

Ultimately not a topic for UX since exporting the description is done in the background. My comment was just about balancing effort vs. need with the idea that HTML is not a native format for text processors.

(In reply to Heiko Tietze from comment #5)
> Ultimately not a topic for UX since exporting the description is done in 
> the background. 
But the penultimate topic is for UX  - namely, what should users be expecting from the "Text Alternative" and "Description" fields?  (and Christophes interesting comment 4 makes these questions particularly salient).

As a first step toward clarifying those expectations, please help me evaluate/revise the existing descriptions of these controls in the Description dialog (Format > Description). 

help.libreoffice.org/7.4/en-US/text/shared/01/05190100.html

NB. I am not asking for an "ideal design" -- just a reasonable, pragmatic proposal for the current functionality. The immediate problem is that the scope or function of "Text Alternative" and "Description" are unclear. 

For example:
1. Is Text Alternative and Description only relevant in relation to export (HTML, PDF)?  Or does it have (or is supposed to have) other purposes?

2. At present, for PDF export, only Images will export Text Alternative and Description.  Perhaps the help should say that?  Or should help say what is the expected behavior, and then have a caveat like "At present, this only works for Images"?  (this is a UX question)

3. As noted in this ticket, Description is not exported to HTML.  So the current help is highly misleading (just plain false, afaict, and somewhat irresponsible). But what can be said about the use/function of Description? (another UX question)

I accept the possibility that no one knows the answers to these questions -- which is why it seems appropriate to have a genuine UX evaluation, so that those responsible for the backend have a "target" (design specifications) to work towards. 

Again -- for now -- I am only seeking a reasonable first step in relation to the existing functionality -- primarily so that a few sentences in the help page can be revised -- and trust that this first small step will generate additional steps (bug reports).

(In reply to Christophe Strobbe from comment #4)
> An accessible authoring tool is required to preserve accessibility features
> when exporting to or saving in other formats where corresponding features
> are available.

I agree. Adding this ticket to the a11y meta bug.

(In reply to Christophe Strobbe from comment #1)
> The "Title" matches the alt attribute for images in HTML.
> The "Description" would match the "long description" for images in HTML and
> there are various ways of doing this in HTML. The Web Accessibility
> Initiative's tutorial on complex images describes a few ways of doing this:
> https://www.w3.org/WAI/tutorials/images/complex/ .

Thanks, that's very informative.
What about just setting the description in the "longdesc" attribute using a "data:" URI, like this example from https://www.w3schools.com/tags/att_img_longdesc.asp ?

> <!-- The description is included in a data:URI -->
> <img src="w3html.gif" alt="W3Schools.com" width="100" height="132" longdesc="data:text/html;charset=utf-8;,%3C!DOCTYPE%20html%3E%3Chtml%3E%3Chead%3E%3Ctitle%3EDescription%20of%20the%20Logo%3C/title%3E%3C/head%3E%3Cbody%3E%3Cp%3ESome%20description%20goes%20here%3C/body%3E%3C/html%3E">

Not having much experience with either HTML or a11y, that looks to me like it might be a rather straightforward way. 

> A technique not described in the above tutorial is using the details and
> summary elements inside the figcaption element below the image (img and
> figcaption being both wrapped in the figure element), so the long
> description is available through a disclosure widgets. This works both for
> screen reader users and other keyboard users. (An example in German can be
> found at
> https://digitalisierung.hdm-stuttgart.de/barrierefreiheit/gesetze-und-
> richtlinien/ .)

LO provides the possibility to insert a caption to the image (right click -> "Insert Caption"), which seems to be what "figcaption" is for semantically in the first place (at a quick glance, but I'm not very experienced with either HTML or a11y) so I'm wondering whether using "figcaption" for something else wouldn't somehow "conflict" with that concept?

> (Note also that "Description" should only be filled in for images that are
> too complex to be described using only an alt attribute. The alt attribute
> is always read; the long description is presented through a mechanism that a
> screenreader user can chose to ignore or skip. In many cases, this is a
> link.)

Do I understand correctly that this is something that the user decides, so should be mentioned in the documentation?

Interestingly, Word (or its ODT import functionality) doesn't seem to use the concept of separate fields for title and description. When opening the sample file in Word, right-clicking the image and selection "Edit alt text", an "Alt Text" box shows up that has the content of both fields merged together:

> This is the text alternative
> 
> This is the description // where does this appear?

and it is exported to HTML like this:

> <img width=166 height=314
> src="Description%20Test%20file_files/image002.gif" align=left hspace=12
> alt="Title: This is the text alternative - Description: This is the description > // where does this appear?"
> v:shapes="Image1">

(In reply to sdc.blanco from comment #6)
> For example:
> 1. Is Text Alternative and Description only relevant in relation to export
> (HTML, PDF)?  Or does it have (or is supposed to have) other purposes?

I think that it can also be helpful when using LO itself get a text description, just the same as it can be used with HTML or PDF.

> 2. At present, for PDF export, only Images will export Text Alternative and
> Description.  Perhaps the help should say that?  Or should help say what is
> the expected behavior, and then have a caveat like "At present, this only
> works for Images"?  (this is a UX question)

I tend towards the second option, once it's clear what the expected behavior is. (I think something like "At present, this is only exported for Images, there's bug 149013 for other formats" or somesuch might be helpful to keep track of this?)

> 3. As noted in this ticket, Description is not exported to HTML.  So the
> current help is highly misleading (just plain false, afaict, and somewhat
> irresponsible). But what can be said about the use/function of Description?
> (another UX question)

Depending on where the discussion goes, I think Christophe's comment 1 could be an answer here:

(In reply to Christophe Strobbe from comment #1)
> (Note also that "Description" should only be filled in for images that are
> too complex to be described using only an alt attribute. The alt attribute
> is always read; the long description is presented through a mechanism that a
> screenreader user can chose to ignore or skip. In many cases, this is a
> link.)

-> "description" is supposed to be used for a more detailed description of the image if a "short summary" in the "Text Alternative" field doesn't cover all relevant information?

(In reply to Michael Weghorn from comment #8)
> I think that it can also be helpful when using LO itself get a text
> description, just the same as it can be used with HTML or PDF.
+1

I have seen in BZ (but could not find it again) that one person mentioned using the Description field for documentation in a corporate setting (maybe in/with templates).

iiuc, you imagine that hovering the mouse over an object would show the "Alternative Text" and/or "Description"?  (sounds good!)
How would you display the data if both fields are used?

And maybe an option in Tools > Options > View to toggle which ones are shown?  (It looks like there is just enough room next to Mouse to put the controls.)


> > Should help say what is the expected behavior, and then have a caveat...
> I tend towards the second option, once it's clear what the expected 
> behavior is. 
Me too. So thanks for helping to moving the thinking forward toward a first resolution of "expected behavior".

> > But what can be said about the use/function of Description?
No strong opinions here -- happy to follow the sensible ideas already being proposed/developed here by Christophe and Michael.

But one question in relation to the help page for the "Description" control.  Here is the current text:

   Enter a description text. The long description text can be entered to
   describe a complex object or group of objects to users with screen reader
   software. The description is visible as an alternative tag for 
   accessibility tools.

Notice the mention about screen reader software and accessibility tools. Two questions.

1.  Should the help page mention these topics at all?  (I am assuming "yes").

2.  But if yes, then presumably there are some standards (e.g., alt tag) that are used to support screen readers and other tools.  But I get the impression (from the links that Christophe has sent) that "description" is not so standardized.  So maybe it is necessary to simply explain clearly what gets exported to PDF and HTML (are there other exports?) -- without making these generic/vague claims about screen reader software, etc.  Maybe something like:

   Whether the Description tag is used by other software depends on the 
   software's implementation.   

Not trying to promote a particular formulation here -- rather my concern is that the description of Description should give adequate and accurate information so that users can make informed decisions about what might be possible with this field.

(In reply to Michael Weghorn from comment #7)
> (In reply to Christophe Strobbe from comment #1)
> > The "Title" matches the alt attribute for images in HTML.
> > The "Description" would match the "long description" for images in HTML and
> > there are various ways of doing this in HTML. The Web Accessibility
> > Initiative's tutorial on complex images describes a few ways of doing this:
> > https://www.w3.org/WAI/tutorials/images/complex/ .
> 
> Thanks, that's very informative.
> What about just setting the description in the "longdesc" attribute using a
> "data:" URI, like this example from
> https://www.w3schools.com/tags/att_img_longdesc.asp ?

The longdesc attribute has a long history of being rather poorly supported by screen readers and has been removed from HTML5, so that is not a good solution. (Please note that W3Schools is not related to the W3C and that their tutorials have no higher authority than anybody else's.)

> 
> > <!-- The description is included in a data:URI -->
> > <img src="w3html.gif" alt="W3Schools.com" width="100" height="132" longdesc="data:text/html;charset=utf-8;,%3C!DOCTYPE%20html%3E%3Chtml%3E%3Chead%3E%3Ctitle%3EDescription%20of%20the%20Logo%3C/title%3E%3C/head%3E%3Cbody%3E%3Cp%3ESome%20description%20goes%20here%3C/body%3E%3C/html%3E">
> 
> Not having much experience with either HTML or a11y, that looks to me like
> it might be a rather straightforward way. 

Longdesc had fairly poor support in browsers and screen readers when used correctly (using a regular URL or URL fragment). I have never seen the data:URI version in the wild, nor tested it.

> 
> > A technique not described in the above tutorial is using the details and
> > summary elements inside the figcaption element below the image (img and
> > figcaption being both wrapped in the figure element), so the long
> > description is available through a disclosure widgets. This works both for
> > screen reader users and other keyboard users. (An example in German can be
> > found at
> > https://digitalisierung.hdm-stuttgart.de/barrierefreiheit/gesetze-und-
> > richtlinien/ .)
> 
> LO provides the possibility to insert a caption to the image (right click ->
> "Insert Caption"), which seems to be what "figcaption" is for semantically
> in the first place (at a quick glance, but I'm not very experienced with
> either HTML or a11y) so I'm wondering whether using "figcaption" for
> something else wouldn't somehow "conflict" with that concept?

I hope I haven't caused any confusion with the example from HdM Stuttgart. A caption is no replacement for a text alternative or a long description, since the caption is also presented to sighted users and can be used in LO to generated a "Table of Figures" for the entire document.
I wanted to show that there are many techniques for long descriptions in HTML instead of just one "canonical" one, so if you want to use LibO as an HTML editor, you will at some point encounter a method that is not supported by LibO. That would be different if LibO only exported HTML, just like it only exports PDF without enabling PDF editing as such.

> 
> > (Note also that "Description" should only be filled in for images that are
> > too complex to be described using only an alt attribute. The alt attribute
> > is always read; the long description is presented through a mechanism that a
> > screenreader user can chose to ignore or skip. In many cases, this is a
> > link.)
> 
> Do I understand correctly that this is something that the user decides, so
> should be mentioned in the documentation?

If a long description is available, its availability should be announced to the user (based on the appropriate API call between LibO and the screen reader), at which point the user decides whether to read it or not. (This is how NVDA implemented it in 2012, for example: https://github.com/nvaccess/nvda/issues/809 .)


> 
> Interestingly, Word (or its ODT import functionality) doesn't seem to use
> the concept of separate fields for title and description. When opening the
> sample file in Word, right-clicking the image and selection "Edit alt text",
> an "Alt Text" box shows up that has the content of both fields merged
> together:
> 
> > This is the text alternative
> > 
> > This is the description // where does this appear?
> 
> and it is exported to HTML like this:
> 
> > <img width=166 height=314
> > src="Description%20Test%20file_files/image002.gif" align=left hspace=12
> > alt="Title: This is the text alternative - Description: This is the description > // where does this appear?"
> > v:shapes="Image1">

Until version 2016, MS Word had two separate fields: Title and Description. Since Word 2019, there is only the Alt Text field. (Word 2019 also introduced the "Mark as decorative" textbox.) Some people are still using Word 2016, especially those who don't want to move to a subscription-based model for desktop software.

Apologies for the long "omnibus" comment:

(In reply to Michael Weghorn from comment #8)
> (In reply to sdc.blanco from comment #6)
> > For example:
> > 1. Is Text Alternative and Description only relevant in relation to export
> > (HTML, PDF)?  Or does it have (or is supposed to have) other purposes?
> 
> I think that it can also be helpful when using LO itself get a text
> description, just the same as it can be used with HTML or PDF.

The distinction between the (short) text alternative and the long description applies across document formats: HTML, PDF, LibreOffice Writer, LibreOffice Impress, ...
(I can only speculate about the reasons why Microsoft Word 2019 removed the distinction; it might just be because the goal of "Title" versus "Description" was not clear from the UI and documentation and hence confused authors.)

(In reply to Michael Weghorn from comment #8)
> (In reply to Christophe Strobbe from comment #1)
> > (Note also that "Description" should only be filled in for images that are
> > too complex to be described using only an alt attribute. The alt attribute
> > is always read; the long description is presented through a mechanism that a
> > screenreader user can chose to ignore or skip. In many cases, this is a
> > link.)
> 
> -> "description" is supposed to be used for a more detailed description of
> the image if a "short summary" in the "Text Alternative" field doesn't cover
> all relevant information?

Right. You always fill in the field "Alternative (Text only)" (soon to be renamed so something better; see Bug 148941 ). If the image is too complex or contains too much detail, you only describe the most essential information in "Alternative (Text only)" and add the full details in "Description".

(In reply to sdc.blanco from comment #9)
> I have seen in BZ (but could not find it again) that one person mentioned
> using the Description field for documentation in a corporate setting (maybe
> in/with templates).
> 
> iiuc, you imagine that hovering the mouse over an object would show the
> "Alternative Text" and/or "Description"?  (sounds good!)
> How would you display the data if both fields are used?
> 
> And maybe an option in Tools > Options > View to toggle which ones are
> shown?  (It looks like there is just enough room next to Mouse to put the
> controls.)

"Description" is not really related to corporate contexts. However, I can imagine that companies often use charts and diagrams that are too complex to be described with a short text alternative and that the description field therefore becomes more important.

Neither "Alternative Text" nor "Description" are primarily intended for tooltips and I am wary of recommending exposure as a tooltip for two reasons:
1. Screen reader users don't use a mouse, so tooltips are not exposed to them. (Just like the "title" attribute in HTML, which is useless to screen reader users.)
2. Sighted authors might start thinking that those attributes are intended for tooltips and begin use them for additional information instead of text alternatives.


(In reply to sdc.blanco from comment #10)
> > > But what can be said about the use/function of Description?
> No strong opinions here -- happy to follow the sensible ideas already being
> proposed/developed here by Christophe and Michael.
> 
> But one question in relation to the help page for the "Description" control.
> Here is the current text:
> 
>    Enter a description text. The long description text can be entered to
>    describe a complex object or group of objects to users with screen reader
>    software. The description is visible as an alternative tag for 
>    accessibility tools.
> 
> Notice the mention about screen reader software and accessibility tools. Two
> questions.
> 
> 1.  Should the help page mention these topics at all?  (I am assuming "yes").

Yes, but how you mention them is important, since most people are not familiar with them. (See more below.)


> 
> 2.  But if yes, then presumably there are some standards (e.g., alt tag)
> that are used to support screen readers and other tools.  But I get the
> impression (from the links that Christophe has sent) that "description" is
> not so standardized.  So maybe it is necessary to simply explain clearly
> what gets exported to PDF and HTML (are there other exports?) -- without
> making these generic/vague claims about screen reader software, etc.  Maybe
> something like:
> 
>    Whether the Description tag is used by other software depends on the 
>    software's implementation.   
> 
> Not trying to promote a particular formulation here -- rather my concern is
> that the description of Description should give adequate and accurate
> information so that users can make informed decisions about what might be
> possible with this field.

I think the guidance on both Title and Description needs a rewrite. I would suggest the following:

Title

Enter a short text alternative [for the object]. This text alternative should convey the same information as the object. If you are in doubt about how to formulate the text description, imagine how you would describe it to someone over the phone in one or two sentences. The meaning of the document should not change if the object were replaced by the text alternative. Assistive technologies, such as screen readers used by blind people, announce the presence of the image and then read the text alternative.

Description

Enter a long description for the object. Use this field only if the image is too complex or contains too much detail to be described with a short text alternative. In that case, the short text alternative contains only the most essential information and the (long) description contains all the additional details. Assistive technologies, such as screen readers used by blind people, should announce the presence of a long description to the user (typically after reading the short text alternative); the user then decides whether to read it or not.


Is this too much detail or too technical? It has the benefit of leaving out HTML support (because I prefer to leave that out until we have fixed the issue of exporting long descriptions) and gets rid of the formulation "is visible as", which is not very appropriate for data that are mainly intended for blind users.

(In reply to Christophe Strobbe from comment #12)

> Neither "Alternative Text" nor "Description" are primarily intended for
> tooltips.
Understood.  But BZ shows that people use or want to use the possibilities in the software.

> 2. Sighted authors might start thinking that those attributes are intended
> for tooltips and begin use them for additional information instead of text
> alternatives.
IIUC, at present LO does not use those fields when hovering the mouse over non-text objects. Michael was just pointing out that this possibility might be attractive to some.

If this capability were added, then could we address your concern by using the "help" page -- by pointing out that if this feature is being used to create "accessible" documents, then "Text Alternative" should only be used to describe the object.

This is an example of my point at the end of comment 10,
(a) do not tell the user what to do, but
(b) give adequate information so that they can make an informed decision about how to use the feature.
 
> Is this too much detail 
Yes (in relation to help page) and No (in relation to giving a better idea of what needs to be documented in help).


> HTML support (because I prefer to leave that out until we have fixed the
> issue of exporting long descriptions)
Assuming/hoping this will be resolved soon.  Will wait to update the help until "the dust from construction settles".

Final question:
> Assistive technologies, such as screen readers used by blind people, should
> announce the presence of a long description to the user 
But how can these technologies know that a "long description" is present?  Doesn't it depend on LO exporting this information to an HTML or PDF tag (or internally to its own documents if this capability is added) in a form that would likely to be recognized by these technologies? 

I ask because the online help has to document what happens, not what "should" happen.

(In reply to sdc.blanco from comment #13)
> (In reply to Christophe Strobbe from comment #12)
> > 2. Sighted authors might start thinking that those attributes are intended
> > for tooltips and begin use them for additional information instead of text
> > alternatives.
> IIUC, at present LO does not use those fields when hovering the mouse over
> non-text objects. Michael was just pointing out that this possibility might
> be attractive to some.
> 
> If this capability were added, then could we address your concern by using
> the "help" page -- by pointing out that if this feature is being used to
> create "accessible" documents, then "Text Alternative" should only be used
> to describe the object.

Regarding 'if this feature is being used to > create "accessible" documents':
It should *only* be used for accessibility and for nothing else. Using it for tooltips would constitute abuse of the feature. (Accessibility is a requirement, not a favour done to people with disabilities.)


> This is an example of my point at the end of comment 10,
> (a) do not tell the user what to do, but
> (b) give adequate information so that they can make an informed decision
> about how to use the feature.

Regarding the suggestion: 'Whether the Description tag is used by other software depends on the software's implementation.'

This does not seem very helpful. First, "other software" is very vague. Second, to the reader of the documentation, this casts doubt on the usefulness of "Description", whereas I want it to be used when accessibility considerations require it.


> Final question:
> > Assistive technologies, such as screen readers used by blind people, should
> > announce the presence of a long description to the user 
> But how can these technologies know that a "long description" is present? 
> Doesn't it depend on LO exporting this information to an HTML or PDF tag (or
> internally to its own documents if this capability is added) in a form that
> would likely to be recognized by these technologies? 
> 
> I ask because the online help has to document what happens, not what
> "should" happen.

The usefulness of a long description in an ODF file does not depend on first exporting it to HTML or PDF. Assistive technologies interact with other software through Accessibility APIs. One such API is IAccessible2, which was part of IBM's donation to OpenOffice.org a few years ago (and from there inherited by LibreOffice). (See https://www.zdnet.com/article/ibm-throws-its-source-code-and-support-behind-openoffice/ )

IAccessible2 is a platform-independent Accessibility API (unlike Gnome's ATK/AT-SPI, MS Windows's UI Automation and Apple's accessibility APIs). The NVDA issue I referenced in my previous comment (see https://github.com/nvaccess/nvda/issues/809 ) contains a link to a commit at https://github.com/nvaccess/nvda/commit/0ac840a8a14ebe18f25b7392d13077b8391f97e8 that uses IAccessible2 to query the browser for the presence of a long description. More specifically, it uses the IAccessibleAction Interface documented at https://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/interface_i_accessible_action.html .
I imagine LibreOffice would do something similar.

(In reply to sdc.blanco from comment #9)
> (In reply to Michael Weghorn from comment #8)
> > I think that it can also be helpful when using LO itself get a text
> > description, just the same as it can be used with HTML or PDF.
> iiuc, you imagine that hovering the mouse over an object would show the
> "Alternative Text" and/or "Description"?  (sounds good!)
> How would you display the data if both fields are used?

I didn't think of any specific way on how to show this to the user. It was more a general "That information is available, so can be accessed, e.g. by people with screen readers". What would be the best way to represent this would be a separate question (and IMHO a bit out of the scope of this ticket, which is about HTML export).
The obvious way that would already work by now (but is complicated) is by opening the dialog where the description can be edited and move the cursor to that field to have the screen reader speak the text.
One thought was that ideally, there would be some way to expose this via existing attributes/methods in the corresponding a11y interfaces for the different platforms, and could then e.g. be queried by the screen reader on demand, like e.g. Orca's "What's this" functionality (s. https://help.gnome.org/users/orca/stable/howto_whereami.html.en) that queries different information depending on what kind of object is selected.

Update: While looking into what the NVDA commit mentioned by Christophe does, his comment 14 came in...

(In reply to Christophe Strobbe from comment #14)
> IAccessible2 is a platform-independent Accessibility API (unlike Gnome's
> ATK/AT-SPI, MS Windows's UI Automation and Apple's accessibility APIs). The
> NVDA issue I referenced in my previous comment (see
> https://github.com/nvaccess/nvda/issues/809 ) contains a link to a commit at
> https://github.com/nvaccess/nvda/commit/
> 0ac840a8a14ebe18f25b7392d13077b8391f97e8 that uses IAccessible2 to query the
> browser for the presence of a long description. More specifically, it uses
> the IAccessibleAction Interface documented at
> https://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/
> interface_i_accessible_action.html .
> I imagine LibreOffice would do something similar.

That's really helpful, thanks a lot! I didn't test it, but reading the  IAccessibleAction interface doc, the interesting question would then probably be what to do if the "long_description" action (or whatever it's called) is performed. From initial reading, IAccessibleAction doesn't seem to be meant to be used to just get a textual representation of something in the first place, but to execute some action. I could imagine that Firefox e.g. opens the corresponding page linked there, but I haven't actually tried. 
There is  IAccessibleAction::description (s. https://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/interface_i_accessible_action.html#a7c8d49908df62d2ca14794b7ee2977d5 ), but that's rather meant to return a description of what *the action does*, so *I think* it wouldn't just return the text set as description for the image. (?)

(In reply to sdc.blanco from comment #10)
> Notice the mention about screen reader software and accessibility tools. Two
> questions.
> 
> 1.  Should the help page mention these topics at all?  (I am assuming "yes").
> 
> 2.  But if yes, then presumably there are some standards (e.g., alt tag)
> that are used to support screen readers and other tools.  But I get the
> impression (from the links that Christophe has sent) that "description" is
> not so standardized.  So maybe it is necessary to simply explain clearly
> what gets exported to PDF and HTML (are there other exports?) -- without
> making these generic/vague claims about screen reader software, etc.  Maybe
> something like:
> 
>    Whether the Description tag is used by other software depends on the 
>    software's implementation.   

As Christophe mentions, I think it makes sense to have a description independent of potential export formats and I like Christophe's suggestion from comment 12 for the descriptions of the meaning.
For ODF itself, the corresponding attribute is "svg:desc", described as:
"The <svg:desc> element specifies a prose description of a graphic object that may be used to support accessibility. See appendix D."
( https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part3-schema/OpenDocument-v1.3-os-part3-schema.html#__RefHeading__1415840_253892949 )


Back to HTML export:

@Christophe:
Comment 11 and comment 12 are very helpful, thanks!
But to be honest, after reading those, I don't know what would be a proper way of handling "Description" on HTML export.
Any suggestion?

(In reply to Christophe Strobbe from comment #11)
> The longdesc attribute has a long history of being rather poorly supported
> by screen readers and has been removed from HTML5, so that is not a good
> solution.

That seems to rule out "longdesc", which otherwise looks like it would be quite equivalent from a semantic perspective.

(In reply to Christophe Strobbe from comment #11)
> A caption is no replacement for a text alternative or a long description,
> since the caption is also presented to sighted users and can be used in LO
> to generated a "Table of Figures" for the entire document.

As I understand it, "the caption is also presented to sighted users" also applies for the "figcaption" in HTML, so exporting the description to that would generate visible output in the HTML page. My general expectation would be that the description would generally not be visible in an exported document by default, since it isn't visible in Writer either.
So, with my limited background knowledge, that doesn't really sound like a perfect match either.

Reading https://www.w3.org/WAI/tutorials/images/complex/ more or less gives me the impression that using an image caption instead of the "Description" would maybe be a better way to create accessible documents that are meant to be exported to HTML in the first place...

> Until version 2016, MS Word had two separate fields: Title and Description.
> Since Word 2019, there is only the Alt Text field.

Regarding the described situation, merging "Alternative (Text only)" and "Description" and put the resulting text into the "alt" attribute on HTML export also sounds like a somewhat interesting idea, but also far from perfect. It would fulfill the expectation that the text is not visible by default, but more of a "tag"/annotation for the image. However, having all of the text in the "alt" attribute also doesn't really sound great, since it's meant to be used for a short summary only...

I really don't know what the best solution here would be. I can think of reasons to argue for any of these:

1) It already "works as designed": Since there is no real equivalent for the image description in HTML (other than "longdesc", which is obsolete and wasn't properly supported by screen readers anyway), not exporting it is "correct".
If something should show up as a caption in HTML, it should be added as such in Writer.

2) Use "figcaption" in some way. (How?) https://www.w3.org/WAI/tutorials/images/complex/ describes it as a way for providing long descriptions.

3) on HTML export, merge "Alternative (Text only)" and "Description" into the "alt" attribute, since that is meant to be used to provide an alternative description.

> I wanted to show that there are many techniques for long descriptions in
> HTML instead of just one "canonical" one, so if you want to use LibO as an
> HTML editor, you will at some point encounter a method that is not supported
> by LibO. That would be different if LibO only exported HTML, just like it
> only exports PDF without enabling PDF editing as such.

That's an additional aspect. Since this ticket is about HTML export, that was what my comments were referring to.

I'll skip the discussion on how the long description should be exposed in LibreOffice, since this issue is about how it should be exported to HTML.

(In reply to Michael Weghorn from comment #15)
> (In reply to sdc.blanco from comment #10)
> (...)
> For ODF itself, the corresponding attribute is "svg:desc", described as:
> "The <svg:desc> element specifies a prose description of a graphic object
> that may be used to support accessibility. See appendix D."
> (
> https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part3-schema/
> OpenDocument-v1.3-os-part3-schema.html#__RefHeading__1415840_253892949 )

That is correct.

> @Christophe:
> Comment 11 and comment 12 are very helpful, thanks!
> But to be honest, after reading those, I don't know what would be a proper
> way of handling "Description" on HTML export.
> Any suggestion?

I would suggest the following:

Export the contents of the ODF <svg:desc> element to a <p> element below the <p> element containing the <img> element. Give that <p> element an ID attribute. Give the <img> element an aria-describedby attribute that points to the paragraph's ID attribute.
Example (simplified):

<p><img src="..." alt="..." aria-describedby="longdescription1" name="..." /></p>
<p id="longdescription1">[Contents of ODF's svg:desc element inserted here]</p>

(Adding a longdesc to the img element is optional, due to poor support. The syntax of the attribute would then be longdesc="#longdescription1", since it expect a URL or a fragement identifier, whereas the aria-describedby expects an ID.)

Note that when LibreOffice starts exporting image captions correctly (in LibreOffice 7.1.4.2, the caption text gets embedded in the exported image), the p element with the description would be below the caption (assuming the caption is below instead of above the image).


> (In reply to Christophe Strobbe from comment #11)
> > The longdesc attribute has a long history of being rather poorly supported
> > by screen readers and has been removed from HTML5, so that is not a good
> > solution.
> 
> That seems to rule out "longdesc", which otherwise looks like it would be
> quite equivalent from a semantic perspective.
> 
> (In reply to Christophe Strobbe from comment #11)
> > A caption is no replacement for a text alternative or a long description,
> > since the caption is also presented to sighted users and can be used in LO
> > to generated a "Table of Figures" for the entire document.
> 
> As I understand it, "the caption is also presented to sighted users" also
> applies for the "figcaption" in HTML, so exporting the description to that
> would generate visible output in the HTML page. My general expectation would
> be that the description would generally not be visible in an exported
> document by default, since it isn't visible in Writer either.
> So, with my limited background knowledge, that doesn't really sound like a
> perfect match either.
> 
> Reading https://www.w3.org/WAI/tutorials/images/complex/ more or less gives
> me the impression that using an image caption instead of the "Description"
> would maybe be a better way to create accessible documents that are meant to
> be exported to HTML in the first place...
>

Mapping ODF's <svg:desc> to HTML5's figcaption would cause a mismatch. LibreOffice's "save as HTML" would need to handle image captions correctly before we can consider ways of referencing a long description from an HTML figcaption element. ODF's captions are currently not exported to HTML as text but embedded in the image to which they belong: see Bug 142356.

(LibreOffice's "Export as XHTML" function exports to "XHTML 1.1 plus MathML 2.0", which has no figure or figcaption elements, since these elements were first introduced in HTML 5. XHTML 1.1 has been superseded since 2018: https://www.w3.org/TR/xhtml11/ .)

@Christophe: Thanks for all your input here! Setting to NEW.

fwiw – this ticket was opened because I could not come further in updating the help page for the Description dialog (Format > Description) (e.g., because of ambiguities or contradictions between the help page and the current actual behavior).

Needed to have/see the discussion in this ticket so that the help could be revised in an appropriate way.  Also as expected, these questions help clarify the software development. That purpose is now accomplished adequately, so thanks for bearing with my naive questions. Have opened bug 149130 for the help page. Thanks to Christophe and Michael for informative discussion.

Meanwhile, however this current ticket is resolved, it will be helpful to know exactly what gets exported to HTML (for frames, images, OLE objects, shapes, textboxes), so that it can be documented on the help page. Thanks.

Just in case it requires additional attention -- 

Tools > Imagemap - select imagemap - right-click - Description provides the possibility to add "Text Alternative" and "Description" to an imagemap.

"Text Alternative" is exported to the image map. "Description" is not.

Here is a fragment from my test.

<map name="map1">
<area shape=rect coords="5,8,108,108" nohref name="ImageMap" alt="This is Text Alternative">
</map>

Thanks for a very informative discussion, this is a bug report to keep handy for a long list of useful accessibility references.

LO 6.3 didn't keep the description either, when either saving as HTML or exporting as XHTML:

Version: 6.3.6.2
Build ID: 2196df99b074d8a661f4036fca8fa0cbfa33a497
CPU threads: 8; OS: Linux 5.15; UI render: default; VCL: gtk3; 
Locale: en-AU (en_AU.UTF-8); UI-Language: en-US
Calc: threaded

Also changing the component to "Writer" as "Writer Web" is about the alternative view.