What we want to state about rendering <desc> when it applies to tables

[Kristen James Eberlein <kris@eberleinconsulting.com>]

This e-mail relates to the following exchange in the DITAweb review:

Regarding this sentence: In addition, the optional <desc> element enables a table description that is parallel with a figure description. I don't think the comparison with a figure description offers any value to the reader. The purpose of this optional element is to hold a description of the table that contains additional information not found in the table title. Renderers may use this description to describe the table upon user request or when the table cannot be rendered. (Consider assistive readers here, the audio readout often reads the description instead of the table itself, or before the table itself.)	gjoseph	new	comment	15/12/2021 08:55:47
I agree that the comparison with figure is not useful. However, do remember that desc is not the equivalent of alt; the contents of desc within tableÂAREÂintended to be rendered in the content flow. In fact, we have a normative statement to this effects in the "Rendering expectations" section of the desc topic. Changed the second sentence to simply read "In addition, the optional descÂelement enables a table description." I wonder whether we need to mention in this (table) topic that when used, the content of the optional desc and title elements are typically rendered as part of the content flow. @Robert and @Gershon?	keberlein	updated	comment	15/12/2021 15:17:47
I'm not sure. Strictly speaking, that's about rendering <desc>. But yeah I assume it will be missed if we don't mention it here. Implementations I've worked with always display the desc by default as part of the content flow, visible in the browser / without a screen reader. That said, I've also helped with customizations that explicitly used this as the screen reader summary of the table. I think either approach is valid (which is why the spec makes this a SHOULD and not a MUST), but must be used consistently or your content breaks -- which is why there is a normative rule pushing one consistent default.	randerson	new	comment	15/12/2021 23:15:13
@Robert, so what do we want to do here? Add a "Rendering expectations" section, and mention that the contents of the optional desc and title are typically rendered as part of the content flow? Do we want to make any mention of implementations using the content of desc as a screen reader summary of the table? Or is that more appropriate for mention in the desc topic? Bring this item to the TC for discussion?	keberlein	new	comment	16/12/2021 13:57:49
I would bring it to the TC because this confuses so many people, but with a suggestion that we resolve it by adding a rendering section that reminds that the description is typically part of the document flow. I'd probably favor noting that implementations have been known to use this as table-summary metadata, but I'm not sure how to say that with spec language and not totally upend the "SHOULD be rendered" normative rule from the desc topic.	randerson	new	comment	16/12/2021 14:40:31

--
Best,
Kris