Linguistics and accessibility

[niruvt]

I am working on a package in the LinguisTiX bundle for printing linguistic abbreviations. For instance, to denote present tense, linguists use PRS (not in caps, but in small caps). So, suppose in a text, a sentence like: English uses \{-s\} for denoting \abr{prs}, then it should be read as: "English uses the s morpheme for denoting present tense."

The list of standard abbreviations is small, but many a times some custom abbreviations are required. I would like to have a way to create a macro that can on the fly create the alternate text. I am willing to use the lttemplates code along with the new \DocumentMetadata{tagging=on} method. I would love to know how much of this is possible in LaTeX? From where should one start. Note that the morpheme and the abbreviation is just one small example, there are many such instances that need tagging.

[davidcarlisle]

LaTeX can probably generate whatever you need but the question is what you need, you could use ActualText but then it would essentially replace PRS and so reading and cut and paste would not have any indication it was there. An alternative would be to use Alt but the behaviour of different reading systems is a bit variable.

PDF does have an E property that is probably the most natural for this but again I am not sure how different PDF reading systems react.

pdf2.0 table 355 lists these as

Key	Value
Alt	(Optional) An alternative description of the structure element and its children in human-readable form, which is useful when extracting the document’s contents in support of accessibility to users with disabilities or for other purposes (see 14.9.3, "Alternate descriptions").
E	(Optional; PDF 1.5) The expanded form of an abbreviation or an acronym.
ActualText	(Optional; PDF 1.4) Text that is an exact replacement for the content enclosed by the structure element and its children. This replacement text (which should apply to as small a piece of content as possible) is useful when extracting the document’s contents in support of accessibility to users with disabilities or for other purposes (see 14.9.4, "Replacement text")

You could generate Alt and ActualText perhaps most easily using the accsupp package or any keys can be adding using the lower level features from the tagging code.

[davidcarlisle]

I made an example

\DocumentMetadata{tagging=on,uncompress}
\documentclass{article}

\begin{document}

Try 1 (alt)
\tagmcend\tagstructbegin{tag=Span,alt=present tense}\tagmcbegin{tag=Span}PRS\tagmcend\tagstructend\tagmcbegin{tag=Span}
more text

Try 2 (ActualText)
\tagmcend\tagstructbegin{tag=Span,actualtext=present tense}\tagmcbegin{tag=Span}PRS\tagmcend\tagstructend\tagmcbegin{tag=Span}
more text

Try 3 (E)
\tagmcend\tagstructbegin{tag=Span,E=present tense}\tagmcbegin{tag=Span}PRS\tagmcend\tagstructend
\tagmcbegin{tag=Span}
more text

\end{document}

prs.pdf

Somewhat surprisingly all three keys had exactly the same effect reading with acrobat read-aloud with no screen reader and with NVDA screen reader in acrobat or foxit. PRS was substituted by "present tense" with no announcement or indication that this is an acronym expansion. (Which is the behaviour I would expect from ActualText, less so the others.

[u-fischer]

Span is fine and I would use E for this use case. So something like this (it will work with and without \DocumentMetadata as long as LaTeX is new enough):

\DocumentMetadata{tagging=on}
\documentclass[a4paper]{article}
\NewTaggingSocket{lngx/abbr}{2}
\NewTaggingSocketPlug{lngx/abbr}{default}
 {\leavevmode
  \tagmcend\tagstructbegin{tag=Span,E={#1}}\tagmcbegin{tag=Span}%
  #2%
  \tagmcend\tagstructend\tagmcbegin{}}
\AssignTaggingSocketPlug{lngx/abbr}{default}

%Details of user interface are up to you!
\NewDocumentCommand\newlinguisticabbreviation{mm}
 {\ExpandArgs{c}\newcommand{__lngx_abbr_#2:}{\UseTaggingSocket{lngx/abbr}{#1}{\textsc{#2}}}}
\NewDocumentCommand\abr{m}{\UseName{__lngx_abbr_#1:}}
 
\newlinguisticabbreviation{present tense}{prs}
\begin{document}

English uses {-s} for denoting \abr{prs}
\end{document}

[niruvt]

I revisited Frank's talk in TUG 2025 and the example you provide seems okay. E.g., listen to this snippet from his talk (starting at 02:06:40). There is no indication that math mode has started when the text is n^p=n.

[niruvt]

@u-fischer thanks for the clarification. What should one study in order to provide tagging support for such elements? I may have newer and even more complicated artifacts that can require an announcement (e.g., verbatim text/figure/list structure from Frank's talk). I don't expect you to give the implementation. I just need a pointer to a place where I can find the details, study different types that are available for tagging and make a decision regarding the best suited one in various cases. Thanks for the help so far.

[u-fischer]

As David wrote this case is described in the PDF standard. But the standard does not tell you how this read out, as that depends on the implementation in PDF readers and screen reader. So you have to try with various options. The standard also don't tell you if this tagging is something that is really helpful to blind people. I don't know if they want to get the abbreviation read out all the time or if they would prefer to hear the same that you see, namely "prs". For this decision you have to find users in the field that give you feedback.

[niruvt]

I will try to get in touch with the people in community. Thanks for the information. My original question is answered. Unless I need further clarification, I don't mind if the discussion thread is closed.

[davidcarlisle]

@niruvt the PDF 2.0 specification (which is available at no cost but you have to sign up to download it) says this about acronyms

14.9.5 Expansion of abbreviations and acronyms

The expansion of an abbreviation or acronym may be specified for the following items:
• Marked-content sequences, through an E property in a property list attached to the marked-
content sequence with a Span tag.
• Structure elements, through an E entry in the structure element dictionary. (See "Table 355 —
Entries in a structure element dictionary".)

NOTE 1 Abbreviations and acronyms can pose a problem for text-to-speech engines. Sometimes the full
pronunciation for an abbreviation can be divined without aid. For example, a dictionary search
will probably reveal that "Blvd." is pronounced "boulevard" and that "Ave." is pronounced
"avenue." However, some abbreviations are difficult to resolve, as in the sentence "Dr. Healwell
works at 123 Industrial Dr."

[niruvt]

Thanks for adding this. I will keep this in mind and check the specification too.

[davidcarlisle]

@niruvt

There is no indication that math mode has started when the text is n^p=n

Not announcing math is normal (although actually MathCat has an option to beep when entering math if the listener wants that) but that is rather different to acronyms and abbreviations. $n^p=n$ just appears in one form to the sighted reader so reading it as n to the p equals n or similar is natural but (perhaps?) a reader may want to know that an abbreviation is being used here. To a sighted reader having PRS in the document is not the same experience as having "present tense" Depending on what users expect (and it's hard to know that without asking them) you may want the expansion to be something like prs, present tense not just present tense even if that isn't how you would read it conventionally. Using a macro such as Ulrike just showed it would be easy to adjust to have a version which used #1 and #2 in the E value, if that were ever needed, without having to change the markup in the document.

[niruvt]

Got it. I think I can provide several options like that. E.g., if option abcd used, then you will just hear 'prs'. If option efgh used, then 'present tense' and if ijkl used, then prs, present tense. The definition itself can be flexible depending on the conditional used. I will talk to connect with some people from the community as well.

[niruvt]

I wanted to provide support for tagging IPA. I looked at PDF 2.0 and found the PhoneticAlphabet and Phoneme keys (see 14.9.6 and table 354). The documentation of tagpdf package mentions that it has phoneme key for this purpose. I made a small non-working example. It produces a fatal error. The example is based on the code provided by you two, but I don’t understand the details of these keys and I think that’s why something is failing. Have a look at this:

\DocumentMetadata{tagging=on,lang={en-GB}}
\documentclass{article}

\ExplSyntaxOn
\socket_new:nn { tagsupport / lngx / phoneme } { 2 }
\socket_new_plug:nnn { tagsupport / lngx / phoneme }
                     { default } {
  \mode_leave_vertical:
  \tag_mc_end:
  \tag_struct_begin:n {
    tag                    = { Span },
    phoneme                = { #1 }
  }
  \tag_mc_begin:n {
    tag                    = { Span }
  }
  #2
  \tag_mc_end:
  \tag_struct_end:
  \tag_mc_begin:n { }
}

\msg_new:nnn { linguistix } { phoneme } {
  No~ pronunciation~ hint~ given~ for:\\ /#1/.
}

\NewDocumentCommand \phonetic { o m } {
  \IfValueTF { #1 } {
    \socket_use:nnn { tagsupport / lngx / phoneme }
                    { #1 }
                    { #2 }
  } {
    \msg_warning:nnn { linguistix } { phoneme } { #2 }
    #2
  }
}
\ExplSyntaxOff

\begin{document}
\phonetic[pee kaa choo]{pikachu}
\end{document}

So the first priority would be to fix this, but that’s not it. The next question is where should this key be used exactly? Does the implementation look correct as it is now? I have a command \ipatext in my package and if I understand correctly, phoneme tag can be added to the argument of it, but I am not sure. What are your views? There is another tagging-philosophical-question.

I thought about it because a blind linguist told me that IPA is not read correctly. I was thinking if I can add a helping text to IPA for it to be read correctly. So, suppose I have /pikaʧu/ in IPA, I will provide an interface to add ‘pee kaa choo’ as a ‘pronunciation hint’ (as PDF 2.0 calls it). Just so that the reader reads it properly. I was thinking of ActualText in the beginning, but then I found phoneme. Now here is a dilemma. If I add it using the ActualText mechanism, probably many readers will read IPA better as there will be reading hints (provided they are provided, of course). If I just add the phoneme tag, it will just be marked that it is in IPA without it actually being able to read the text.

I read some discussions around tagging complexities and I have seen that the team prefers to adhere to the standard and hopes for improvements in the reading software. My personal preference also is the same. In that case, I lean more towards phoneme tag (which, as Ulrike mentions, is not used in most PDF readers). What should I do? (Sounds very unlikely, but still asking) can I add ActualText along with phoneme?

[davidcarlisle]

I don't think you want ActualText here as ActualText essentially is the text used in accessibility, and cut and paste and other uses, so it essentially totally masks the IPA string except for the typeset content. Phoneme could be used to give a pronunciation hint, but my understanding is that you would use IPA in that attribute, so so using it to give pronunciation hints for IPA is a bit backwards.

I'm most familiar with nvda and certainly there users can give speech dictionaries to improve reading of certain characters, that's needed for some math characters.

But this response is all a bit theoretical so I don't have much experience with the phoneme key in practice.

[niruvt]

[...] so using it to give pronunciation hints for IPA is a bit backwards.

You are correct. That's why even I was confused about the phoneme key.

I'm most familiar with nvda and certainly there users can give speech dictionaries to improve reading of certain characters, that's needed for some math characters.

Okay, so in your opinion, the IPA should be left blank and the reading support for them as Unicode characters should improve, right?

[u-fischer]

You are missing the assigning command
\AssignTaggingSocketPlug{lngx/phoneme}{default} .

Also it is better to use this to declare tagging sockets as it take care of some of the special conventions there.

\NewTaggingSocket { lngx / phoneme } { 2 }
\NewTaggingSocketPlug {lngx / phoneme } {...]

We can not really say something about how to use the phoneme key: it is mentioned in the spec but imho nobody has implemented support for it.

[niruvt]

You are missing the assigning command

Ahh, yes!

Thanks, I have added it now.

Also it is better to use this to declare tagging sockets as it take care of some of the special conventions there.

I wanted to use expl3 wherever possible, there is no expl3 equivalent for this, right? I thought adding tagsupport takes care of everything.

We can not really say something about how to use the phoneme key: it is mentioned in the spec but imho nobody has implemented support for it.

Okay, but as David points out, probably it is best not to use it for IPA at least.

[niruvt]

Didn't know that \tag_socket_use:n also existed. Found it in tagpdf-user.dtx. I don't see any generated PDF of this dtx. Maybe this should go to the main user documentation.

[u-fischer]

\tag_socket_use:n is documented in source2e, lttagging.

[davidcarlisle]

There is a thread on improving NVDA's IPA readings here

https://nvda.groups.io/g/nvda/topic/nvda_reading_and_writing_ipa/105052577

not exactly conclusive other than it's a known issue and it's possible to address things at the screen reader end rather than at the pdf generation side.

[niruvt]

@FrankMittelbach I get it. I have found some linguists already. I have created a mailing list. There is some participation already. I wanted more people, I will maybe ask someone to post a public request at the Facebook group you suggest. I don't (intend to) use Facebook myself. I posted a request at linguistlist which is a well established public mailing list of linguistics. Got some people from there. (Would be very nice if you all join too).

Anyway, why I asked you is not to get a ready-to-use solution. I will of course run it through blind linguists I have managed to find, but meanwhile I had to know if it is according to PDF standards. For that, the project team is so far the best place I know. That's why I asked here. Can you elaborate on why you think alternative text doesn't fit the bill (theoretically)?

[niruvt]

@FrankMittelbach PDF 2.0 says:

PDF documents may be enhanced by providing alternate descriptions for images, formulas, or other items that do not translate naturally into text.

Can't IPA fit into "other things that don't translate naturally into text"?

[FrankMittelbach]

maybe ,but I think it does naturally translates to text (or language) only that it got messed up in Unicode somewhat. It is a bit like mathematics, where people initially thought the way to go it to provide alternative text for each and every formula snippet, which is not usable in reality. But it might be the best you can do right now.

[u-fischer]

You can read the PDF standards yourself, they are available at no cost from the PDF association. But you will see that they do not say much about this use case -- you (the linguists) will have to figure out yourself what is the "best" (with a suitable definition of "best") . Start with html -- if you have a good working solution there it will be easier to figure out what should be done in PDF. (The most logical markup imho would be to use the /Lang key, e.g. /Lang (de-fonipa) but I do not know if any setup would make use of it, so while it may be theoretically the "best", practically it is probably not. )

[niruvt]

@FrankMittelbach

maybe ,but I think it does naturally translates to text (or language) only that it got messed up in Unicode somewhat. It is a bit like mathematics, where people initially thought the way to go it to provide alternative text for each and every formula snippet, which is not usable in reality. But it might be the best you can do right now.

Thanks for these valuable insights. I will check with the people I know and make a decision.

@u-fischer

You can read the PDF standards yourself, they are available at no cost from the PDF association.

Of course. I found many pointers regarding the PDF keys from the standard itself. Why I asked here is because the team has a prior experience and valuable insights. Also, if I understand correctly, if tagging is mishandled by add-on packages like mine, it can affect the overall tagging quality of the document. Thus I thought talking to the team could be helpful. That's the only reason why I asked. I will see if there are standard practices in HTML. Thanks.