Matterhorn 09-007 · PDF/UA-1 UA1:7.2-1

Ruby tags in PDF: RB, RT, RP and the order they go in

RB, RT or RP appears outside a Ruby element, or Ruby has an illegal child sequence.

What a screen reader actually does

Pronunciation annotations are announced inline as if they were body text.

What ruby is in the file

A ruby assembly is four structure types. Ruby is the wrapper; inside it, RB is the base text at full size and RT is the annotation in small type:

/Span
└── /Ruby
    ├── /RB   東京            the base text
    └── /RT   とうきょう       its reading, set small above it

When the annotation cannot be set as ruby and is printed as a bracketed comment instead, the brackets are tagged too:

/Ruby
├── /RB   東京
├── /RP   （
├── /RT   とうきょう
└── /RP   ）

Those are the only two shapes ISO 32000-1 allows. A Ruby holds one RB followed by either an RT, or the group RP, RT, RP — and a ruby assembly may not break across lines. RB and RT may hold text or other inline elements; RB may carry a RubyAlign attribute, and RT both RubyAlign and RubyPosition.

One detail about the reference. The protocol’s condition cites Table 338, which is where Ruby and Warichu appear among the inline structure types. The rules for what goes inside them are in the table that follows it — Table 339 in the 2008 text.

What goes wrong, and what is heard

An RT or RB outside a Ruby. The annotation is now an ordinary inline element. A reader meets the base and the reading run together — 東京とうきょう — or, in a romanised document, a word followed by its pronunciation guide as though both were the sentence.

Something other than RB, RT and RP inside the Ruby. A Span a tagger or an editor put there, for instance. Whatever it holds is part of neither the base nor the annotation.

The right types in the wrong order. An RT before its RB, an RB with nothing after it, or two RT elements. The reader meets the reading before the word, a word whose reading is missing, or two readings for one word.

In every case the loss is the same: nothing in the file still says which text is the word and which text explains it.

Where it comes from

A document whose ruby was tagged as a Span or a P — no ruby structure at all — does not fail this condition. It has the wrong type, which is a judgement, covered by 01-006.

This condition needs a document that uses the ruby types and gets them wrong. That can happen when a reading-order repair drags an RT out of its Ruby, when a converter emits the annotation before the base because it was painted first, and when someone builds the elements by hand and stops at RB.

How to check it free

There is no automated check to lean on. Acrobat’s Accessibility Checker has no rule for ruby in Adobe’s list of its rules, and veraPDF’s PDF/UA-1 profile has none either. (Adobe: Create and verify PDF accessibility; veraPDF PDF/UA-1 rules)

So read the tree. In Acrobat Pro, open the Tags panel (View → Show/Hide → Side Panels → Tags), expand each <Ruby>, and check three things: its children are only RB, RT and RP; the first is an RB; and what follows is either one RT or RP, RT, RP. Then look through the tree for RT and RB elements whose parent is not a Ruby.

How to fix it free, in Acrobat Pro

The Tags panel can do all of it, using the steps Adobe documents for creating, moving and retyping tags (Adobe: Edit document structure with the Content and Tags panels):

1. Select the element that should contain the assembly — usually the Span or P the base word sits in — choose New Tag from the Options menu and type Ruby as the type. Adobe’s list of standard tag types does not include the ruby types, and the dialog accepts a type typed in.
2. Select the base text on the page and choose Create Tag From Selection, typing RB. Do the same for the annotation, typing RT.
3. Drag both tags into the Ruby, RB first.
4. If the annotation is printed in brackets, tag each bracket RP the same way and place them either side of the RT.
5. Remove anything left empty with Delete Tag.

If the source application has a ruby feature and its export tags ruby, re-exporting is better than any of this. Check one exported assembly in the Tags panel before trusting the rest.

Where Taggart differs

Taggart reports two of the three failures:

<RT> appears inside <P> but the ruby structure grammar (ISO 32000-1, Table 338) requires it to be inside <Ruby>.

and

<Ruby> contains a <Span> child, which the ruby structure grammar (ISO 32000-1, Table 338) does not permit (allowed: <RB>, <RP>, <RT>).

It does not check the order or the count of a Ruby’s children. An RT before its RB, an RB with no RT, and two RT elements in one Ruby all pass. Read the order yourself, as above, even when Taggart reports nothing.

There is no repair. Each finding is a blocker with its page and structure path, and the restructuring is yours to do in the Tags panel or at the source.

How Taggart handles it

Taggart checks for the common form of this condition automatically and reports it as a blocker. The check does not cover every form of it; what it misses is described above.

Where this sits in the standards

Related conditions

• 09-008 A Warichu-related structure element does not conform to ISO 32000-1, Table 338WT or WP appears outside a Warichu element, or Warichu has an illegal child sequence.
• 09-002 Structure elements are nested in a semantically inappropriate mannerNesting that is syntactically legal but semantically nonsense — a Table inside an H2, a paragraph containing a section.
• 01-006 Structure type is not semantically appropriateThe tag does not match the nature of the content: a heading tagged as a paragraph, a data table tagged as a layout container, a caption tagged as body text. This is the judgment call that no validator can make for you.

Other conditions in checkpoint 09

Checkpoint 09 covers appropriate tags. These are its other failure conditions; the ones without a link are in the rule set but do not have a written page yet.

• 09-001 Tags are not in logical reading orderThe order of elements in the structure tree does not match the order a human would read the page. This is the single most common substantive defect in tagged PDFs and the one Acrobat's own tooling handles worst.
• 09-002 Structure elements are nested in a semantically inappropriate mannerNesting that is syntactically legal but semantically nonsense — a Table inside an H2, a paragraph containing a section.
• 09-003 Structure type is not semantically appropriate after role mappingOnce role mapping has been resolved, the effective type still does not describe the content.
• 09-004 A table-related structure element does not conform to ISO 32000-1, Table 337The table grammar is broken: a TD outside a TR, a TR outside Table/THead/TBody/TFoot, a Table with no rows, or rows that span different numbers of columns.
• 09-005 A list-related structure element does not conform to ISO 32000-1, Table 336The list grammar is broken: an LI outside an L, an Lbl or LBody outside an LI, a list item with no LBody.
• 09-006 A TOC-related structure element does not conform to ISO 32000-1, Table 333TOCI appears outside a TOC, or a TOC contains children other than TOC and TOCI.
• 09-008 A Warichu-related structure element does not conform to ISO 32000-1, Table 338WT or WP appears outside a Warichu element, or Warichu has an illegal child sequence.

Checked with Taggart on a generated file that fails this condition on 2026-10-02. The Acrobat steps follow Adobe’s documentation and were not walked through by hand. Last updated 2026-10-02.