diff options
Diffstat (limited to 'Master/texmf-dist/doc/xelatex/polyglossia/polyglossia.tex')
-rw-r--r-- | Master/texmf-dist/doc/xelatex/polyglossia/polyglossia.tex | 500 |
1 files changed, 500 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/xelatex/polyglossia/polyglossia.tex b/Master/texmf-dist/doc/xelatex/polyglossia/polyglossia.tex new file mode 100644 index 00000000000..98d121422d2 --- /dev/null +++ b/Master/texmf-dist/doc/xelatex/polyglossia/polyglossia.tex @@ -0,0 +1,500 @@ +\documentclass[11pt]{ltxdoc} +\usepackage{xltxtra} +\usepackage{xspace,fancyvrb} +\usepackage[neverdecrease]{paralist} +\usepackage[dvipdfm]{color} +\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} +\definecolor{darkgray}{gray}{0.3} +\definecolor{lightgray}{gray}{0.6} +\definecolor{mygreen}{rgb}{0,.43,0} +\usepackage[dvipdfm, + bookmarks=true, + colorlinks=true, + linkcolor=myblue, + urlcolor=myblue, + citecolor=myblue, + hyperindex=false, + hyperfootnotes=false, + pdftitle={Polyglossia: A Babel replacement for XeLaTeX}, + pdfauthor={F Charette <firmicus ατ gmx δοτ net>}, + pdfkeywords={xetex, xelatex, multilingual, babel, hyphenation} + ]{hyperref} +\usepackage{polyglossia,farsical} +\setmainlanguage[variant=uk]{english} +\setotherlanguages{arabic,hebrew,syriac,greek,russian} +\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*\TB[1]{\textcolor{myblue}{\bf #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}} + +\newlength{\oldparindent} +\newcommand{\parindentoff}{\setlength{\oldparindent}{\parindent} \setlength{\parindent}{0pt}} +\newcommand{\parindenton}{\setlength{\parindent}{\oldparindent}} + +%% Sidenotes << copied from fontspec.dtx +\newcommand\warn[2]{% + \edef\thisversion{#1}% + \ifhmode\unskip~\fi{\ifx\thisversion\fileversion\color{red}\fi + $\leftarrow$}% + \marginpar{\raggedleft + \small% + {\ifx\thisversion\fileversion\color{red}\fi$\rightarrow$}% + \,{\notefont #1:~#2}}} + +\newcommand\new[1]{% + \edef\thisversion{#1}% + \ifhmode\unskip~\fi{\ifx\thisversion\fileversion\color{blue}\else\color[gray]{0.5}\fi + $\leftarrow$}% + \marginpar{\raggedleft + \small\ifx\thisversion\fileversion\color{blue}\else\color[gray]{0.5}\fi + $\rightarrow$\,{\notefont #1:~New!}}} +\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}} + +%% Sidenote font +\newfontfamily\notefont[Scale=MatchLowercase]{Lucida Sans Unicode} +%%% + +%% fontspec declarations: +\setromanfont[Mapping=tex-text]{Linux Libertine} +\defaultfontfeatures{Scale=MatchLowercase} +\setmonofont{DejaVu Sans Mono}%{Consolas} +\setsansfont{Lucida Sans Unicode} +\newfontfamily\arabicfont[Script=Arabic,Scale=1.5]{Scheherazade} +\newfontfamily\farsifont[Script=Arabic,Scale=1.33]{Farsi Simple Bold} +\newfontfamily\syriacfont[Script=Syriac,Scale=1.5,ExternalLocation="/mnt/data/fonts/syriac/"]{SyrCOMJerusalem.otf} +\newfontfamily\hebrewfont[Script=Hebrew]{SBL Hebrew} + +\newcommand\Babel{\pkg{babel}\xspace} + +\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[ExternalLocation="/mnt/data/fonts/greek/"]{GFSAmbrosia.otf} +Π$\;\,$ο$\;\,$λ$\;\,$υ$\;\,$γ$\;\,$λ$\;\,$ο$\;\,$σ$\;\,$σ$\;\,$ι$\;\,$α}\\[16pt] +\color{myblue}Polyglossia: A Babel Replacement for \XeLaTeX} +\author{\scshape\color{myblue}François Charette} +\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. +Basically, it can be used as a replacement of \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 in function of 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 numeration system, modifying the formatting + of numbers appropriately (this also includes redefining the alphabetic sequence + for non-Latin alphabets). +\item Ensuring the 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 \Babel{} that do not make sense in the \XeTeX\ world (like font +encodings, shorthands, etc.) are (obviously) not supported. +Generally speaking, \pkg{polyglossia} aims to remain as compatible as possible +with the fundamental features of \Babel{} while being cleaner, light-weight, +and modern. The package \pkg{antomega} has been much 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 +specifically for \XeLaTeX, it obviously also relies on \pkg{fontspec} by Will +Robertson. For languages written from right to left, it needs the package \pkg{bidi} +(by the present author). 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 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”} +As with \Babel{}, \pkg{polyglossia} also allows 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 \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 command +that are explained in section \ref{specific} below. + +\begin{table}[h]\centering +\label{tab:lang} +\begin{tabular}{lllll}\hline +albanian & czech & \TR{german} & \TR{magyar}& slovak \\ +\TR{arabic}& danish & \TR{greek} & norsk & slovenian\\ +bahasai & divehi & \TR{hebrew} & nynorsk & spanish \\ +bahasam & dutch & hindi & polish & swedish \\ +basque &\TR{english}& icelandic & portuges & \TR{syriac} \\ +brazil &\TR{esperanto}& interlingua & romanian & \TR{thai} \\ +breton & estonian & irish &\TR{russian}& turkish \\ +bulgarian&\TR{farsi} & italian & samin & ukrainian \\ +catalan & finnish & latin & sanskrit &\TR{usorbian} \\ +coptic & french & latvian & scottish & welsh \\ +croatian & galician & \TR{lsorbian} &\TR{serbian}& \\ +\hline +\end{tabular} +\caption{Languages currently supported in \pkg{polyglossia}} +\end{table} + +Some options are convenient shortcuts for loading languages with +specific options: + +\begin{itemize} +\item american = english with option ‘variant=american’ +\item USenglish = english with option ‘variant=american’ +\item UKenglish = english with option ‘variant=british’ +\item british = english with option ‘variant=british’ +\item australian = english with option ‘variant=australian’ +\item newzealand = english with option ‘variant=newzealand’ +\item ogerman = german with option ‘spelling=old’ +\item monogreek = greek with option ‘variant=monotonic’ (or ‘mono’) +\item polygreek = greek with option ‘variant=polytonic’ (or ‘poly’) +\item ancientgreek = greek with option ‘variant=ancient’ +\end{itemize} +Another option (turned off by default) is ‘nolocalmarks’, which +prevents the redefinition of the internal \LaTeX\ macros +\cmd\markboth\ and \cmd\markright. + +\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} +\begin{greek}[variant=ancient] +τὸν δ' ἠμείβετ' ἔπειτα θεά, γλαυκῶπις Ἀθήνη: “ὦ πάτερ ἡμέτερε Κρονίδη, ὕπατε +κρειόντων, καὶ λίην κεῖνός γε ἐοικότι κεῖται ὀλέθρῳ: ὡς ἀπόλοιτο καὶ ἄλλος, +ὅτις τοιαῦτά γε ῥέζοι: ἀλλά μοι ἀμφ' Ὀδυσῆι δαί̈φρονι δαίεται ἦτορ, δυσμόρῳ, ὃς +δὴ δηθὰ φίλων ἄπο πήματα πάσχει νήσῳ ἐν ἀμφιρύτῃ, ὅθι τ' ὀμφαλός ἐστι θαλάσσης …” +\end{greek} +\end{verbatim} + +\begin{greek}[variant=ancient] +τὸν δ' ἠμείβετ' ἔπειτα θεά, γλαυκῶπις Ἀθήνη: “ὦ πάτερ ἡμέτερε Κρονίδη, ὕπατε +κρειόντων, καὶ λίην κεῖνός γε ἐοικότι κεῖται ὀλέθρῳ: ὡς ἀπόλοιτο καὶ ἄλλος, +ὅτις τοιαῦτά γε ῥέζοι: ἀλλά μοι ἀμφ' Ὀδυσῆι δαί̈φρονι δαίεται ἦτορ, δυσμόρῳ, ὃς +δὴ δηθὰ φίλων ἄπο πήματα πάσχει νήσῳ ἐν ἀμφιρύτῃ, ὅθι τ' ὀμφαλός ἐστι θαλάσσης …” +\end{greek} + + +\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 numeration 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\setromanfont\ etc. + Likewise it is possible to use \Cmd\rmfamilylatin, \Cmd\sffamilylatin, + and \Cmd\ttfamilylatin. + +\item Also some macros defined in \Babel’s \file{hyphen.cfg} (and thus usually + compiled into the xelatex format) are redefined, but keep a similar + behaviour, namely \Cmd\selectlanguage, \Cmd\foreignlanguage, + and the environment ¦otherlanguage¦\DescribeEnv{otherlanguage}. +\end{itemize} +% +Since the \XeLaTeX\ format incorporates \Babel{}'s \file{hyphen.cfg}, +the low-level commands for hyphenation and language switching +defined there are also accessible.\footnote{ % + The file \file{hyphen\_cfg} (available on the + \href{http://scripts.sil.org/svn-view/xetex/TRUNK/texmf/tex/xelatex/polyglossia/hyphen\_cfg}{\XeTeX\ subversion repository}) + is meant to eventually replace \Babel’s \file{hyphen.cfg}. If you want + to experiment with it, rename it into \file{hyphen.cfg}, copy it to + \texttt{…/tex/xelatex/polyglossia/} and rebuild the xelatex format.} + +\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{arabic} +\textbf{Options}: + \begin{itemize} + \item \TB{calendar} = \textit{islamic} (= hijri) or gregorian + \item \TB{locale} = \textit{default},\footnote{ % + For Egypt, Sudan, Yemen and the Golf 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) + \end{itemize} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\abjad and \Cmd\abjadmaghribi (see section \ref{abjad}) + \end{itemize} + +\subsection{english} +\textbf{Options}: + \begin{itemize} + \item \TB{variant} = \textit{american} (= us), british (= uk), australian or newzealand + \item \TB{ordinalmonthday} = true/\textit{false} (true by default only when variant = british) + \end{itemize} + +\subsection{esperanto} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\hodiau\ and \Cmd\hodiaun are special forms of \cmd\today\ (see the \Babel\ documentation) + \end{itemize} + +\subsection{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}) + \end{itemize} + +\subsection{german} +\textbf{Options}: + \begin{itemize} + \item \TB{spelling} = \textit{new} or old + \end{itemize} + +\subsection{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} +\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}). + \end{itemize} + + +\subsection{lsorbian and usorbian} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\oldtoday : see the \Babel documentation. + \end{itemize} + +\subsection{magyar} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\ontoday\ (= \Cmd\ondatemagyar): special forms of \cmd\today\ + (see the \Babel\ documentation). + \end{itemize} + + +\subsection{russian} +\textbf{Options}: + \begin{itemize} + \item \TB{spelling} = \textit{modern} or old (for captions and date only, not for hyphenation) + \end{itemize} + +\subsection{serbian} +\textbf{Options}: + \begin{itemize} + \item \TB{script} = \textit{cyrillic} or latin + \end{itemize} + +\subsection{syriac} +\textbf{Options}: + \begin{itemize} + \item \TB{numerals} = \textit{western} (i.e., 1234567890) or eastern + (for which the Oriental Arabic numerals are used: \textarabic{١٢٣٤٥٦٧٨٩٠}). + \end{itemize} +\textbf{Commands}: + \begin{itemize} + \item \Cmd\abjadsyriac (see section \ref{abjad}) + \end{itemize} + +\subsection{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{Alphabetic numeration 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} +Note that the Hebrew implementation in \pkg{polyglossia} is currently less +sophisticated than the one in \Babel, where various special cases are taken into +account. + +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 {\arabicfont\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 {\arabicfont\abjadmaghribi{1863}}. + +Hebrew numerals are generated with the command \Cmd\hebrewnumeral. +Example: +¦\hebrewnumeral{1863}¦ yields {\hebrewfont\hebrewnumeral{1863}}. + +Support is also provided for Syriac abjad numerals, which can be generated +with \Cmd\abjadsyriac. +Example: ¦\abjadsyriac{463}¦ yields {\syriacfont\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 \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 new package computes dates in the Islamic (Hijra) calendar, which is lunar.\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 (depending of the +current writing direction this is set either in Arabic or in roman transliteration). +It 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 their can be differences between different localities, as well as between + civil and religious authorities.} +For instance if ¦\Hijritoday¦ yields the date “\Hijritoday” (which is the one +for \today\ indicated on the front page of \href{http://www.aljazeera.net}{aljazeera.net}), +¦\Hijritoday[1]¦ would rather print “\Hijritoday[1]” (the date given on the site +\href{http://www.gulfnews.com}{gulfnews.com}). + +\subsection{Farsi (jalālī) calendar (farsical.sty)} +Again this is taken almost verbatim from ¦Arabiftoday.sty¦ (in the \pkg{Arabi} package), +itself a slight modification of the file ¦ftoday.sty¦ in Farsi\TeX.\footnote{ % + I intend to 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} +\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 \Babel{} package (in particular +Boris Lavva and others for its Hebrew support), Alexej Kryukov (antomega), Will +Robertson (\pkg{fontspec}), Apostolos Syropoulos (\pkg{xgreek}), Youssef Jabri +(\pkg{arabi}), and Vafa Khalighi (\pkg{xepersian}). I should also thank other +individuals for their assistance in supporting specific languages: Yves Codet +(Sanskrit), Zdenek Wagner (Hindi), and other members of the xetex user +community. And of course my gratitude also goes to Jonathan Kew, the formidable +author of \XeTeX! + +\end{document} + |