Code blocks need alternative text

PDF/UA check CODE_ALT_TEXT · Structure & other · severity High · PDF/UA 8.2.5.32 Code

↩ Back to the rules index · WCAG cross-reference

Why it matters#

Code blocks (programming code, command-line examples) without alternative text are read character-by-character as nonsense. Affects technical documentation heavily.

What you will see#

A Code element has no Alt or ActualText, so it is read out character by character as nonsense.

How to fix#

Add an ActualText entry to the Code structure element containing the literal code text when the code is rendered as an image or vector art rather than real text. An Alt entry describing the code may be added as well, but is optional.

Step-by-step guide#

1. Locate the flagged Code element in the Accessibility tags panel using the EQChecker report and determine how the code is rendered: real selectable text, or an image / outlined vector art.
2. If the code is an image or vector outlines, add the literal code as ActualText: Properties > Tag tab > Actual Text, entering the exact code text including meaningful whitespace and line breaks. ISO 14289-2 8.2.5.32 requires a textual representation where the code is intended to be consumed as text.
3. Alternatively (or additionally) fill Alternate Text with a description of what the code does; EQChecker accepts either entry, though 8.2.5.32 makes Alt explicitly optional in the standard.
4. Note that even when the code is already real text - which satisfies the standard itself - EQChecker cannot verify the drawn text is complete and keeps warning until the Code element carries an Alt or ActualText entry.
5. Better long-term fix: re-export from the source with the code as real text in an embedded monospace font instead of a screenshot, then add a brief Alt or ActualText to clear the checker.

Verify: Re-run the EQChecker scan: the CODE_ALT_TEXT warning clears once the Code element carries a non-empty Alt or ActualText entry. Real text content alone does not clear this particular check.

Note: The 8.2.5.32 SHALL covers only a textual representation where the code is intended to be consumed as text, and an Alt property is explicitly optional (may) - hence EQChecker reports a warning, not an error. ActualText flattens the subtree for assistive technology and some readers normalize line breaks inside it: short fragments work well, but for long listings prefer real text plus a brief Alt.

WCAG success criteria#

1.3.1 Info and Relationships — Level A#

Structure and relationships conveyed visually (headings, lists, tables, labels, groups) must also be available programmatically.

Understanding 1.3.1

Standards#

This check contributes to the following standards:

PDF/UA WCAG A EN 301 549