References notes and floats/Registers and index/How-to guides/Typesetting bidirectional registers

Indexes and registers in ConTeXt  ·  Overview  ·  Tutorial  ·  How-to guides  ·  Previous: Sorting multilingual registers  ·  Typesetting bidirectional registers  ·  Next: Managing structured register data

🚧 This page is under construction. Feel free to correct, expand, and improve it; its structure and examples may still change.

1. Goal

Use this guide when an index or named register contains Arabic, Hebrew, or other right-to-left material.

By the end of the guide, you will be able to:

• select a font with the required script support;
• enable bidirectional processing;
• distinguish sorting language from writing direction;
• align right-to-left register entries correctly;
• keep page references readable;
• control the physical order of multiple columns;
• test mixed left-to-right and right-to-left entries with the current ConTeXt version.

Four separate decisions

A bidirectional register involves at least four distinct decisions:

1. which language or key controls sorting;
2. which font and OpenType script shape the characters;
3. which direction controls each paragraph or entry;
4. which direction controls the physical order of columns.

Changing one of these does not necessarily change the others.

2. Before you begin

You should already know how to:

• create and place an ordinary register;
• assign explicit sorting keys;
• configure a register language and sorting method.

See:

• Sorting multilingual registers;
• Formatting an index.

Use UTF-8 source files.

Make sure that the selected font contains the Arabic or Hebrew glyphs required by the document and supports the appropriate OpenType script.

3. Enable bidirectional processing

A practical starting point for current ConTeXt LMTX is:

\setupdirections
  [bidi=global,
   method=unicode]

This enables Unicode-aware bidirectional processing throughout the document.

Paragraph direction can then be selected with commands such as:

\righttoleft

and:

\lefttoright

For paragraph-level alignment, use:

\setupalign[r2l]

or an explicit alignment list such as:

\setupalign
  [r2l,right]

Direction and alignment are not identical

A bare right-to-left direction setting changes writing direction, but it does not always provide the paragraph alignment or line-breaking behaviour required by the layout.

When text is placed in constrained areas such as table cells, framed text, or columns, combine direction with an explicit alignment setting and test the result.

4. Select script-aware fonts

The font setup must activate the required script.

A simple Hebrew setup may use:

\definefontfeature
  [hebrew]
  [default]
  [script=hebr]

\definefontfamily
  [mainface]
  [serif]
  [Noto Serif Hebrew]
  [features=hebrew]

\setupbodyfont
  [mainface,11pt]

A simple Arabic setup may use:

\definefontfeature
  [arabic]
  [default]
  [script=arab]

\definefontfamily
  [mainface]
  [serif]
  [Noto Naskh Arabic]
  [features=arabic]

\setupbodyfont
  [mainface,11pt]

Font names depend on the fonts installed on the system or server.

Test the actual publication font

A register is a poor place to discover missing glyphs or incomplete shaping.

Before indexing a full document, test:

• isolated letters;
• words containing contextual forms;
• diacritics;
• punctuation;
• numerals;
• mixed Latin and right-to-left text.

5. Create a simple Hebrew register

The following MWE creates a one-column Hebrew index whose entries are displayed right to left.

Explicit Latin sorting keys are used so that the example has a predictable editorial order independent of Hebrew collation.

\setuppapersize[A6]

\definefontfeature
  [hebrew]
  [default]
  [script=hebr]

\definefontfamily
  [mainface]
  [serif]
  [Noto Serif Hebrew]
  [features=hebrew]

\setupbodyfont
  [mainface,11pt]

\setupdirections
  [bidi=global,
   method=unicode]

\setupregister
  [index]
  [n=1,
   indicator=no]

\starttext

\lefttoright
The text discusses wisdom
\index[hokhmah]{\righttoleft חָכְמָה}
and justice
\index[tsedeq]{\righttoleft צֶדֶק}.

It also mentions peace
\index[shalom]{\righttoleft שָׁלוֹם}.

\subject{Index}

\righttoleft
\placeindex

\stoptext

Simple Hebrew register with right-to-left entries and Latin sorting keys.

In this example:

• the running prose is left to right;
• the Hebrew forms are displayed in the register;
• Latin sorting keys determine the order;
• the placed register is switched to right-to-left direction.

Why use explicit Latin keys here?

The purpose of this MWE is to isolate typesetting direction from language-sensitive sorting.

A production Hebrew index may instead use Hebrew collation, but that sorting policy must be tested separately with representative data.

6. Create a simple Arabic register

The same strategy can be used for Arabic.

\setuppapersize[A6]

\definefontfeature
  [arabic]
  [default]
  [script=arab]

\definefontfamily
  [mainface]
  [serif]
  [Noto Naskh Arabic]
  [features=arabic]

\setupbodyfont
  [mainface,12pt]

\setupdirections
  [bidi=global,
   method=unicode]

\setupregister
  [index]
  [n=1,
   indicator=no]

\starttext

\lefttoright
The text discusses wisdom
\index[hikma]{\righttoleft الحكمة}
and justice
\index[adl]{\righttoleft العدل}.

It also mentions peace
\index[salam]{\righttoleft السلام}.

\subject{Index}

\righttoleft
\placeindex

\stoptext

Simple Arabic register with right-to-left entries and Latin sorting keys.

Again, the displayed Arabic entry and the sorting form are separate.

7. Keep entry direction local when the document is mixed

Do not switch the entire document to right-to-left direction when only some entries require it.

Prefer local direction commands inside the displayed form:

\index[Plato]{Plato}

\index[aflatun]{\righttoleft أفلاطون}

\index[platon-hebrew]{\righttoleft אפלטון}

This allows one register to contain Latin, Arabic, and Hebrew forms.

However, a mixed register still requires an explicit editorial sorting policy.

For example:

• use one transliteration system for all non-Latin entries;
• create separate named registers for each script;
• use one dominant language and explicit keys for exceptions.

Do not confuse visual order with editorial order

Bidirectional processing determines how characters and runs are displayed.

Sorting keys determine where entries appear in the register.

A visually correct Arabic or Hebrew entry can still appear in the wrong alphabetical position if its sorting policy has not been defined.

8. Control punctuation and page references

A typical register entry combines:

• right-to-left entry text;
• punctuation or a separator;
• left-to-right Arabic numerals used as page references.

This is a bidirectional boundary and should be inspected carefully.

Test at least:

• one single page number;
• several page numbers;
• an explicit page range;
• punctuation inside the displayed entry;
• parentheses and dashes;
• entries containing embedded Latin text.

A diagnostic example may include:

\index[shalom]{\righttoleft שָׁלוֹם}

\index[hikma]{\righttoleft الحكمة}

\index[plato-arabic]
  {\righttoleft أفلاطون\lefttoright\space (Plato)}

If punctuation appears on the wrong side, isolate the left-to-right and right-to-left runs explicitly rather than relying on surrounding context alone.

Use a diagnostic page

Before processing a complete book, prepare one test page containing every difficult combination used by the publication.

A correct single word does not prove that page references, ranges, punctuation, and embedded Latin text will also behave correctly.

9. Align entries in constrained layouts

Right-to-left text inside tables, frames, or narrow columns may require both direction and alignment.

For example, a right-to-left table column may use:

\setupTABLE
  [column]
  [2]
  [align={r2l,right}]

The same principle applies to any constrained register layout:

• set the writing direction;
• set the paragraph alignment;
• use an appropriate tolerance where line breaking is difficult;
• test the actual column width.

Avoid assuming that r2l alone controls every aspect of alignment.

10. Control the order of multiple columns

Right-to-left entry direction does not automatically reverse the physical order in which multiple register columns are filled or displayed.

A multi-column register may therefore require an explicit mixed-column setup.

For example:

\setupmixedcolumns
  [register]
  [direction=reverse]

Then configure the register to use the intended number of columns:

\setupregister
  [index]
  [n=2]

Test column order with numbered markers

To verify the physical order of columns, use temporary entries whose intended sequence is obvious.

Do not judge column order only from alphabetic entries, because an unexpected sorting result can be mistaken for a column-direction problem.

Because mixed-column behaviour can depend on the current implementation and layout, test direction=reverse with the exact ConTeXt version used for publication.

11. Decide between one mixed register and several registers

Use one mixed register when:

• readers expect one combined navigational list;
• one common sorting-key system has been defined;
• script changes remain readable;
• indicators and page references remain unambiguous.

Use separate named registers when:

• each script follows its own alphabet;
• different fonts or paragraph directions require distinct setups;
• different audiences will consult different lists;
• a combined register would obscure the editorial order.

For example:

\defineregister[arabicterms]
\defineregister[hebrewterms]

\arabicterms[hikma]{\righttoleft الحكمة}
\hebrewterms[hokhmah]{\righttoleft חָכְמָה}

\righttoleft
\placearabicterms

\placehebrewterms

Separate registers can also be configured independently for language, method, heading, and number of columns.

12. Troubleshooting

Problem	Likely cause	What to check
Arabic letters do not join correctly	The font feature does not activate the Arabic script, or the font lacks adequate support	Check the font, script=arab, and the actual font name
Hebrew diacritics or letters are missing	The selected font lacks the required glyphs or marks	Test the complete character set with the publication font
Entry text is right to left but aligned on the wrong side	Direction was set without explicit paragraph alignment	Combine r2l with an appropriate alignment setting
Page numbers or punctuation appear on the wrong side	Mixed directional runs are not isolated clearly	Add explicit \lefttoright and \righttoleft boundaries
Entries are visually correct but alphabetically misplaced	The sorting language or explicit key is wrong	Review language, method, and sorting keys
Two-column output fills columns in the wrong physical order	Entry direction and column order were treated as one setting	Test a mixed-column setup with direction=reverse
A test works in ordinary paragraphs but fails in a table or frame	The constrained layout requires its own direction and alignment settings	Configure the cell or frame explicitly and test line breaking

13. What this guide has established

This guide has shown that:

1. sorting language and writing direction are separate;
2. bidirectional processing should be enabled explicitly;
3. fonts must activate the appropriate Arabic or Hebrew OpenType script;
4. right-to-left entries can use left-to-right sorting keys;
5. mixed registers require local direction control and an explicit editorial order;
6. punctuation and page references create bidirectional boundaries that must be tested;
7. right-to-left direction and paragraph alignment are distinct;
8. right-to-left entry direction and physical column order are also distinct;
9. constrained layouts may require their own direction and alignment settings;
10. bidirectional registers should be tested with the current ConTeXt version and the exact publication fonts.

The central rule is: configure sorting, shaping, paragraph direction, and column order as separate parts of one coordinated layout.

14. Next step

If register entries are generated from XML, Lua, a database, or another structured source, continue with:

• Managing structured register data.

That guide treats:

• structured entry fields;
• displayed forms and sorting keys;
• processors and userdata;
• generated entries;
• validation before placement.

Indexes and registers in ConTeXt  ·  Overview  ·  Tutorial  ·  How-to guides  ·  Previous: Sorting multilingual registers  ·  Typesetting bidirectional registers  ·  Next: Managing structured register data