Support page number alias substitution with bidi / RTL text shaping

[andersonhc]

PR #1894 added initial support for page-count alias substitution ({nb} / alias_nb_pages()) when text shaping is enabled.

There is still a remaining compatibility gap with bidirectional and RTL text. When the alias appears inside text processed by the bidi pipeline, it can be reordered as normal text before alias substitution runs. For example, {nb} may become }nb{, so the alias is no longer recognized and is rendered literally instead of being replaced by the total page count.

Example:

from fpdf import FPDF

pdf = FPDF()
pdf.add_font("SBL_Hbrw", fname="test/text_shaping/SBL_Hbrw.ttf")
pdf.set_font("SBL_Hbrw", size=18)
pdf.set_text_shaping(True, direction="rtl")

pdf.add_page()
pdf.cell(text="אבג {nb} דהו")

pdf.output("rtl-nb-alias.pdf")

The {nb} alias should be replaced by the total page count, consistently with LTR shaped text and regular non-shaped text, but right now the alias can be reordered by bidi processing and emitted literally, so the generated PDF may contain the alias text instead of the page count.

We likely need to detect page-count aliases before bidi reordering and preserve them as special atomic / unbreakable fragments. This may require changes in bidi.py or in the preprocessing path that creates bidi fragments, so aliases are not treated as ordinary reorderable text.

[prateek-dagar]

Hi @andersonhc , I’ve outlined a few possible solutions above. Let me know which one you think would be best, or if you have another approach in mind. I’d be happy to work on it.

Proposed Solutions

Option A: PUA Character Placeholder

Replace each alias with a single Private Use Area (PUA) character (e.g. \uE000) before running the bidi algorithm. If necessary, scan the input and select an unused PUA codepoint.

• Pros: Preserves the full paragraph context, allowing correct bidi level resolution and shaping. Simple to implement.
• Cons: Theoretical collision risk with existing PUA characters, mitigated by selecting an unused codepoint.

Option B: Segment Splitting

Split the text at alias boundaries, run the Unicode Bidirectional Algorithm on each segment independently, and insert placeholder fragments between them.

• Pros: Completely avoids character-collision issues.
• Cons: Breaks bidi rendering context. Text on either side of an alias can no longer interact, which may produce incorrect bidi levels or shaping.

Option C: Add a protected_sequences Parameter to BidiParagraph

Move Option A's PUA substitution logic into bidi.py rather than handling it in fpdf.py.

• Pros: Keeps the caller code in fpdf.py simpler.
• Cons: Introduces an application-level concept (protected strings) into a module that otherwise implements the bidi specification.

[andersonhc]

At first glance, Option A seems like a good approach because it limits the impact on the bidi algorithm. We could use a sequence of PUA characters that is highly unlikely to occur naturally, avoiding the additional preprocessing required to search for unused code points.
If you find a better alternative or prefer one of the other options, I’m open to evaluating it.