Version 5.9.21

Accessibility / tagged PDF

What is tagged PDF?

Tagged PDF is an extension of the PDF file with a logical structure of the content. The tags are used to determine the role of the object to be output, e.g. level 1 heading, a paragraph or an image. This is mainly used to create accessible PDFs, i.e. PDFs that are optimized for screen readers or similar output devices.

For accessible PDFs, not only the technical side must be taken into account (this is what the speedata Publisher is for), but also the logical structure must be created sensibly. For example, images must be output with an alternative text, otherwise their use is restricted.

Example

In the following example, the document is not further divided into sub structures. A heading (H1) and an image (Figure) are output in this section.

<Layout xmlns="urn:speedata.de:2009/publisher/en"
	xmlns:sd="urn:speedata:2009/publisher/functions/en">

  <PDFOptions format="PDF/UA" />

  <StructureElement role="Document" id="doc" />

  <Record element="data">
    <PlaceObject>
      <Textblock>
        <Bookmark level="1" select="'My image collection'"/>
        <Paragraph role="H1" parent="doc">
          <Value>My image collection</Value>
        </Paragraph>
      </Textblock>
    </PlaceObject>

    <PlaceObject>
      <Image parent="doc"
             description="an ocean"
             file="ocean.pdf"
             width="4cm" />
    </PlaceObject>
  </Record>
</Layout>

Hierarchical structure

By default, the role “Document” is defined with the ID doc. This corresponds to the following structure:

<StructureElement role="Document" id="doc" />

There are two ways to define further structures. Either these are defined in a nested manner (both examples create the same structure):

<StructureElement role="Document">
	<StructureElement role="Art">
		<StructureElement role="Sect" id="sect1a1"/>
		<StructureElement role="Sect" id="sect2a1"/>
	</StructureElement>
	<StructureElement role="Art">
		<StructureElement role="Sect" id="sect1a2"/>
		<StructureElement role="Sect" id="sect2a2"/>
	</StructureElement>
</StructureElement>

or you can use the parent attribute:

<StructureElement role="Document" id="doc" />
<StructureElement role="Art" id="art1" parent="doc" />
<StructureElement role="Art" id="art2" parent="doc" />
<StructureElement role="Sect" id="sect1a1" parent="art1"/>
<StructureElement role="Sect" id="sect2a1" parent="art1"/>
<StructureElement role="Sect" id="sect1a2" parent="art2"/>
<StructureElement role="Sect" id="sect2a2" parent="art2"/>

This allows the document to be structured dynamically based on the data.

The id attribute is necessary to specify the parent structure for paragraphs and images. In the example above, both elements are output in the Sect section.

Roles (tag names)

The following role names (tags) are defined in the speedata Publisher. Others can be added on request:

Art, Artifact, Div, Document, Figure, H1, H2, H3, H4, H5, H6, Lbl, Link, P, Part, Sect, Span, Table, TD, TH, TOC, TOCI, TR.

Order of the structure elements

The hierarchical structure is created in the order in which they are output in the Publisher. This means that objects that are output first appear higher in the structure. However, if you want to output an H1 heading after other objects, for example, it will appear further down in the document structure. To change the order, you can specify the position in the command (attribute structpos). The specification top (or equivalent 1) inserts the paragraph at the first position in the structure, below the specified parent ID (section in the example below). Alternatively, a different position can be specified, but it must be smaller than the number of current child elements.

‘Unimportant’ texts and images

Texts and images that should not appear in the hierarchy can be marked as an artifact (role).

Language

Screen readers choose the voice by the language of the text. The main language of the layout (<Options mainlanguage="...">) becomes the language of the document. A paragraph in another language gets its language with the attribute language, for example <Paragraph role="P" language="Arabic">; in PDF/UA mode the Publisher writes it to the structure element of the paragraph. Use the language of most of the text as the main language and mark the other parts. This also keeps the PDF smaller, because only text in a language other than the main language needs a language entry.

Alternative texts and image descriptions

Images should be provided with a description so that this appears in the hierarchy instead of the image. For paragraphs, it is also possible to insert the ‘real text’ (actual text). This is displayed in the hierarchy instead of the text within <Value>.

From the examples repository

This layout can also be found in the examples repository and creates a PDF/UA-compliant PDF that fulfils the requirements for accessibility. Below the top level Document there is a section Sect, which contains a heading, a paragraph without special features and a paragraph with a hyperlink, as well as an image.

(Run the speedata Publisher with sp --dummy, as variable data is not used here).

<Layout xmlns="urn:speedata.de:2009/publisher/en"
	xmlns:sd="urn:speedata:2009/publisher/functions/en">
  <PDFOptions format="PDF/UA" />

  <StructureElement role="Document">
    <StructureElement role="Sect" id="section" />
  </StructureElement>

  <Record element="data">
    <PlaceObject>
      <Textblock>
        <Paragraph role="H1" parent="section">
          <B>
            <Value>A very short story</Value>
          </B>
        </Paragraph>
        <Paragraph role="P" parent="section">
          <Value>Once upon a time....</Value>
        </Paragraph>
        <Paragraph role="P" parent="section">
          <Value>This is a </Value>
          <A href="https://www.speedata.de"
             description="link to speedata.de">
            <Value>link to speedata.de</Value>
          </A>
          <Value>.</Value>
        </Paragraph>
      </Textblock>
    </PlaceObject>
    <PlaceObject>
      <Image
          width="8"
          file="ocean.pdf"
          parent="section"
          description="An image of an ocean" />
    </PlaceObject>
  </Record>
</Layout>

The output from the layout above is as expected.

Various tools can be used to check the structure of the document:

You can use pdfuaanalyze to display the structure as an XML tree.

<Document>
  <Sect>
    <H1></H1>
    <P></P>
    <P>
      <Link></Link>
    </P>
    <Figure></Figure>
  </Sect>
</Document>

The speedata Publisher can also dump the structure tree to an XML file by using the Trace command with the attribute dump-structtree (all Trace switches are listed in the chapter Troubleshooting / Debugging):

<Trace dump-structtree="yes" />

This writes the file publisher-struct.xml which contains the structure tree of the PDF document. This is useful for debugging and for automated testing of the document structure.

Spaces between words

In the PDF, the space between two words is just a gap, not a character. Programs that extract the text (screen readers, copy and paste, search) have to guess where a word ends, and some of them run the words together. In PDF/UA mode, the Publisher therefore puts an invisible space character into every space between words. The layout does not change. With <PDFOptions interwordspace="yes"> you can switch this on for other PDFs as well, with interwordspace="no" you can switch it off.

Reading order of words

In some scripts, the glyphs of a word are not in reading order in the PDF: in right-to-left scripts such as Arabic and Hebrew, and in Indic scripts, where some vowel signs stand before the consonant they follow in the text. Programs that extract the text then get the characters of such words in the wrong order. In PDF/UA mode, the Publisher therefore stores the text of these words once more in reading order (as ActualText), together with their language if it differs from the language of the document. Words in Latin, Greek or Cyrillic script are not affected. The layout does not change, but the PDF gets larger, for a fully vowelled Arabic text by about a third. With <PDFOptions logicaltextorder="yes"> you can switch this on for other PDFs as well, with logicaltextorder="no" you can switch it off.

Not all programs use this information in the same way. Some programs that do not support right-to-left text output the words of these scripts in reverse order.

Checking the document

The following programs can be used to check accessibility:

PAC (PDF accessibility checker)
Adobe Acrobat
Vera PDF
pdfuaanalyze shows the structure of the document as XML.

Known limitations

The current issues can be viewed on GitHub.