% !TeX program = lualatex \documentclass{ltxdoc} \usepackage{minted} \usepackage[arabic,persian,english]{babelbidi} \babelprovide[import , mapdigits ,onchar = ids fonts letters]{arabic} \babelprovide[import,,onchar=ids fonts letters]{persian} \babelprovide[import,main,onchar=ids fonts letters]{english} \babelfont{rm}[english]{Times New Roman} \babelfont{tt}[english]{JetBrains Mono} \babelfont{rm}[arabic]{Amiri} \babelfont{rm}[persian]{Vazirmatn} \babelfont{tt}[persian]{Vazir Code} \babelfont{tt}[arabic]{Kawkab Mono} % Hasubi Mono % Kawkab Mono \usepackage{pkgmeta} \usepackage{datemultical} \dmcset{babelbidi}{\pkgmeta[year]{babelbidi}}{\pkgmeta[month]{babelbidi}}{\pkgmeta[day]{babelbidi}} \usepackage[svgnames]{xcolor} \usepackage{booktabs} \usepackage{hyperref} \setminted{ breaklines=true, % breakanywhere=true, escapeinside=|| } \setminted[latex]{bgcolor=Gold, bgcolorpadding=0.5em} \setminted[bash]{bgcolor=Gainsboro} \hypersetup{ colorlinks=true, linkcolor=blue, urlcolor=blue } \title{The \textsf{babelbidi} Package} \author{Amer Amikhteh} \date{% Version \pkgmeta[version]{babelbidi}\\[2pt] \dmc{babelbidi}{long} } \begin{document} \maketitle \begin{abstract} \textsf{babelbidi} extends Babel's bidirectional support by fixing direction-sensitive behaviour and providing interfaces for explicit text direction, language selection, and font configuration, including glyph fallback with Lua\TeX. It supports languages available through Babel and works with \LuaTeX~(recommended), Xe\TeX, or pdf\TeX, with either an LTR or RTL main language. \end{abstract} \section{Introduction} Babel provides the infrastructure for typesetting documents containing both left-to-right (LTR) and right-to-left (RTL) languages. Some layout components, however, do not always behave correctly in RTL contexts, and Babel does not provide all the basic direction interfaces that may be useful in a document. \textsf{babelbidi} addresses these gaps in two ways: \begin{enumerate} \item it patches direction-sensitive layout behaviour \item and provides a small set of bidi and language-selection APIs. \end{enumerate} Most layout patches concern Lua\LaTeX. For documents whose main language does not use the Latin script, code-related direction handling is provided with Lua\LaTeX, Xe\LaTeX, and pdf\LaTeX. The basic direction commands follow interfaces found in bidi implementations such as \textsf{luabidi}. The commands \verb|\lr|, \verb|\rl|, and the \texttt{latin} environment are inspired in part by interfaces familiar to users of \textsf{xepersian}. \section{Obtaining and Installing} The official version of the \texttt{babelbidi} package is available from CTAN: \begin{center} \url{https://ctan.org/pkg/babelbidi} \end{center} Once the \TeX{} Live package database has been updated, the package can be installed with the following command: \begin{minted}{bash} tlmgr install babelbidi \end{minted} \section{Loading} The package is loaded as follows: \begin{minted}{latex} \usepackage[]{babelbidi} \end{minted} The package accepts options for both Babel and \textsf{babelbidi}. Options not defined by \textsf{babelbidi} are passed to Babel. The \texttt{bidi} and \texttt{layout} options are Babel options for which \textsf{babelbidi} provides engine-dependent defaults. If \texttt{bidi} is not specified, \textsf{babelbidi} selects its default value according to the engine: \begin{center} \begin{tabular}{ll} \toprule Engine & Default value of \texttt{bidi} \\ \midrule Lua\TeX & \texttt{basic} \\ Xe\TeX & \texttt{bidi-r} \\ Pdf\TeX & \texttt{default} \\ \bottomrule \end{tabular} \end{center} With \LuaTeX, \textsf{babelbidi} selects the following default value for \texttt{layout}: \begin{minted}{latex} counters graphics footnotes lists \end{minted} Specifying \texttt{layout} replaces this default; it does not add to it. For example: \begin{minted}{latex} layout={counters footnotes} \end{minted} This selects only \texttt{counters} and \texttt{footnotes} for the \texttt{layout} option. To retain \texttt{graphics} and \texttt{lists}, include them explicitly in the value. When the value contains multiple selectors, the value must be enclosed in \textbf{braces}. For best results, consider the following recommendations: \begin{enumerate} \item For slides with an RTL main language, \textsf{beamer-rl} is recommended over \textsf{beamer}, though it is not required. \item Lua\LaTeX~is recommended for its broader capabilities and Lua\footnote{Lua is a lightweight programming language designed to be embedded in applications.} extensibility. Separately, Babel's \texttt{onchar} option can automatically select a language based on the characters in the text. For Arabic: \begin{minted}{latex} \babelprovide[import, mapdigits, onchar=ids fonts letters]{arabic} \end{minted} Punctuation such as parentheses may still require explicit language selection. \end{enumerate} With \LuaTeX, the \texttt{fontcache} option controls caching of font mappings used by Babel's \texttt{onchar=fonts} option. It is a boolean option and is enabled by default to improve compilation speed. In special cases, such as font changes made through the \texttt{rmfamily} hook, cached mappings may prevent these changes from taking effect. The cache can be disabled when necessary: \begin{minted}{latex} \usepackage[fontcache=false]{babelbidi} \end{minted} \section{Font fallback} With Lua\LaTeX, \textsf{babelbidi} can use fonts from other Babel languages when the current font lacks a required glyph. Declare an ordered fallback chain in the preamble: \begin{minted}{latex} \fontfallback{english}{persian,greek} \end{minted} The source and candidate languages must be known to Babel. They can be specified as package options or loaded explicitly with \verb|\babelprovide|. Their fonts must be declared with \verb|\babelfont|. Candidates are tried in order, while the text language, direction, font family, series, shape, and size are preserved. Fallback applies to text fonts, including custom families, but not to math fonts. It works with or without \texttt{onchar=fonts} and also uses the \texttt{fontcache} setting. A later declaration replaces the previous chain; an empty candidate list disables fallback: \begin{minted}{latex} \fontfallback{english}{} \end{minted} Unknown languages, repeated candidates, and self-references are ignored with a warning where appropriate. Fallback is not recursive and is applied per glyph before shaping. It is available only with Lua\LaTeX; Xe\LaTeX~and pdf\LaTeX~warn and ignore explicit fallback declarations. \section{Direction and Language APIs} \textsf{babelbidi} provides commands, environments, and package options for controlling text direction, selecting languages, and setting fonts. \subsection{Font Selection} When running under Xe\LaTeX~or Lua\LaTeX, \textsf{babelbidi} provides the following commands: \begin{itemize} \item \cmd{\settextfont}\oarg{options}\marg{font}: Sets the \texttt{rm}, \texttt{sf}, and \texttt{tt} fonts for the main language. \item \cmd{\setlatintextfont}\oarg{options}\marg{font}: Sets the \texttt{rm}, \texttt{sf}, and \texttt{tt} fonts for the selected Latin language. \item \cmd{\deflatinfont}\marg{command}\oarg{options}\marg{font}: Defines a Latin font family command. \item \cmd{\setlatinsansfont}\oarg{options}\marg{font}: Sets the sans-serif font for the selected Latin language. \item \cmd{\setlatinmonofont}\oarg{options}\marg{font}: Sets the monospaced font for the selected Latin language and configures it for use by \cmd{\latinttfamily}. \end{itemize} \subsection{Commands} \begin{center} \begin{tabular}{@{}ll@{}} \toprule Command & Description \\ \midrule \verb|\LRE| & Typesets its argument from left to right \\ \verb|\RLE| & Typesets its argument from right to left \\ \verb|\LR| & Alias for \verb|\LRE| \\ \verb|\RL| & Alias for \verb|\RLE| \\ \verb|\lr| & Typesets its argument in the selected left-to-right language \\ \verb|\rl| & Typesets its argument in the selected right-to-left language \\ \verb|\latintoday| & Prints today's date in the selected Latin language \\ \verb|\latinttfamily| & Selects the configured Latin monospaced font family \\ \bottomrule \end{tabular} \end{center} \subsection{Environments} \begin{center} \begin{tabular}{@{}ll@{}} \toprule Environment & Description \\ \midrule \texttt{RTL} & Typesets its contents from right to left \\ \texttt{LTR} & Typesets its contents from left to right \\ \texttt{latin} & Typesets its contents in the selected Latin language \\ \bottomrule \end{tabular} \end{center} \subsection{Language Selection} \label{sec:language-selection} The following package keys select the languages used for Latin text, directional text, and code-related material: \begin{center} \begin{tabular}{@{}ll@{}} \toprule Key & Used for \\ \midrule \texttt{latin} & The \texttt{latin} environment and Latin font commands \\ \texttt{ltr} & The \verb|\lr| command \\ \texttt{rtl} & The \verb|\rl| command \\ \texttt{code} & Code-related material \\ \bottomrule \end{tabular} \end{center} For example: \begin{minted}{latex} \usepackage[code=dutch,rtl=arabic]{babelbidi} \end{minted} Unless specified explicitly, the values of these keys are selected automatically and updated after each \verb|\babelprovide| call. Explicit values remain unchanged. The automatic selections are determined as follows: \begin{description} \item[\texttt{latin}:] The main language if it uses the Latin script; otherwise, the first loaded Latin-script language; otherwise, \texttt{english}. \item[\texttt{ltr}:] The main language if it is left to right; otherwise, the first loaded left-to-right language; otherwise, \texttt{english}. \item[\texttt{rtl}:] The main language if it is right to left; otherwise, the first loaded right-to-left language; otherwise, \texttt{arabic}. \item[\texttt{code}:] The main Latin-script language, if available; otherwise, \texttt{english}, if loaded; otherwise, the first loaded Latin-script language; otherwise, the main or first loaded left-to-right language; finally, the main language. \end{description} Languages should be declared before their fonts are configured. \section{Patches} The package applies the following patches automatically when the corresponding engine or package is in use. \begin{enumerate} \item \textbf{Common patches} \begin{enumerate} \item Code language selection: when the main language does not use the Latin script, the code-related patches use the language selected by the \texttt{code} key. These patches cover the \texttt{verbatim} environment, the \textsf{listings} package, and the \textsf{minted} environment and inline command. Documents with a Latin-script main language do not need these patches. \item \texttt{\string\label}: prevents errors caused by Babel's direction commands in label keys derived from enumeration counters. \end{enumerate} \item \textbf{Xe\LaTeX~patches} \begin{enumerate} \item \textsf{natbib}: corrects citation links in RTL text with recent \textsf{hyperref} versions. \item \textsf{fontspec}: disables its math-mode handling when Babel bidi mode is active. \end{enumerate} \item \textbf{Lua\LaTeX~patches} \begin{enumerate} \item \texttt{\string\makebox} and tables: adjust the positions of \texttt{l} and \texttt{r} material and swap table-column alignment in RTL text. \item Footnotes: adjust footnote paragraph direction in RTL contexts; footnotes issued in math mode in RTL-main documents are treated as RTL. \item TikZ: use LTR paragraph direction inside \texttt{tikzpicture}, except with \textsf{beamer-rl}. \item \textsf{fancyhdr}: increase the head height and typeset headers and footers in LTR direction. \item \textsf{beamer}: correct the layout of rounded boxes, except when \textsf{beamer-rl} is loaded. \end{enumerate} \item \textbf{RTL-main footnote-rule patch} \begin{enumerate} \item With Xe\LaTeX~and Lua\LaTeX, typeset the footnote rule in a stable LTR direction when the main language is RTL. \end{enumerate} \end{enumerate} \section{Minted} BabelBidi supports the \textsf{minted} package: \begin{minted}{latex} \usepackage{minted} \end{minted} The \texttt{textlang} option selects a Babel language already declared with \verb|\babelprovide| or loaded as a Babel package option: \begin{minted}{latex} \begin{minted}[textlang=persian]{latex} متن فارسی \end{min||ted} \end{minted} It can also be set with \verb|\setminted|: \begin{minted}{latex} \setminted{textlang=persian} \end{minted} The \texttt{textdir} option sets the code direction: \texttt{rtl} (right-to-left) or \texttt{ltr} (left-to-right). \sloppy With Lua\LaTeX, \texttt{chardir} uses Babel's \verb|\babelcharproperty| to temporarily set character directions. It takes comma-separated \texttt{\{character\}\{direction\}} pairs. Direction values include \texttt{l}, \texttt{al}, \texttt{r}, \texttt{en}, \texttt{an}, \texttt{on}, \texttt{et}, and \texttt{cs}. Previous values are restored after the environment ends. This example sets right-to-left code with the backslash and closing brace assigned direction \texttt{l}: \begin{minted}[chardir={{.}{r}}]{latex} \begin{min||ted}[textdir=rtl, chardir={{\\}{l},{\}}{l}}]{latex} این روش در \lr{Chapter 2 (Examples)} توضیح داده شده است. \end{min||ted} \end{minted} With Lua\LaTeX, frames retain left-to-right geometry. Line numbers use Latin digits. \section{Current Limitations and Possible Directions} \begin{enumerate} \item \textbf{Incomplete API coverage.} Several APIs provided by \textsf{luabidi} are not yet defined by \textsf{babelbidi}. Extending this API coverage is a priority for the next release. \item \textbf{Limited compatibility testing.} The package has not been tested with every combination of document class and third-party package. Broader testing may help identify interactions that require further work. \end{enumerate} \section{License} The \texttt{BabelBidi} package is released under the \lr{\LaTeX~Project Public License (LPPL)}, version \lr{1.3c} or later. The full text of the license is available in the \texttt{LICENSE} file. \section{Author and Maintainer} The \texttt{babelbidi} package is developed and maintained by \textbf{Amer Amikhteh}. The project's source code, development versions, and issue tracker are available in the project repository: \begin{center} \url{https://github.com/gambi-shah/babelbidi} \end{center} \end{document}