XSL-FO based PDFs don't include heading tags

[rjcbop]

We've found that PDFs generated from the XSL-FO approach (e.g., built from the "DITA Map PDF - based on XSL-FO" transformation scenario), and with accessibility enabled, don't include heading tags such as H1, H2, etc. This poses a problem for meeting 508 accessibility standards since screen reader users rely on the heading tags to understand document structure. We did, however, notice that the heading tags are included in PDFs generated from the CSS approach.

It's simple to add the heading tags for topic titles (in the XSL-FO approach) by including a "role" attribute in the attribute set for each level of topic title. For example, for a top level title, you just need to add the following to a customized version of the "topic.title" attribute set:

<xsl:attribute name="role">H1</xsl:attribute>

However, in the case of a section within a topic (i.e., generated from a <section> element in a concept topic), you'd need to write some code to determine the nesting level of the topic that includes the section. Before considering to write that code ourselves, we wanted to check with the Oxygen team to see if there were any plans to do that?

Thanks

[xephon]

rjcbop, there development of the current pdf2 plugin is stale. I have also added some interesting features, like XMP handling and think about forking the plugin. Maybe we can join forces.

[julien_lacour]

Hello,

If the join forces leads to an issue on DITA-OT GitHub side, could you add the link here?
It's just for follow-up purpose. Thank you both!

Regards,
Julien

[rjcbop]

I've found a very simple fix that leverages the get-topic-level code that's included in the DITA OT's version of topic.xsl. Specifically, to add the correct heading level to a section element, you just need to override the template (within topic.xsl) that matches the section title, as follows:

<xsl:template match="*[contains(@class,' topic/section ')]/*[contains(@class,' topic/title ')]">
<fo:block xsl:use-attribute-sets="section.title">
<xsl:variable name="level" as="xs:integer">
<xsl:apply-templates select="." mode="get-topic-level"/>
</xsl:variable>
<xsl:call-template name="commonattributes"/>
<xsl:attribute name="role">
<xsl:value-of select="concat('H',$level+1)"/>
</xsl:attribute>
<xsl:apply-templates select="." mode="customTitleAnchor"/>
<xsl:apply-templates select="." mode="getTitle"/>
</fo:block>
</xsl:template>

This same approach (using the 'level' variable to get the topic level and then adding the @role attribute to specify the heading level) can also be applied to the case of a section element with a @spectitle attribute (instead of a <title> element) and to the case of an example element.

[julien_lacour]

Hello,

Could you indicate which tool you are using for checking 508 accessibility standard compliance?
I tried with PAC 2021 and Acrobat internal tool, but, even if the role is missing in the FO file, the checker says nothing about headings.

Regards,
Julien

[rjcbop]

Hi Julien,

Automated PDF accessibility checkers will not flag the absence of headings, but the absence of headings is something you'll notice if you read the document with a screen reader (such as NVDA). The absence of heading tags means that headings are specified with styling rather than structure, which makes it more difficult for screen reader users to understand the structure of the document. For reference, here is a link to WCAG's guidance on heading tags for PDFs: https://www.w3.org/WAI/WCAG21/Techniques/pdf/PDF9

Regards,
Rich