Files
Krushil DhankechaandCesar Berrospi Ramis 18e6be77e0 fix(webvtt): parse cue ruby spans instead of dropping their cues (#935)
* fix(webvtt): parse cue ruby spans instead of dropping their cues

A cue holding a <ruby> annotation was dropped as a whole: the
unknown-tag pass kept ruby and rt tags, the text-span validator then
rejected the leftover "<", and WebVTTFile.parse lost the cue with only
a RuntimeWarning (#934).

Model the WebVTT cue ruby span and cue ruby text span (WebVTT 1, 4.2.2)
as cue components. An open <rt> is closed implicitly by the next <rt>
or by </ruby>, since the end tag of the last ruby text span may be
omitted; serialization always writes it back out.

Signed-off-by: krushil dhankecha <dhankechakrushil@gmail.com>

* fix(webvtt): follow the spec for <rt> tags and export ruby spans

Follow the WebVTT cue text parsing rules (WebVTT 1, 6.4) for ruby text
spans. An <rt> start tag only applies when the innermost open span is a
<ruby>; otherwise it is ignored, and so is an </rt> end tag when no <rt>
is open. As a result, an <rt> inside an open <rt> no longer closes it
and starts a sibling (the text is kept in the open span), and an <rt>
outside a <ruby> no longer produces a cue ruby text span. The implicit
close of the last <rt> by </ruby> is unchanged, and the guard that
protected it from an empty tag stack is no longer needed.

Export WebVTTCueRubySpan and WebVTTCueRubyTextSpan from
docling_core.types.doc, like the other cue components.

Add webvtt_example_05.vtt, a file with ruby spans, and tests for it and
for the <rt> handling above.

Signed-off-by: Cesar Berrospi Ramis <ceb@zurich.ibm.com>

* refactor(webvtt): derive cue tag names from START_TAG_NAMES

Use START_TAG_NAMES as the single list of cue span tag names. The cue
component kind is typed with it and the cue tag pattern is built from
its values, so adding a tag no longer requires keeping several copies
in sync.

In WebVTTCueBlock.parse, close spans through _close_top_span in the
end-tag branch and in the final loop that closes the remaining open
spans, and drop the membership check on the tag name, which always
holds because the tag pattern only matches known tags. Behaviour is
unchanged.

Signed-off-by: Cesar Berrospi Ramis <ceb@zurich.ibm.com>

---------

Signed-off-by: krushil dhankecha <dhankechakrushil@gmail.com>
Signed-off-by: Cesar Berrospi Ramis <ceb@zurich.ibm.com>
Co-authored-by: Cesar Berrospi Ramis <ceb@zurich.ibm.com>
2026-11-13 16:04:36 +01:00
..