diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/polyglossia/polyglossia.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/polyglossia/polyglossia.tex | 772 |
1 files changed, 772 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/polyglossia/polyglossia.tex b/Master/texmf-dist/doc/latex/polyglossia/polyglossia.tex new file mode 100644 index 00000000000..0e84fa1f184 --- /dev/null +++ b/Master/texmf-dist/doc/latex/polyglossia/polyglossia.tex @@ -0,0 +1,772 @@ +\documentclass[11pt]{ltxdoc} +\usepackage{color} +\usepackage{xspace,fancyvrb} +\usepackage[neverdecrease]{paralist} +\definecolor{myblue}{rgb}{0.02,0.04,0.48} +\definecolor{lightblue}{rgb}{0.61,.8,.8} +\definecolor{myred}{rgb}{0.65,0.04,0.07} +\usepackage[ + bookmarks=true, + colorlinks=true, + linkcolor=myblue, + urlcolor=myblue, + citecolor=myblue, + hyperindex=false, + hyperfootnotes=false, + pdftitle={Polyglossia: A Babel replacement for XeLaTeX and LuaLaTeX}, + pdfauthor={F Charette, A Reutenauer}, + pdfkeywords={xetex, xelatex, luatex, lualatex, multilingual, babel, hyphenation} + ]{hyperref} +\usepackage[babelshorthands]{polyglossia} +\usepackage{farsical} +\setmainlanguage[variant=british,ordinalmonthday=false]{english} +\setotherlanguages{arabic,hebrew,syriac,greek,russian,catalan} +\usepackage{metalogo} +\usepackage[protrusion]{microtype} +\newcommand*\Cmd[1]{\cmd{#1}\DescribeMacro{#1}\xspace} +\newcommand*\pkg[1]{\textsf{\color{myblue}#1}} +\newcommand*\file[1]{\texttt{\color{myblue}#1}} +\newcommand*\TR[1]{\textcolor{myred}{#1}} +\newcommand*\TX[1]{\hyperref[#1]{\textcolor{myred}{#1}}} +\newcommand*\TB[1]{\textcolor{myblue}{\bf #1}} +\newcommand*\link[1]{\href{#1}{#1}} +\def\eg{\textit{e.g.,}\xspace} +\def\ie{\textit{i.e.,}\xspace} +\def\ca{\textit{ca.}\@\xspace} +\def\Eg{\textit{E.g.,}\xspace} +\def\Ie{\textit{I.e.,}\xspace} +\def\etc{\@ifnextchar.{\textit{etc}}{\textit{etc.}\@\xspace}} + +%% Sidenotes << copied from fontspec.dtx +\newcommand\new[1]{% + \edef\thisversion{#1}% + \ifhmode\unskip~\fi{\ifx\thisversion\fileversion\color{blue}\else\color[gray]{0.5}\fi + $\leftarrow$}% + \marginpar{\centering + \small\ifx\thisversion\fileversion\color{blue}\else\color[gray]{0.5}\fi + \textsf{#1}}} +\newcommand\displaycmd[2]{% + \\\DescribeMacro{#2}\centerline{\cmd{#1}}} +\renewenvironment{itemize}{\begin{compactitem}[\char"2023]}%[{\fontspec{DejaVu Sans}\char"25BB}]}% + {\end{compactitem}} +\renewenvironment{enumerate}{\begin{compactenum}}{\end{compactenum}} + +%% fontspec declarations: +\setmainfont{Linux Libertine O} +\setsansfont{Linux Biolinum O} +\setmonofont[Scale=MatchLowercase]{DejaVu Sans Mono} +\newfontfamily\arabicfont[Script=Arabic]{Amiri} +\newfontfamily\syriacfont[Script=Syriac]{Serto Jerusalem} +\newfontfamily\hebrewfont[Script=Hebrew]{Ezra SIL} + +\linespread{1.05} +\frenchspacing +\EnableCrossrefs +\CodelineIndex +\RecordChanges +% COMMENT THE NEXT LINE TO INCLUDE THE CODE +\AtBeginDocument{\OnlyDescription} +\begin{document} +\GetFileInfo{polyglossia.sty} + +\title{\textcolor{lightblue}{\Huge\fontspec[Script=Greek,Language=Polytonic Greek,LetterSpace=40]{GFS Ambrosia} Πολυγλωσσια} +\\[16pt] +\color{myblue}Polyglossia: A Babel Replacement for \XeLaTeX\ and \LuaLaTeX} +\author{\scshape\color{myblue}François Charette\\\color{myblue}Current maintainer: \scshape Arthur Reutenauer} +\date{\filedate \qquad \fileversion\\ +\footnotesize (\textsc{pdf} file generated on \today)} + +\maketitle +\tableofcontents + + +\DeleteShortVerb{\|} +\MakeShortVerb{\¦} + +%\begin{abstract} +%Blablabla +%\end{abstract} + + +\section{Introduction} + +Polyglossia is a package for facilitating multilingual typesetting with +\XeLaTeX\ and (at an early stage) \LuaLaTeX. Basically, it +can be used as a replacement of \pkg{babel} for performing the following +tasks automatically: + +\begin{enumerate} +\item Loading the appropriate hyphenation patterns. +\item Setting the script and language tags of the current font (if possible and + available), via the package \pkg{fontspec}. +\item Switching to a font assigned by the user to a particular script or language. +\item Adjusting some typographical conventions according to the current language + (such as afterindent, frenchindent, spaces before or after punctuation marks, + etc.). +\item Redefining all document strings (like “chapter”, “figure”, “bibliography”). +\item Adapting the formatting of dates (for non-Gregorian calendars via external + packages bundled with polyglossia: currently the Hebrew, Islamic and Farsi + calendars are supported). +\item For languages that have their own numbering system, modifying the formatting + of numbers appropriately (this also includes redefining the alphabetic sequence + for non-Latin alphabets).\footnote{ % + For the Arabic script this is now done by the bundled package \pkg{arabicnumbers}.} +\item Ensuring proper directionality if the document contains languages + that are written from right to left (via the package \pkg{bidi}, + available separately). +\end{enumerate} + +Several features of \pkg{babel} that do not make sense in the \XeTeX\ world (like font +encodings, shorthands, etc.) are not supported. +Generally speaking, \pkg{polyglossia} aims to remain as compatible as possible +with the fundamental features of \pkg{babel} while being cleaner, light-weight, +and modern. The package \pkg{antomega} has been very beneficial in our attempt to +reach this objective. + +\paragraph{Requirements:} The current version of \pkg{polyglossia} makes use of some convenient +macros defined in the \pkg{etoolbox} package by Philipp Lehmann. Being designed +for \XeLaTeX\ and \LuaLaTeX, it obviously also relies on \pkg{fontspec} by Will +Robertson. For languages written from right to left, it needs the package \pkg{bidi} +by Vafa Khalighi (\textarabic{وفا خليقي}). Polyglossia also bundles three packages for calendaric +computations (\pkg{hebrewcal}, \pkg{hijrical}, and \pkg{farsical}). + +\section{Loading language definition files} + +\subsection{The recommended way} +You can determine the default language by means of the command: + \displaycmd{\setdefaultlanguage[⟨options⟩]\{lang\}}{\setdefaultlanguage} +(or equivalently \Cmd\setmainlanguage). +Secondary languages can be loaded with + \displaycmd{\setotherlanguage[⟨options⟩]\{lang\}.}{\setotherlanguage} +These commands have the advantage of being explicit and of allowing you to set +language-specific options.\footnote{ % + More on language-specific options below.} +It is also possible to load a series of secondary languages at once using + \displaycmd{\setotherlanguages\{lang1,lang2,lang3,…\}.}{\setotherlanguages} +Language-specific options can be set or changed at any time by means of + \displaycmd{\setkeys\{⟨lang⟩\}\{opt1=value1,opt2=value2,…\}.}{\setkeys} + + +\subsection{The “Babel way”} +\new{v1.2.0} +{\color{red}\bfseries Warning}: \pkg{polyglossia} no longer supports loading +language definition files as package options! +%As with \pkg{babel}, \pkg{polyglossia} also allows you to load language definition files +%as package options. In most cases, option \texttt{⟨lang⟩} will load the file +%\file{gloss-⟨lang⟩.ldf}. Note however that the \textit{first} language listed in \\ +%\centerline{\cmd{\usepackage[lang1,lang2,…]{polyglossia}}} +%will be the default language for the document, which +%is the opposite convention of \pkg{babel}. +%Note also that this method may not work in some cases, and should be +%considered deprecated. + +\subsection{Supported languages} + +Table~\ref{tab:lang} lists all languages currently supported. +Those in red have specific options and/or commands +that are explained in section \ref{specific} below. + +\begin{table}[h]\centering +\label{tab:lang} +%albanian +%amharic +%\TX{arabic} +%armenian +%asturian +%bahasai +%bahasam +%basque +%\TX{bengali} +%brazil[ian] +%breton +%bulgarian +%\TX{catalan} +%coptic +%croatian +%czech +%danish +%divehi +%\TX{dutch} +%\TX{english} +%\TX{esperanto} +%estonian +%\TX{farsi} +%finnish +%french +%galician +%\TX{german} +%\TX{greek} +%\TX{hebrew} +%\TX{hindi} +%icelandic +%interlingua +%irish +%italian +%\TX{lao} +%latin +%latvian +%lithuanian +%\TX{lsorbian} +%\TX{magyar} +%malayalam +%marathi +%norsk +%nynorsk +%occitan +%polish +%portuges +%romanian +%\TX{russian} +%samin +%\TX{sanskrit} +%scottish +%\TX{serbian} +%slovak +%slovenian +%spanish +%swedish +%\TX{syriac} +%tamil +%telugu +%\TX{thai} +%turkish +%turkmen +%ukrainian +%urdu +%\TX{usorbian} +%vietnamese +%welsh +%%%%% private note: the following table was automatically generated with "maketabular.pl 5 < above_input" +\begin{tabular}{lllll} +\hline +albanian & croatian & \TX{hebrew} & norsk & swedish \\ +amharic & czech & \TX{hindi} & nynorsk & \TX{syriac} \\ +\TX{arabic} & danish & icelandic & occitan & tamil \\ +armenian & divehi & interlingua & polish & telugu \\ +asturian & \TX{dutch} & irish & portuges & tibetan \\ +bahasai & \TX{english} & \TX{italian} & romanian & \TX{thai} \\ +bahasam & \TX{esperanto} & \TX{lao} & \TX{russian} & turkish \\ +basque & estonian & latin & samin & turkmen \\ +\TX{bengali} & \TX{farsi} & latvian & \TX{sanskrit}& ukrainian \\ +brazil[ian] & finnish & lithuanian & scottish & urdu \\ +breton & french & \TX{lsorbian} & \TX{serbian} & \TX{usorbian} \\ +bulgarian & galician & \TX{magyar} & slovak & vietnamese \\ +\TX{catalan} & \TX{german} & malayalam & slovenian & welsh \\ +coptic & \TX{greek} & marathi & spanish & \\ +\hline +\end{tabular} +\caption{Languages currently supported in \pkg{polyglossia}} +\end{table} + +\textit{NB:} The support for Amharic\new{v1.0.1} should be considered an experimental attempt to +port the package \pkg{ethiop}.\footnote{ Feedback is welcome.} +Version 1.1.1\new{v1.1.1} addded support for Asturian, %\footnote{ Provided by Kevin Godby and Xuacu Saturio.}, +Lithuanian, %\footnote{ Provided by Kevin Godby and Paulius Sladkevičius.}, +and Urdu. %\footnote{ Provided by Kamal Abdali.} +% +Version 1.2\new{v1.2.0} adds support for Armenian, Occitan, Bengali, +Lao, Malayalam, Marathi, Tamil, Telugu, and Turkmen.\footnote{ % + See acknowledgements at the end for due credit to the various contributors.} + + + +Polyglossia can also be loaded with the option +‘babelshorthands’\new{v1.1.1}, which globally activates \pkg{babel} +shorthands whenever available. Currently shorthands are implemented for +Catalan, Dutch, German, Italian, and Russian: see these respective +languages for details. + +Another option (turned off by default) is ‘localmarks’, which +redefines the internal \LaTeX\ macros \cmd\markboth\ and \cmd\markright. +\new{v1.2.0}Note that this was formerly turned on by default, but ẃe +now realize that it causes more problems than otherwise. For backwards-compatibility +the opposite option ‘nolocalmarks’ is still available. + +There is also the option ‘quiet’ which turns off most info messages and some of the warnings +issued by \LaTeX, \pkg{fontspec} and \pkg{polyglossia}. + +\section{Language-switching commands} + +Whenever a language definition file \file{gloss-⟨lang⟩.ldf} is loaded, +the command \cmd{\text⟨lang⟩[⟨options⟩]\{…\}} \DescribeMacro{\text⟨lang⟩} +becomes available for short insertions of text in that language. +For example ¦\textrussian{\today}¦ yields \textrussian{\today} +Longer passages are better put between the environment ¦⟨lang⟩¦ +(again with the possibility of setting language options locally. +\DescribeEnv{⟨lang⟩} +For instance the following allows us to quote the beginning +of Homer’s \textit{Iliad}: + +\begin{Verbatim}[formatcom=\color{myblue}] +\begin{greek}[variant=ancient] +μῆνιν ἄειδε θεὰ Πηληϊάδεω Ἀχιλῆος οὐλομένην, ἣ μυρί' Ἀχαιοῖς ἄλγε' +ἔθηκε, πολλὰς δ' ἰφθίμους ψυχὰς Ἄϊδι προί̈αψεν ἡρώων, αὐτοὺς δὲ ἑλώρια +τεῦχε κύνεσσιν οἰωνοῖσί τε πᾶσι, Διὸς δ' ἐτελείετο βουλή, ἐξ οὗ δὴ τὰ +πρῶτα διαστήτην ἐρίσαντε Ἀτρεί̈δης τε ἄναξ ἀνδρῶν καὶ δῖος Ἀχιλλεύς. +\end{greek} +\end{Verbatim} + +\begin{greek}[variant=ancient] +μῆνιν ἄειδε θεὰ Πηληϊάδεω Ἀχιλῆος οὐλομένην, ἣ μυρί' Ἀχαιοῖς ἄλγε' ἔθηκε, +πολλὰς δ' ἰφθίμους ψυχὰς Ἄϊδι προί̈αψεν ἡρώων, αὐτοὺς δὲ ἑλώρια τεῦχε κύνεσσιν +οἰωνοῖσί τε πᾶσι, Διὸς δ' ἐτελείετο βουλή, ἐξ οὗ δὴ τὰ πρῶτα διαστήτην ἐρίσαντε +Ἀτρεί̈δης τε ἄναξ ἀνδρῶν καὶ δῖος Ἀχιλλεύς. +\end{greek} +\bigskip + +Note that for Arabic one cannot use the environment ¦arabic¦, +as \cmd\arabic\ is defined internally by \LaTeX. In this case +we need to use the environment ¦Arabic¦ instead\DescribeEnv{Arabic}. + +\subsection{Other commands} +The following commands are probably of lesser interest to the end user, but +ought to be mentioned here. +\begin{itemize} +\item \Cmd\selectbackgroundlanguage: this selects the global font setup and + the numbering definitions for the default language. + +\item \Cmd\resetdefaultlanguage\ (experimental): + completely switches the default language + to another one in the middle of a document: \textit{this may have adverse effects}! + +\item \Cmd\normalfontlatin: in an environment where \cmd\normalfont\ has been redefined + to a non-latin script, this will call the font defined with \cmd\setmainfont\ etc. + Likewise it is possible to use \Cmd\rmfamilylatin, \Cmd\sffamilylatin, + and \Cmd\ttfamilylatin. + +\item Some macros defined in \pkg{babel}’s \file{hyphen.cfg} (and thus usually + compiled into the \XeLaTeX\ and \LuaLaTeX\ format) are redefined, but keep a similar + behaviour, namely \Cmd\selectlanguage, \Cmd\foreignlanguage, + and the environment ¦otherlanguage¦\DescribeEnv{otherlanguage}. +\end{itemize} +% +Since the \XeLaTeX\ and \LuaLaTeX\ format incorporate \pkg{babel}’s \file{hyphen.cfg}, +the low-level commands for hyphenation and language switching +defined there are also accessible. + +\section{Font setup} + +With polyglossia it is possible to associate a specific font with any script or language +that occurs in the document. That font should always be defined as +¦\⟨script⟩font¦\ or ¦\⟨language⟩font¦. +For instance, if the default font defined by \cmd\setmainfont\ +does not support Greek, then one can define the font used to display Greek with:\\ +\centerline{ \cmd\newfontfamily\cmd{\greekfont[Script=Greek,⟨…⟩]\{⟨font⟩\}}. } +Note that polyglossia will use the font thus defined as is. +for instance if ¦\arabicfont¦ is explicitly defined, then one should take care of +including the option ¦Script=Arabic¦ in that definition. +See the \pkg{fontspec} documentation for more information. +If a specific sans or monospace font is needed for a particular script or language, +it can be defined by means of \new{v1.2.0} +¦\⟨script⟩fontsf¦\ or ¦\⟨language⟩fontsf¦ and ¦\⟨script⟩fonttt¦\ or ¦\⟨language⟩fonttt¦, respectively. + +Whenever a new language is activated, \pkg{polyglossia} will first check whether +a font has been defined for that language or – for languages in non-Latin scripts – +for the script it uses. If it is not defined, it will use the currently active font +and – in the case of OpenType fonts – will attempt to turn on the appropriate +OpenType tags for the script and language used, in case these are available in +the font, by means of \pkg{fontspec}’s \cmd\addfontfeature. If the current font +does not appear to support the script of that language, an error message is +displayed. + +\section{Language-specific options and commands}\label{specific} + +This section gives a list of all languages for which options and end-user commands are defined. +The default value of each option is given in italic. + +%\subsection{amharic}\label{amharic} + +\subsection{arabic}\label{arabic} +\textbf{Options}: + \begin{itemize} + \item \TB{calendar} = \textit{gregorian} or islamic (= hijri) + \item \TB{locale} = \textit{default},\footnote{ % + For Egypt, Sudan, Yemen and the Gulf states.} + mashriq,\footnote{ % + For Iraq, Syria, Jordan, Lebanon and Palestine.} + libya, algeria, tunisia, morocco, or mauritania. + This setting influences the spelling of the month names for the Gregorian calendar, + as well as the form of the numerals (unless overriden by the following option). + \item \TB{numerals} = \textit{mashriq} or maghrib + (the latter is the default when locale = algeria, tunisia or morocco) + \item \TB{abjadjimnotail} = \textit{false} or true. \new{v1.0.3} + Set this to true if you want the \textit{abjad} form of the number three to be \textarabic{ج} – as in the manuscript tradition – instead of the modern usage \textarabic{ج}. + \end{itemize} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\abjad and \Cmd\abjadmaghribi (see section \ref{abjad}) + \item \Cmd\aemph to emphasize text with ¦\overline¦.\new{v1.2.0} + ¦\textarabic{\aemph{اب}}¦ yields \textarabic{\aemph{اب}}. + This command is also available for Farsi, Urdu, etc. + \end{itemize} + +\subsection{bengali}\label{bengali}\new{v1.2.0} +\textbf{Options}: + \begin{itemize} + \item \TB{numerals} = Western or \textit{Devanagari} + \end{itemize} + +\subsection{catalan}\label{catalan} +\textbf{Options:} +\begin{itemize} + \item \TB{babelshorthands} = \textit{false} or true. \new{v1.1.1} + Activates the shorthands \texttt{"l} and \texttt{"L} to type geminated l’s. +\end{itemize} +\textbf{Commands}: +\begin{itemize} + \item \Cmd{\l.l} and \Cmd{\L.L} behave as in \pkg{babel} to type a geminated l, as in \textit{co\l.laborar}. \new{v1.1.1} + In polyglossia the same can also be achieved with \Cmd{\l·l} and \Cmd{\L·L}.\footnote{ % + NB: · is the glyph U+00B7 MIDDLE DOT.} +\end{itemize} + +\subsection{dutch}\label{dutch} +\textbf{Options:} +\begin{itemize} + \item \TB{babelshorthands} = \textit{false} or true. \new{v1.1.1} + if this is turned on, all shorthands defined in \pkg{babel} + for fine-tuning the hyphenation of Dutch words are activated. + \begin{itemize} + \item ¦"-¦ for an explicit hyphen sign, allowing hyphenation in the rest of the word + \item ¦"~¦ for a compound word mark without a breakpoint + \item ¦"|¦ disables the ligature at this position + \item ¦""¦ is like ¦"-¦, but produces no hyphen sign + (for compound words with a hyphen, e.g., ¦foo-""bar¦) + \item ¦"/¦ to enable hyphenation in two words written together but separated by a slash. + \item In addition, the macro \Cmd\- is redefined to allow hyphens in the rest of the word. + \end{itemize} +\end{itemize} + +\subsection{english}\label{english} +\textbf{Options}: + \begin{itemize} + \item \TB{variant} = \textit{american} (= us), usmax (same as ‘american’ but with additional hyphenation patterns), british (= uk), australian or newzealand + \item \TB{ordinalmonthday} = true/\textit{false} (true by default only when variant = british) + \end{itemize} + +\subsection{esperanto}\label{esperanto} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\hodiau\ and \Cmd\hodiaun are special forms of \cmd\today\ (see the \pkg{babel} documentation) + \end{itemize} + +\subsection{farsi}\label{farsi} +\textbf{Options}: + \begin{itemize} + \item \TB{numerals} = western or \textit{eastern} + \item \TB{locale} (not yet implemented) + \item \TB{calendar} (not yet implemented) + \end{itemize} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\abjad (see section \ref{abjad}) + \item \Cmd\aemph (see section \ref{arabic}). + \end{itemize} + +%\subsection{french}\label{french} +%\textbf{Options}: +% \begin{itemize} +% \item \TB{espacedeuxpoints} = thick or half \new{v1.2.x} ??? +% \footnote{ % +% Can be customized by redefining \french@colonspace } +% \end{itemize} +% + +\subsection{german}\label{german} +\textbf{Options}: + \begin{itemize} + \item \TB{spelling} = \textit{new} (= 1996) or old (= 1901): + indicates whether hyphenation patterns for traditional (1901) or reformed + (1996) orthography should be used. The latter is the default. + \item \TB{latesthyphen} = \textit{false} or true: if this option is set to true, + the latest (experimental) hyphenation patterns ‘(n)german-x-latest’ + will be loaded instead of ‘german’ or ‘ngerman’. NB: This is based on + the file \texttt{language.dat} that comes with \TeX Live 2008 and later. + \item\TB{babelshorthands} = \textit{false} or true: \new{v1.0.3} + if this is turned on, all shorthands defined in \pkg{babel} + for fine-tuning the hyphenation of German words are activated. + \begin{itemize} + \item ¦"ck¦ for ¦ck¦ to be hyphenated as ¦k-k¦ + \item ¦"ff¦ for ¦ff¦ to be hyphenated as ¦ff-f¦; this is also available for the letters l, m, n, p, r and t + \item ¦"|¦ disables the ligature at this position + \item ¦"-¦ for an explicit hyphen sign, allowing hyphenation in the rest of the word + \item ¦""¦ is like ¦"-¦, but produces no hyphen sign + (for compound words with a hyphen, e.g., ¦foo-""bar¦) + \item ¦"~¦ for a compound word mark without a breakpoint + \item ¦"=¦ for a compound word mark with a breakpoint, + allowing hyphenation in the composing words. + \end{itemize} + + There are also four shorthands for quotation signs: + \begin{itemize} + \item ¦"`¦ for German left double quotes („) + \item ¦"'¦ for German right double quotes (“) + \item ¦"<¦ for French left double quotes («) + \item ¦">¦ for French right double quotes (»). + \end{itemize} + \item\TB{script} = \textit{latin} or fraktur.\new{v1.2.0} + Setting script=fraktur modifies the captions for typesetting German in Fraktur. + \end{itemize} + +\subsection{greek}\label{greek} +\textbf{Options}: + \begin{itemize} + \item \TB{variant} = \textit{monotonic} (= mono), polytonic (= poly), or ancient + \item \TB{numerals} = \textit{greek} or arabic + \item \TB{attic} = \textit{false}/true + \end{itemize} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\Greeknumber and \Cmd\greeknumber \ (see section \ref{abjad}). + \item The command \Cmd\atticnumeral (= \Cmd\atticnum) (activated with + the option ¦attic=true¦), displays numbers using the acrophonic + numbering system (defined in the Unicode range + \textsf{U+10140–U+10174}).\footnote{ % + See the documentation of the \pkg{xgreek} package for more details.} + \end{itemize} + +\subsection{hebrew}\label{hebrew} +\textbf{Options}: + \begin{itemize} + \item \TB{numerals} = hebrew or \textit{arabic} + \item \TB{calendar} = hebrew or \textit{gregorian} + \end{itemize} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\hebrewnumeral\ (= \Cmd\hebrewalph) (see section \ref{abjad}). + \item \Cmd\aemph (see section \ref{arabic}). + \end{itemize} + +\subsection{hindi}\label{hindi}\new{v1.2.0} +\textbf{Options}: + \begin{itemize} + \item \TB{numerals} = Western or \textit{Devanagari} + \end{itemize} + +\subsection{italian}\label{italian} +\textbf{Option:} +\begin{itemize} + \item \TB{babelshorthands} = \textit{false} or true. \new{v1.2.0cc}% TODO: check version + Activates the ¦"¦ character as a switch to perform etymological + hyphenation when followed by a letter, or other tasks when followed by + certain analphabetic characters; in particular ¦""¦ is used to enter + double raised open quotes (the Italian keyboard misses the backtick), + and ¦"<¦ and ¦">¦ to insert open and closed guillemets without any + spacing after the open or before the closed sign. ¦"/¦ is made + equivalent to \slash allowing a linebreak after the slash without any + hyphen sign; ¦"-¦ produces a short rule/hyphen and a discretional line + break alowing line breaks in the second compound word fragment. +\end{itemize} + +\subsection{lao}\label{lao}\new{v1.2.0} +\textbf{Options}: + \begin{itemize} + \item \TB{numerals} = lao or \textit{arabic} + \end{itemize} + +\subsection{lsorbian and usorbian}\label{lsorbian}\label{usorbian} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\oldtoday : see the \pkg{babel} documentation. + \end{itemize} + +\subsection{magyar}\label{magyar} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\ontoday\ (= \Cmd\ondatemagyar): special forms of \cmd\today\ + (see the \pkg{babel} documentation). + \end{itemize} + + +\subsection{russian}\label{russian} +\textbf{Options}: + \begin{itemize} + \item \TB{babelshorthands} = \textit{false} or true. % TODO check and document! + \item \TB{spelling} = \textit{modern} or old (for captions and date only, not for hyphenation) + \end{itemize} + +\subsection{sanskrit}\label{sanskrit} +\textbf{Options}: + \begin{itemize} + \item \TB{Script} (default = Devanagari). \new{v1.0.2} + The value is passed to \pkg{fontspec} in cases where ¦\sanskritfont¦ or + ¦\devanagarifont¦ are not defined. This can be useful if you typeset + Sanskrit texts in scripts other than Devanagari. + %TODO \item Numerals <<<< + \end{itemize} + +\subsection{serbian}\label{serbian} +\textbf{Options}: + \begin{itemize} + \item \TB{script} = \textit{cyrillic} or latin + \end{itemize} + +\subsection{syriac}\label{syriac} +\textbf{Options}: + \begin{itemize} + \item \TB{numerals} = \textit{western} (i.e., 1234567890), eastern + (for which the Oriental Arabic numerals are used: \textarabic{١٢٣٤٥٦٧٨٩٠}), + or abjad. \new{v1.0.1}. + \end{itemize} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\abjadsyriac (see section \ref{abjad}) + \item \Cmd\aemph (see section \ref{arabic}). + \end{itemize} + +\subsection{thai}\label{thai} +\textbf{Options}: + \begin{itemize} + \item \TB{numerals} = thai or \textit{arabic} + \end{itemize} + +To insert the word breaks, you need to use an external processor. +See the documentation to \pkg{thai-latex} and the file \file{testthai.tex} +that comes with this package. + +\section{Modifying or extending captions and date formats} + +To redefine internal macros, you can use the command ¦\gappto¦ from the package +\pkg{etoolbox}. For compatibility with \pkg{babel} the command ¦\addto¦ is also available +with the same effect. For instance, to change the ¦\chaptername¦ for language ¦lingua¦, +you can do this: +\begin{verbatim} +\gappto\captionslingua{\renewcommand{\chaptername}{Caput}} +\end{verbatim} + +\section{Non-Western decimal digits} + +Several scripts have their own versions of the decimal digits commonly called +‘Arabic numerals’. With the appropriate language option set, \pkg{polyglossia} +will automatically convert the output of internal \LaTeX\ counters to their +localized forms, for instance to display page, chapter and section numbers. + +In previous versions this conversion was achieved my means of TECKit fontmappings. +If needed they can be activated with the fontspec ¦Mapping¦ option, +using ¦arabicdigits¦, ¦farsidigits¦ or ¦thaidigits¦. +For instance if \cmd\arabicfont\ is defined with the option ¦Mapping=arabicdigits¦, +then by typing ¦\textarabic{2010}¦ one will obtain \textarabic{٢٠١٠}. + +With version v1.1.1\new{v1.1.1} the same conversion is achieved directly by +simple \TeX\ macros. This prevents some problems that occur when the value of a +counter has to be written and read from auxiliary files.\footnote{ % + For instance the package \pkg{lastpage} did not work with \pkg{polyglossia} in situations + where the display of counters was redefined to include a font-switching command.} +These macros (currently \Cmd\arabicdigits, \Cmd\farsidigits\ and \Cmd\thaidigits\ are provided) +are also available to the users. For instance in an Arabic environment +¦\arabicdigits{9182/738543-X}¦ yields +\textarabic{\arabicdigits{9182/738543-X}}. + +\section{Alphabetic numbering in Greek, Arabic, Hebrew, Syriac and Farsi}\label{abjad} + +In certain languages, numbers can be represented +by a special alphanumerical notation.\footnote{ % + See, e.g., \url{http://en.wikipedia.org/wiki/Greek_numerals}, + \url{http://en.wikipedia.org/wiki/Abjad_numerals}, + and \url{http://en.wikipedia.org/wiki/Hebrew_numerals}.} + %% \url{http://en.wikipedia.org/wiki/Syriac_alphabet} + +The Greek numerals are obtained with \Cmd\greeknumeral (or \Cmd\Greeknumeral\ in uppercase). +Example: ¦\greeknumeral{1863}¦ yields \textgreek{\greeknumeral{1863}}. + +The Arabic \textit{abjad} numbers can be generated with the command \Cmd\abjad. +Example: ¦\abjad{1863}¦ yields \textarabic{\abjad{1863}}. +In the Maghrib the conventions are somewhat different, and the maghribi forms +of the \textit{abjad} numerals are obtained with the \Cmd\abjadmaghribi\ command. +Example: ¦\abjadmaghribi{1863}¦ yields \textarabic{\abjadmaghribi{1863}}. + +The code for Hebrew numerals, which was incorrect in previous versions, was +ported from the implementation in \pkg{babel} with v1.1.1\new{v1.1.1}, and the +user interface is identical to the one in \pkg{babel}. +The commands \Cmd\hebrewnumeral, \Cmd\Hebrewnumeral and \Cmd\Hebrewnumeralfinal\ behave exactly +as they do in \pkg{babel}: the second command prints the number with \textit{gereshayim} before +the last letter, and the latter uses in addition the final forms of Hebrew letters. +Examples: +¦\hebrewnumeral{1750}¦ yields \texthebrew{\hebrewnumeral{1750}}, +¦\Hebrewnumeral{1750}¦ yields \texthebrew{\Hebrewnumeral{1750}}, +and ¦\Hebrewnumeralfinal{1750}¦ yields \texthebrew{\Hebrewnumeralfinal{1750}}. + + +Support is also provided for Syriac abjad numerals, which can be generated +with \Cmd\abjadsyriac.\footnote{ % +A fine guide to numerals in Syriac can be found at \link{http://www.garzo.co.uk/documents/syriac-numerals.pdf}.} +Example: ¦\abjadsyriac{463}¦ yields \textsyriac{\abjadsyriac{463}}. + + +\section{Calendars} + +\subsection{Hebrew calendar (hebrewcal.sty)} +The package \file{hebrewcal.sty} is almost a verbatim copy of \file{hebcal.sty} +that comes with \pkg{babel}. +The command \Cmd\Hebrewtoday\ formats the current date in the Hebrew calendar +(depending of the current writing direction this will automatically set either +in Hebrew script or in roman transliteration). + +\subsection{Islamic calendar (hijrical.sty)} +This package computes dates in the lunar Islamic (Hijra) calendar.\footnote{ % + It makes use of the arithmetical algorithm in chapter 6 of + Reingold \& Gershowitz, \textit{Calendrical calculation: the Millenium edition} + (Cambridge University Press, 2001).\label{reingold}} +It provides two macros for the end-user. +The command + \displaycmd{\HijriFromGregorian\{⟨year⟩\}\{⟨month⟩\}\{⟨day⟩\}}{\HijriFromGregorian} +sets the counters ¦Hijriday¦, ¦Hijrimonth¦ and ¦Hijriyear¦. +\Cmd\Hijritoday\ formats the Hijri date for the current day. +This command is now locale-aware\new{v1.1.1}: its output will differ depending on the +currently active language. Presently \pkg{polyglossia}’s language definition files +for Arabic, Farsi, Urdu, Turkish, Bahasa Indonesia and Bahasa Melayu +provide a localized version of ¦\Hijritoday¦. +If the formatting macro for the current language is undefined, the Hijri date will be formatted +in Arabic or in roman transliteration, depending of the current writing direction. +You can define a new format or redefine one with the command + \displaycmd{\DefineHijriDateFormat\{<lang>\}\{<code>\}.}{\DefineHijriDateFormat} + +The command ¦\Hijritoday¦ also accepts an optional argument to add or subtract a correction +(in days) to the date computed by the arithmetical algorithm.\footnote{ % + The Islamic calendar is indeed a purely lunar calendar based on the observation + of the first visibility of the lunar crescent at the beginning of the lunar month, + so there can be differences between different localities, as well as between + civil and religious authorities.} +For instance if ¦\Hijritoday¦ yields the date “7 Rajab 1429” (which is the date that was +displayed on the front page of \href{http://www.aljazeera.net}{aljazeera.net} on +11th July 2008), ¦\Hijritoday[1]¦ would rather print “8 Rajab 1429” (the date +indicated the same day on the site \href{http://www.gulfnews.com}{gulfnews.com}). + +\subsection{Farsi (jalālī) calendar (farsical.sty)} +This package is an almost verbatim copy of ¦Arabiftoday.sty¦ (in the \pkg{Arabi} package), +itself a slight modification of ¦ftoday.sty¦ in Farsi\TeX.\footnote{ % + One day I may rewrite \pkg{farsical} from scratch using the algorithm in + Reingold \& Gershowitz (ref.~n.~\ref{reingold}).} +Here we have renamed the command \cmd\ftoday\ to +\Cmd\Jalalitoday. +Example: today is \Jalalitoday. + + +%\section{Varia} + + +\section{Acknowledgements (by François Charette)} +\pkg{Polyglossia} is notable for being a recycle box of previous contributions +by other people. I take this opportunity to thank the following individuals, +whose splendid work has made my task almost trivial in comparision: Johannes +Braams and the numerous contributors to the \pkg{babel}{} package (in particular +Boris Lavva and others for its Hebrew support), Alexej Kryukov (\pkg{antomega}), Will +Robertson (\pkg{fontspec}), Apostolos Syropoulos (\pkg{xgreek}), Youssef Jabri +(\pkg{arabi}), and Vafa Khalighi (\pkg{xepersian} and \pkg{bidi}). +The work of Mojca Miklavec and Arthur Reutenauer on hyphenation patterns with their package +\pkg{hyph-utf8} is of course invaluable. I should also thank other +individuals for their assistance in supporting specific languages: Yves Codet +(Sanskrit), Zdenek Wagner (Hindi), Mikhal Oren (Hebrew), Sergey Astanin (Russian), +Khaled Hosny (Arabic), Sertaç Ö. Yıldız (Turkish), Kamal Abdali (Urdu), +and several other members of the \XeTeX\ user community, notably Enrico Gregorio, who +has sent me many useful suggestions and corrections and contributed the ¦\newXeTeXintercharclass¦ +mechanism in xelatex.ini which is now used by polyglossia. +More recently, Kevin Godby of the \href{http://ubuntu-manual.org}{Ubuntu Manual} project has +contributed very useful feedback, bug hunting and, with the help of translators, +new language definition files for Asturian, Lithuanian, Occitan, Bengali, Malayalam, Marathi, Tamil, and Telugu. +It is particularly heartening to realize that this package is used to typeset a widely-read +document in dozens of different languages! +Support for Lao was also added thanks to Brian Wilson. +I also thank Alan Munn for kindly proof-reading the penultimate version of this documentation. +And of course my gratitude also goes to Jonathan Kew, the formidable author of \XeTeX! +\end{document} + |