path: root/Master/texmf-dist/doc/latex/polyglossia/polyglossia.tex

\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}
\hyphenation{Kha-li-ghi}
\GetFileInfo{polyglossia.sty}

\title{\textcolor{lightblue}{\Huge\fontspec[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"
% Note above from François.  Note from self: the table was then
% painstakingly edited by hand because I failed to see the note above :-P -- Arthur
\begin{tabular}{lllll}
\hline
albanian     & czech          & \TX{hindi}    & norsk        & spanish       \\
amharic      & danish         & icelandic     & nynorsk      & swedish       \\
\TX{arabic}  & divehi         & interlingua   & occitan      & \TX{syriac}   \\
armenian     & \TX{dutch}     & irish         & piedmontese  & tamil         \\
asturian     & \TX{english}   & \TX{italian}  & polish       & telugu        \\
bahasai      & \TX{esperanto} & kannada       & portuges     & tibetan       \\
bahasam      & estonian       & \TX{lao}      & romanian     & \TX{thai}     \\
basque       & \TX{farsi}     & latin         & romansh      & turkish       \\
\TX{bengali} & finnish        & latvian       & \TX{russian} & turkmen       \\
brazil[ian]  & french         & lithuanian    & samin        & ukrainian     \\
breton       & friulan        & \TX{lsorbian} & \TX{sanskrit}& urdu          \\
bulgarian    & galician       & \TX{magyar}   & scottish     & \TX{usorbian} \\
\TX{catalan} & \TX{german}    & malayalam     & \TX{serbian} & vietnamese    \\
coptic       & \TX{greek}     & marathi       & slovak       & welsh         \\
croatian     & \TX{hebrew}    & nko           & slovenian    &               \\
\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 we
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{Hyphenation disabling}

In some very specific contexts (such as music score creation), \TeX{} hyphenation
is something to avoid as it may cause troubles. \pkg{polyglossia} provides two
functions: \cmd\disablehyphenation and \cmd\enablehyphenation . Note that when
you select a new language, hyphenation will be in the same state (enabled or
disabled) as before. When you reenable it, it will take the last selected
language.

\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{variant} = \textit{german} or austrian.\new{v1.33.4}
		Setting variant=austrian uses some austrian lexical variants.
	\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}

\textbf{Commands}:
	\begin{itemize}
	\item \Cmd\Asbuk: produces the uppercase Russian alphabet, for
	environments such as ¦enumerate¦
	\item \Cmd\asbuk: same in lowercase
	\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}