Bug 149130

Summary:	Explanation of controls for Description dialog needs to be improved
Product:	LibreOffice	Reporter:	sdc.blanco
Component:	Documentation	Assignee:	sdc.blanco
Status:	RESOLVED FIXED
Severity:	normal	CC:	c_strobbe-fdo, olivier.hallot
Priority:	medium
Version:	7.4.0.0 alpha0+
Hardware:	All
OS:	All
Whiteboard:	target:7.4.0
Crash report or crash signature:		Regression By:
Bug Depends on:	149013, 57423
Bug Blocks:	120200
Attachments:	first draft for description help page

Description sdc.blanco 2022-05-17 12:00:16 UTC

Select an object
Format > Description, press F1

This gives: https://help.libreoffice.org/7.4/en-US/text/shared/01/05190100.html
the help page for the Description dialog.

Title needs to be updated, because of bug 148941

The descriptions of the two controls appear to be the original versions from 2003, and are not accurate. 

Proposal from Christophe Strobbe copied from bug 149013 comment 12

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.

Comment 1 sdc.blanco 2022-05-17 12:07:31 UTC

The two controls on the Description page are also found in the Options tab for the Properties Dialog for images, frames, and OLE objects, so these descriptions will also be embedded in the help page for the Options tab. https://help.libreoffice.org/7.4/en-US/text/swriter/01/05060900.html

Comment 2 sdc.blanco 2022-05-25 01:33:41 UTC

Created attachment 180356 [details]
first draft for description help page

Attached is a document with the following text, which is a first proposal for the help page for the Description dialog.

Description

Assigns a text alternative and a description to the selected object. These texts are available as alternative tags in your document for use by accessibility tools. They are also available as tags for images when you export the document.

Text Alternative

Enter a short description of the essential details of the selected object for a person who cannot see the object. This text is available for use by assistive technologies.

Description

Enter a longer description of the object, especially if the object is too complex or contains too much detail to be described adequately with the short Text Alternative. Use Description to add additional information to the short description found in Text Alternative. This text is available for use by assistive technologies.


(The following text will be placed in a separate "note" box, with a link to the help page about PDF/UA)

For images, Text Alternative and Description are exported with an appropriate tag in HTML and PDF format (remember to enable the Universal Accessibility (PDF/UA) option in PDF export).

Comment 3 sdc.blanco 2022-05-26 10:55:59 UTC

https://gerrit.libreoffice.org/c/help/+/134191

Comment 4 sdc.blanco 2022-05-29 07:21:50 UTC

No further input or comment received.

Comment 5 Commit Notification 2022-05-29 07:23:52 UTC

Seth Chaiklin committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/commit/2df65a1ff7072dc0ec866f5dfe11846c15208199

tdf#149010,tdf#148941,tdf#149012,tdf#149130 update to reflect changes

Comment 6 sdc.blanco 2022-05-29 07:25:41 UTC

Closing as FIXED.  If small adjustments are still needed, then followups can be sent here.