I've got a situation where generated page references need to be screen-reader friendly, and I haven't had much luck sorting it out.

The visual page reference is generated by the following CSS:

a.pageref::after {
	content: "\00a0(p.\00a0" target-counter(attr(href), page) ")";
}

... applied to the following HTML:

See <a class="pageref" href="#appendix-a">Appendix A</a>.

... which - assuming for the sake of argument that "#appendix-a" is a valid reference that just happens to fall on page 37 - produces PDF output like so:

"See Appendix A (p. 37)."

That's a pretty standard citation, but many screen readers are confused by it - they're thrown by the parentheses, they don't know what the "p" means, and they interpret the period following it as a full stop, so the audible output ends up being something like this:

"See Appendix A pee [long pause] 37 dot"

Not ideal!

My initial thought was to use the prince-alt-text property (in combination with an output profile that supports tagged PDFs, of course) to furnish an alternative, more readable version of the ::after pseudo-element's contents, by doing something like this:

a.pageref::after {
	content: "\00a0(p.\00a0" target-counter(attr(href), page) ")";
	prince-alt-text: ", page " target-counter(attr(href), page);
}

In theory, this would result in alt text reading as follows:

"See Appendix A, page 37."

Screen readers will handle that just fine. However, that doesn't work; as soon as the target-counter enters the mix, the prince-alt-text property stops working. No console message is produced. If I remove the target-counter and leave only the static string, it works, but obviously that doesn't have a useful result. I've tried it using both the current stable build and the latest build (dated 2020-08-12) to similar results.

Any suggestions? Or should this be more of a feature request?

Currently target-counter() isn't supported on the accessibility properties but it definitely looks like it would be handy in this case, we will take a look.

Thanks for the quick follow-up - it's good to see accessibility features being taken seriously!

Actually, now that I'm looking that the PDF/UA spec more closely, it looks like it might be more appropriate to use the ActualText property rather than the Alt property in this specific context. I don't seem to see any mechanism in the Prince documentation for specifying ActualText; am I overlooking it?

Edited 11 Sep 2020 by David J Prokopetz

We put a lot of effort into supporting tagged PDF and it's very gratifying to see so many people using it and giving us feedback on the output!

The ActualText property in PDF is used in more specific ways for converting from shaped glyphs back to text, for example "glyphs for ligatures or custom characters, or inline graphics corresponding to letters in an
illuminated manuscript or to dropped capitals."

But you are right that alternate text is specific to images and other non-textual content.

Perhaps expansion text would be the most suitable in this situation, since "p." for "page" is literally an abbreviation? Hopefully screen readers would do the right thing if expansion text is present.

Yeah, I think you're right there. Would something like an icon that appears in place of a word in inline text be a more appropriate scenario for using ActualText? If so, the ability to specify ActualText would still be handy, as the document I'm working with has a few of those as well.

That sounds more like alternate text, I think the case for actual text is restricted to things like if you had the text "ábc" represented in the input document as 'a' + acute accent + 'b' + 'c' but the font happened to include a ligature substitution for "abc" and mark positioning for the accent, so in the final PDF the glyphs would come out in the order "abc" as one ligature then a movement and then the accent; it would be difficult for the reader to get that right (copy and paste would also probably not work correctly) and it might well think that the accent is applied to the 'c' instead of the 'a'. The ActualText property allows the producer to annotate what the original text was in cases where it's difficult to figure out from the glyphs.

Edited 11 Sep 2020 by mikeday

Ah, I see I'm misreading the spec, then - it means ActualText is for stuff where the actual, encoded characters may not accurately reflect how it reads visually. Thanks for the clarification.

I just noticed the following roadmap update is linked to this issue:

* Support prince-expansion-text() value on the content property for use in tagged PDF.

I'm guessing the idea is that this addresses the cited issue from another angle providing a mechanism for expansion text to be specified for the "p." in the page reference rather than (or in addition to?) supporting counters in the alt text?

If I've got the right idea, I'm curious to know what specifying expansion text for only part of a pseudoelement's content would look like in terms of CSS code.

Yes that's the idea, so you could do something like this:

content: prince-expansion-text("page ", "p. ") target-counter(attr(href), page)

And it would render as "p. 17" visually and "page 17" in the structure tree, basically treating the "p." as an abbreviation.

Huh. That's actually a much more appropriate solution than what I had in mind - the idea of applying expansion text to individual fragments of generated content didn't even occur to me. I'm keen to see it in action!

It's now available in the latest build!