xetex writer documentation and new default font.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@6432 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

8 files changed, 258 insertions, 125 deletions

diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index c1c4f8501..b428fb77e 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -2425,6 +2425,10 @@ XeTeX writer
 * Glyphs missing in the font are left out in the PDF without warning
   (e.g. ⇔ left-right double arrow in the functional test output).
 
+* Disable word-wrap (hyphenation) in literal text locally with
+  ``providecommand{\nohyphenation}{\addfontfeatures{HyphenChar=None}}``?
+
+
 problematic URLs
 ````````````````
 
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index c07ba9d6a..c5f1b4a6b 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -977,7 +977,7 @@ _`documentoptions`
     Specify document options.  Multiple options can be given, separated by
     commas.
 
-    Default: "10pt,a4paper".  Option: ``--documentoptions``.
+    Default: "a4paper".  Option: ``--documentoptions``.
 
 _`font_encoding`
     Specify LaTeX font encoding. Multiple options can be given, separated
@@ -1156,6 +1156,47 @@ table_style
 
     Default: "standard".  Option: ``--table-style``.
 
+[xetex writer]
+.................
+
+The xetex writer derives from the latex2e writer, and shares
+all settings defined in the `[latex2e writer]`_ section.  The
+"[latex2e writer]" section of configuration files is processed
+before the "[xetex writer]" section.
+
+The following settings differ from those of the latex2e writer:
+
+font_encoding
+    Disabled as XeTeX uses Unicode-encoded fonts.
+
+.. _latex_preamble [xetex writer]:
+
+latex_preamble
+    LaTeX code that will be inserted in the document preamble.
+
+    Default:
+      Font setup for `Linux Libertine`_,::
+
+        % Linux Libertine (free, wide coverage, not only for Linux)
+        \setmainfont{Linux Libertine O}
+        \setsansfont{Linux Biolinum O}
+        \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
+
+      The optional argument ``HyphenChar=None`` to the monospace font
+      prevents word hyphenation in literal text.
+
+
+    Option: ``--latex-preamble``
+
+.. _template [xetex writer]:
+
+template
+    Path to template file.
+
+    Default: "xelatex.tex" in the ``docutils/writers/latex2e/``
+    directory (installed automatically; for the exact machine-specific
+    path, use the ``--help`` option).  Options: ``--template``.
+
 
 [pseudoxml writer]
 ``````````````````
diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt
index 1fe67b024..c94536f54 100644
--- a/docutils/docs/user/latex.txt
+++ b/docutils/docs/user/latex.txt
@@ -45,7 +45,8 @@ sources via LaTeX:
    As with HTML, styling is mostly done via style sheets or
    `LaTeX packages`_.
 
-   If you prefer this approach, try the `latex2e` writer.
+   If you prefer this approach, try the `latex2e` or the `xetex`
+   writer.
 
 2. treat LaTeX as a page description format (like Postscript):
 
@@ -60,7 +61,7 @@ sources via LaTeX:
    files.
 
 This documents describes the first approach used by the `latex2e`
-writer.
+and `xetex` writers.
 
 
 LaTeX
@@ -83,7 +84,7 @@ available at CTAN_ (see the `TeX Catalogue`_).
 .. _CTAN: http://www.ctan.org
 .. _TeX Catalogue: http://texcatalogue.sarovar.org/
 .. _stylesheet:
-   ../user/config.html#stylesheet-latex2e-writer
+   config.html#stylesheet-latex2e-writer
 .. _TeX input path:
    http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
 
@@ -91,10 +92,10 @@ available at CTAN_ (see the `TeX Catalogue`_).
 Docutils special LaTeX macros
 -----------------------------
 
-Some Docutils objects have no LaTeX counterpart, they will be typeset using
-a Docutils specific LaTeX *macro* (command, environment, or length) to allow
-layout changes from the `style sheet`_ or with `raw LaTeX`_. By convention,
-special macros use the prefix ``\DU``\ [#]_.
+Some Docutils objects have no LaTeX counterpart, they will be typeset
+using a Docutils specific LaTeX *macro* (command, environment, or
+length) to allow customization. By convention, special macros use the
+prefix ``\DU``\ [#]_.
 
 The generated LaTeX documents should be kept processable by a standard LaTeX
 installation. Therefore fallback definitions are included after the `custom
@@ -158,8 +159,8 @@ PDF generation
 ==============
 
 In most cases, LaTeX code is not the desired end-format of the document.
-LaTeX offers (at least) four ways to generate PDF documents from the LaTeX
-source:
+LaTeX offers many ways to generate PDF documents from the LaTeX
+source, including:
 
 _`pdflatex`
   Generates a PDF document directly from the LaTeX file.
@@ -173,15 +174,16 @@ _`latex` + dvips + ps2pdf
   Produce a DVI file with ``latex``, postscript with ``dvips`` and PDF with
   ``ps2pdf``.
 
-_`xetex`
+_`xelatex`
   The `XeTeX`__ engine works with input files in UTF-8 encoding and system
-  fonts. It is currently not supported by Docutils.
+  fonts. Export your document with the `xetex` writer (``rst2xetex``),
+  if you want to go this route.
 
 You need to call latex (or pdflatex/xelatex) twice (or even three times) to
 get internal references correct.
 
-.. _documentoptions: ../user/config.html#documentoptions
-__ http://scripts.sil.org/xetex
+.. _documentoptions: config.html#documentoptions
+__ http://tug.org/xetex/
 
 
 _`rubber`
@@ -219,7 +221,7 @@ Options can be specified as
 * configuration settings (see `Docutils Configuration`_ for details).
 
 .. _Docutils Configuration:
-   ../user/config.html
+   config.html
 
 
 .. _style sheet:
@@ -269,7 +271,7 @@ Stylesheet Repository
 .. _clsguide:
    http://mirror.ctan.org/macros/latex/doc/clsguide.pdf
 .. _embed-stylesheet:
-   ../user/config.html#embed-stylesheet-latex2e-writer
+   config.html#embed-stylesheet-latex2e-writer
 .. _repository of user-contributed style sheets:
    ../../../sandbox/stylesheets/
 .. _sandbox: ../../../sandbox/
@@ -287,7 +289,7 @@ Option:
   latex-preamble_
 
 Default:
-  Load the `PDF standard fonts`_ (Times, Helvetica, Courier)
+  used for `font setup`_
 
 Example:
   To use the better looking ``txtt`` font for monospaced text define the
@@ -298,9 +300,11 @@ Example:
                      \usepackage[scaled=.92]{helvet}  % Helvetica
 
 .. _latex-preamble:
-   ../user/config.html#latex-preamble
+   config.html#latex-preamble
 .. _PDF standard fonts:
    http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts
+.. _Linux Libertine:
+   http://www.linuxlibertine.org/index.php?id=1&L=1
 
 
 Templates
@@ -324,7 +328,7 @@ Example:
     --template=titlepage.tex
 
 .. _publisher documentation: ../api/publisher.html
-.. _template: ../user/config.html#template-latex2e-writer
+.. _template: config.html#template-latex2e-writer
 
 
 Raw LaTeX
@@ -558,7 +562,7 @@ Option:
 .. _memoir:
    http://mirror.ctan.org/help/Catalogue/entries/memoir.html
 .. _documentclass:
-   ../user/config.html#documentclass
+   config.html#documentclass
 
 
 document info
@@ -585,9 +589,9 @@ Example:
 __ ../ref/rst/restructuredtext.html#bibliographic-fields
 
 .. _use-latex-docinfo:
-   ../user/config.html#use-latex-docinfo
+   config.html#use-latex-docinfo
 .. _use-latex-abstract:
-   ../user/config.html#use-latex-abstract
+   config.html#use-latex-abstract
 
 
 document title
@@ -710,6 +714,7 @@ Example 2:
 .. _float.pdf:
    http://mirror.ctan.org/macros/latex/contrib/float/float.pdf
 
+.. _font setup:
 
 font
 ----
@@ -720,30 +725,102 @@ http://www.csarven.ca/web-typography).
 Selecting a suitable font also solves the problem with `bad looking
 PDF output`_.
 
-Default:
+Font selection is one of the main differences between LaTeX and XeTeX:
+
+LaTeX
+  cannot use the fonts of the operating system directly but needs
+  specially installed fonts with additional supporting files.
+
+XeTeX
+  can use system fonts and provides access to the full feature set of
+  modern OpenType_ fonts.
+
+.. _OpenType: http://en.wikipedia.org/wiki/OpenType
+
+The default font setup is done in the latex-preamble_:
+
+LaTeX
   `PDF standard fonts`_ (Times, Helvetica, Courier)
-  (since Docutils 0.7)
+
+XeTeX
+  `Linux Libertine`_, a free, high quality alternative to Times with a
+  wide coverage of glyphs, styles, and OpenType features.
+
+  Despite its name, Linux Libertine can be used on any operating
+  system that can handle OpenType fonts.
 
 Alternative fonts can be selected by
 
-a) specifying the corresponding LaTeX package(s) as argument to the
-   stylesheet_ option_ or with the ``\usepackage`` LaTeX command.
+LaTeX
+  a) specifying the corresponding LaTeX package(s) as argument to the
+     stylesheet_ option_ or with the ``\usepackage`` LaTeX command.
+
+     * packages can be combined,
+     * passing options to a package is only possible in a `style sheet`_
+       or the `LaTeX preamble`_.
+
+  b) changing the font-default macros ``\rmdefault``, ``\sfdefault``
+     and/or ``\ttdefault`` in a custom `style sheet`_, the `LaTeX
+     preamble`_ or `raw LaTeX`_.
+
+  Example 1:
+    Use `Latin Modern`_. LaTeX code::
+
+      \usepackage{lmodern}
+
+    Command line argument::
+
+      --stylesheet=lmodern
+
+  Example 2:
+    The _`Times/Helvetica/Courier` `PDF standard fonts`_ are
+    selected by the LaTeX code [#]_::
+
+      \usepackage{mathptmx}            % Times for serif and math
+      \usepackage[scaled=.90]{helvet}  % downscaled Helvetica for sans serif
+      \usepackage{courier}             % Courier for teletype (mono-space)
+
+    Since Docutils 0.7, this is the default value of the
+    `latex-preamble`_ option.
+
+  .. [#] When generating PDF-files from LaTeX, the `PDF standard
+     fonts`_ do not need to be embedded in the document. While this
+     results in smaller files, the actually used fonts on screen and in
+     print might differ! (For details see, e.g., the testflow_ package
+     documentation.)
+
+
+  Example 3:
+    Use the teletype font from the txfonts_ package. As there is no
+    package for this, we re-define the font macro with the LaTeX code::
 
-   * packages can be combined,
-   * passing options to a package is only possible in a `style sheet`_
-     or the `LaTeX preamble`_.
+      \renewcommand{\ttdefault}{txtt}
 
-b) changing the font-default macros ``\rmdefault``, ``\sfdefault``
-   and/or ``\ttdefault`` in a custom `style sheet`_, the `LaTeX
-   preamble`_ or `raw LaTeX`_.
+
+XeTeX
+  using the macros of the fontspec_ package. Use some font-viewer or
+  -manager (e.g. fontmatrix_) to find out the correct names of the
+  fonts on your system.
+
+  Example:
+    DejaVu_, very wide coverage, screen optimized. As this font
+    runs wide, add ``DIV=10`` to the `documentoptions`_::
+
+      \setmainfont{DejaVu Serif}
+      \setsansfont{DejaVu Sans}
+      \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
+
+.. _fontspec: http://mirror.ctan.org/help/Catalogue/entries/fontspec.html
+.. _fontmatrix: http://fontmatrix.net/
+.. _DejaVu: http://dejavu-fonts.org/
+.. _documentoptions: config.html#documentoptions
 
 choice of suitable fonts
 ````````````````````````
 
-Unfortunately, LaTeX cannot use the fonts of the operating system directly
-[#]_ but needs specially installed fonts with additional supporting files.
-
-.. [#] XeTeX_ can, but is not (yet) supported by Docutils
+High quality free fonts suitable for use with XeTeX are, e.g., listed
+at `Good Libre Fonts`_, `25 Best Free Quality Fonts`_ and the update
+`19 More Free Quality Fonts`_.
 
 The `LaTeX Font Catalogue`_ provides information and examples for a wide
 range of fonts available for use with LaTeX. Here is just a selection:
@@ -864,39 +941,6 @@ d) PSNFSS_ Postscript fonts
        which is part of, e.g., `TeX Live`_.
 
 
-Example 1:
-  Use `Latin Modern`_. LaTeX code::
-
-    \usepackage{lmodern}
-
-  Command line argument::
-
-    --stylesheet=lmodern
-
-Example 2:
-  The _`Times/Helvetica/Courier` `PDF standard fonts`_ are
-  selected by the LaTeX code [#]_::
-
-    \usepackage{mathptmx}            % Times for serif and math
-    \usepackage[scaled=.90]{helvet}  % downscaled Helvetica for sans serif
-    \usepackage{courier}             % Courier for teletype (mono-space)
-
-  Since Docutils 0.7, this is the default value of the
-  `latex-preamble`_ option.
-
-.. [#] When generating PDF-files from LaTeX, the `PDF standard
-   fonts`_ do not need to be embedded in the document. While this
-   results in smaller files, the actually used fonts on screen and in
-   print might differ! (For details see, e.g., the testflow_ package
-   documentation.)
-
-
-Example 3:
-  Use the teletype font from the txfonts_ package. As there is no
-  package for this, we re-define the font macro with the LaTeX code::
-
-    \renewcommand{\ttdefault}{txtt}
-
 .. _LaTeX Font Catalogue:
    http://www.tug.dk/FontCatalogue/
 .. _Latin Modern:
@@ -917,6 +961,13 @@ Example 3:
    http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts
 .. _testflow:
    http://www.tex.ac.uk/tex-archive/help/Catalogue/entries/testflow.html
+.. _Good Libre Fonts:
+   http://typophile.com/node/18207
+.. _25 Best Free Quality Fonts:
+   http://www.alvit.de/blog/article/20-best-license-free-official-fonts
+.. _19 More Free Quality Fonts:
+   http://www.smashingmagazine.com/2006/10/11/17-more-free-quality-fonts/
+
 
 font encoding
 -------------
@@ -954,7 +1005,7 @@ Example 2:
 .. _encguide:
    http://mirror.ctan.org/macros/latex/doc/encguide.pdf
 .. _font-encoding:
-   ../user/config.html#font-encoding
+   config.html#font-encoding
 .. _fontenc:
    http://mirror.ctan.org/help/Catalogue/entries/fontenc.html
 
@@ -1078,9 +1129,9 @@ Example:
 See also `non-breaking hyperlinks`_.
 
 .. _hyperlink-color:
-   ../user/config.html#hyperlink-color
+   config.html#hyperlink-color
 .. _hyperref-options:
-   ../user/config.html#hyperref-options
+   config.html#hyperref-options
 
 
 disable hyperlinks
@@ -1177,7 +1228,7 @@ Example:
 
 __ ../ref/rst/restructuredtext.html#literal-blocks
 .. _literal-block-env:
-   ../user/config.html#literal-block-env
+   config.html#literal-block-env
 .. _listings.pdf:
     http://mirror.ctan.org/macros/latex/contrib/listings/listings.pdf
 
@@ -1400,7 +1451,7 @@ and can be configured in a LaTeX `style sheet`_, e.g.::
 .. note:: The LaTeX name is 'secnumdepth' (whithout 't').
 
 .. _sectnum directive: ../ref/rst/directives.html#sectnum
-.. _sectnum_xform: ../user/config.html#sectnum-xform
+.. _sectnum_xform: config.html#sectnum-xform
 
 
 sidebar
@@ -1553,7 +1604,7 @@ With use-latex-toc (default since release 0.6):
    This is an intended feature of the minitoc_ package. If you really
    require local ToCs at lower level, turn off the use-latex-toc_ option.
 
-.. _use-latex-toc: ../user/config.html#use-latex-toc
+.. _use-latex-toc: config.html#use-latex-toc
 .. _contents directive: ../ref/rst/directives.html#contents
 .. _minitoc:
    http://mirror.ctan.org/help/Catalogue/entries/minitoc.html
@@ -1624,7 +1675,7 @@ Note:
    (where *n* is the Unicode page-number) to the style sheet might help.
 
 .. _LaTeX Unicode: http://www.unruh.de/DniQ/latex/unicode/
-.. _output-encoding: ../user/config.html#output-encoding
+.. _output-encoding: config.html#output-encoding
 .. _inputenc:
    http://mirror.ctan.org/help/Catalogue/entries/inputenc.html
 .. _ucs:
@@ -1695,8 +1746,7 @@ Bad looking PDF output
   So am I just stupid or is there a way to get really high quality pdf from
   Docutils?
 
-Make sure the default font is not a bitmap font. Unfortunately, the
-default font is a bitmap font. You must change it.
+Make sure the default font is not a bitmap font.
 
 There is `Latin Modern`_ if you like the look of the standard font on paper,
 but want nice pdf. Or select something else like Times, Palatino, ... via
@@ -1764,10 +1814,10 @@ This can be solved with the "unicode" hyperref_option_ setting::
   --hyperref-option=unicode
 
 (works also with non-unicode input/output encoding (e.g. "koi8r" or
-"latin1"). However, this setting clashes with the XeTeX_ engine and is
+"latin1"). However, this setting does not work with xelatex_ and is
 therefore not made a default.
 
-.. _hyperref_option: ../user/config.html#stylesheet-latex2e-writer
+.. _hyperref_option: config.html#stylesheet-latex2e-writer
 
 
 image inclusion
@@ -1779,7 +1829,7 @@ supported file formats depend on the used driver:
 * Standard latex_ can include **only EPS** graphics, no other format.
 * `latex + dvipdfmx`_ works with EPS and JPG (add 'dvipdfmx' to the
   documentoptions_ and 'bmpsize' to the stylesheet_ setting).
-* pdflatex_ and xetex_ work with PNG, JPG, or PDF, but **not EPS**.
+* pdflatex_ and xelatex_ work with PNG, JPG, or PDF, but **not EPS**.
 
 If PDF-image inclusion in PDF files fails, specifying
 ``--graphicx-option=pdftex`` or ``--graphicx-option=auto`` might help.
@@ -1921,8 +1971,8 @@ only by a single space or a newline) are combined to a single citation
 group, i.e. ``[cite1]_ [cite2]_`` results in ``\cite{cite1,cite2}``.
 The appearance in the output can be configured in a `style sheet`_.
 
-.. _docutils-footnotes: ../user/config.html#docutils-footnotes
-.. _use-latex-citations: ../user/config.html#use-latex-citations
+.. _docutils-footnotes: config.html#docutils-footnotes
+.. _use-latex-citations: config.html#use-latex-citations
 
 
 Tables
diff --git a/docutils/docutils/writers/xetex/__init__.py b/docutils/docutils/writers/xetex/__init__.py
index 5d36290a0..46711c5b0 100644
--- a/docutils/docutils/writers/xetex/__init__.py
+++ b/docutils/docutils/writers/xetex/__init__.py
@@ -32,10 +32,10 @@ class Writer(latex2e.Writer):
 
     default_template = 'xelatex.tex'
     default_preamble = '\n'.join([
-        r'% PDF Standard Fonts',
-        r'\setmainfont{Times New Roman}',
-        r'\setsansfont[Scale=MatchLowercase]{Arial}',
-        r'\setmonofont[Scale=MatchLowercase,HyphenChar=None]{Courier New}',
+        r'% Linux Libertine (free, wide coverage, not only for Linux',
+        r'\setmainfont{Linux Libertine O}',
+        r'\setsansfont{Linux Biolinum O}',
+        r'\setmonofont[HyphenChar=None]{DejaVu Sans Mono}',
     ])
 
     config_section = 'xetex writer'
diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex
index 4fd635502..e64bae4de 100644
--- a/docutils/test/functional/expected/standalone_rst_latex.tex
+++ b/docutils/test/functional/expected/standalone_rst_latex.tex
@@ -1580,9 +1580,10 @@ not need to be tested with other writers (e.g. the HTML writer).
 %
 \begin{itemize}
 
-\item Role names and class arguments are converted to conform to the regular
-expression \texttt{{[}a-z{]}{[}-a-z0-9{]}*} (all non-conforming characters are replaced
-by a hyphen, all letters are downcased).
+\item Role names and class arguments are converted to conform to the
+regular expression \texttt{{[}a-z{]}{[}-a-z0-9{]}*} (letters are downcased,
+accents and similar decoration is stripped, non-conforming
+characters are replaced by a hyphen).
 
 Class arguments may contain numbers and hyphens, which need special
 treatment in LaTeX command names.
diff --git a/docutils/test/functional/expected/standalone_rst_xetex.tex b/docutils/test/functional/expected/standalone_rst_xetex.tex
index d78de0965..3c46ea5a4 100644
--- a/docutils/test/functional/expected/standalone_rst_xetex.tex
+++ b/docutils/test/functional/expected/standalone_rst_xetex.tex
@@ -2,6 +2,7 @@
 % generated by Docutils <http://docutils.sourceforge.net/>
 % rubber: set program xelatex
 \usepackage[no-sscript]{xltxtra} % loads fixltx2e, metalogo, xunicode, fontspec
+\defaultfontfeatures{Scale=MatchLowercase}
 \usepackage{ifthen}
 \usepackage{color}
 \usepackage{float} % float configuration
@@ -15,10 +16,10 @@
 \usepackage{tabularx}
 
 %%% Custom LaTeX preamble
-% PDF Standard Fonts
-\setmainfont{Times New Roman}
-\setsansfont[Scale=MatchLowercase]{Arial}
-\setmonofont[Scale=MatchLowercase,HyphenChar=None]{Courier New}
+% Linux Libertine (free, wide coverage, not only for Linux
+\setmainfont{Linux Libertine O}
+\setsansfont{Linux Biolinum O}
+\setmonofont[HyphenChar=None]{DejaVu Sans Mono}
 
 %%% User specified packages and stylesheets
 
@@ -354,7 +355,7 @@ Paragraphs contain text and may contain inline markup: \emph{emphasis},
 (\url{http://www.python.org}), external hyperlinks (\href{http://www.python.org/}{Python}\DUfootnotemark{id30}{id29}{5}), internal
 cross-references (\hyperref[example]{example}), external hyperlinks with embedded URIs
 (\href{http://www.python.org}{Python web site}), \href{http://www.python.org/}{anonymous hyperlink
-references}\DUfootnotemark{id33}{id29}{5} (\href{http://docutils.sourceforge.net/}{a second reference}\DUfootnotemark{id35}{id34}{6}), footnote references (manually
+references}\DUfootnotemark{id35}{id29}{5} (\href{http://docutils.sourceforge.net/}{a second reference}\DUfootnotemark{id37}{id36}{7}), footnote references (manually
 numbered\DUfootnotemark{id1}{id8}{1}, anonymous auto-numbered\DUfootnotemark{id2}{id12}{3}, labeled auto-numbered\DUfootnotemark{id3}{label}{2}, or symbolic\DUfootnotemark{id4}{id13}{*}), citation references ([\hyperlink{cit2002}{CIT2002}]),
 substitution references (\includegraphics{../../../docs/user/rst/images/biohazard.png}), and %
 \phantomsection\label{inline-hyperlink-targets}inline hyperlink targets
@@ -817,8 +818,8 @@ This footnote shows the next symbol in the sequence.
 \DUfootnotetext{id16}{id16}{4}{%
 Here's an unreferenced footnote, with a reference to a
 nonexistent footnote:%
-\raisebox{1em}{\hypertarget{id41}{}}%
-\raisebox{1em}{\hypertarget{id17}{}}\hyperlink{id40}{\textbf{\color{red}{[}5{]}\_}}.
+\raisebox{1em}{\hypertarget{id43}{}}%
+\raisebox{1em}{\hypertarget{id17}{}}\hyperlink{id42}{\textbf{\color{red}{[}5{]}\_}}.
 }
 
 
@@ -835,8 +836,8 @@ rendered separately and differently from footnotes.
 \end{figure}
 
 Here's a reference to the above, [\hyperlink{cit2002}{CIT2002}], and a %
-\raisebox{1em}{\hypertarget{id43}{}}%
-\raisebox{1em}{\hypertarget{id19}{}}\hyperlink{id42}{\textbf{\color{red}{[}nonexistent{]}\_}}
+\raisebox{1em}{\hypertarget{id45}{}}%
+\raisebox{1em}{\hypertarget{id19}{}}\hyperlink{id44}{\textbf{\color{red}{[}nonexistent{]}\_}}
 citation.
 
 
@@ -864,7 +865,7 @@ Targets may be indirect and anonymous.  Thus \hyperref[targets]{this phrase} may
 refer to the \hyperref[targets]{Targets} section.
 
 Here's a %
-\raisebox{1em}{\hypertarget{id45}{}}\hyperlink{id44}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an
+\raisebox{1em}{\hypertarget{id47}{}}\hyperlink{id46}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an
 error.
 
 
@@ -892,7 +893,7 @@ explicit targets will generate "warning" (level-2) system messages.
 Since there are two "Duplicate Target Names" section headers, we
 cannot uniquely refer to either of them by name.  If we try to (like
 this: %
-\raisebox{1em}{\hypertarget{id47}{}}\hyperlink{id46}{\textbf{\color{red}`Duplicate Target Names`\_}}), an error is generated.
+\raisebox{1em}{\hypertarget{id49}{}}\hyperlink{id48}{\textbf{\color{red}`Duplicate Target Names`\_}}), an error is generated.
 
 
 %___________________________________________________________________________
@@ -1195,11 +1196,15 @@ allowed (e.g. inside a directive).
 \url{http://www.python.org/}
 }
 %
-\DUfootnotetext{id34}{id35}{6}{%
-\url{http://docutils.sourceforge.net/}
+\DUfootnotetext{id33}{id34}{6}{%
+\url{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia}
 }
 %
 \DUfootnotetext{id36}{id37}{7}{%
+\url{http://docutils.sourceforge.net/}
+}
+%
+\DUfootnotetext{id38}{id39}{8}{%
 \url{A:DOS\\path\\}
 }
 
@@ -1579,9 +1584,10 @@ not need to be tested with other writers (e.g. the HTML writer).
 %
 \begin{itemize}
 
-\item Role names and class arguments are converted to conform to the regular
-expression \texttt{{[}a-z{]}{[}-a-z0-9{]}*} (all non-conforming characters are replaced
-by a hyphen, all letters are downcased).
+\item Role names and class arguments are converted to conform to the
+regular expression \texttt{{[}a-z{]}{[}-a-z0-9{]}*} (letters are downcased,
+accents and similar decoration is stripped, non-conforming
+characters are replaced by a hyphen).
 
 Class arguments may contain numbers and hyphens, which need special
 treatment in LaTeX command names.
@@ -2264,7 +2270,7 @@ Handling by the LaTeX writer:
 \url{http://www.w3.org/XML/Schema\#dev}
 \item[] \href{http://www.w3.org/XML/Schema\%dev}{URL with \%}
 \url{http://example.org/Schema\%dev}
-\item[] \href{A:DOS\\path\\}{file with DOS path}\DUfootnotemark{id37}{id36}{7} \url{A:DOS\\path\\}\DUfootnotemark{id38}{id36}{7}
+\item[] \href{A:DOS\\path\\}{file with DOS path}\DUfootnotemark{id39}{id38}{8} \url{A:DOS\\path\\}\DUfootnotemark{id40}{id38}{8}
 \end{DUlineblock}
 
 \DUadmonition[note]{
@@ -2275,7 +2281,7 @@ These URLs are typeset inside a LaTeX command without error.
 \begin{DUlineblock}{0em}
 \item[] \url{http://www.w3.org/XML/Schema\#dev}
 \item[] \url{http://example.org/Schema\%dev}
-\item[] \url{A:DOS\\path\\}\DUfootnotemark{id39}{id36}{7}
+\item[] \url{A:DOS\\path\\}\DUfootnotemark{id41}{id38}{8}
 \end{DUlineblock}
 }
 
@@ -2307,17 +2313,33 @@ while balanced braces are suported:
 
 \end{itemize}
 
-% unusual combinations (from newlatex, for interactive testing)
-% .. include:: data/latex.txt
+
+%___________________________________________________________________________
+
+\section*{4   Tests for the XeTeX writer%
+  \phantomsection%
+  \addcontentsline{toc}{section}{4   Tests for the XeTeX writer}%
+  \label{tests-for-the-xetex-writer}%
+}
+
+With XeTeX, you can typeset text in any language/script supported by
+Unicode and the selected font, e.g. Azərbaycanca, Bân-lâm-gú, Башҡорт
+Беларуская, Български, Català, Чӑвашла, Česky, Ελληνικά, Español,
+Français, Føroyskt, Хальмг, Íslenska, עברית , Қазақша, Kurdî,
+Latviešu, Lietuvių, Македонски, Монгол, Nāhuatl, Português, Română,
+Русский, Slovenščina, Српски, Türkçe, Українська, Tiếng Việt, Volapük,
+Võro, ייִדיש , Žemaitėška.
+Currently, there is extended support for 28 languages in the
+\href{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia}{polyglossia}\DUfootnotemark{id34}{id33}{6} package.
 
 % System Messages:
 
 
 %___________________________________________________________________________
 
-\section*{4   Error Handling%
+\section*{5   Error Handling%
   \phantomsection%
-  \addcontentsline{toc}{section}{4   Error Handling}%
+  \addcontentsline{toc}{section}{5   Error Handling}%
   \label{error-handling}%
 }
 
@@ -2348,41 +2370,41 @@ Undefined substitution referenced: "problematic".
 
 \DUadmonition[system-message]{
 \DUtitle[system-message]{system-message}
-\raisebox{1em}{\hypertarget{id40}{}}
+\raisebox{1em}{\hypertarget{id42}{}}
 
 {\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~361
 
-\hyperlink{id41}{
+\hyperlink{id43}{
 Unknown target name: "5".
 }}
 
 \DUadmonition[system-message]{
 \DUtitle[system-message]{system-message}
-\raisebox{1em}{\hypertarget{id42}{}}
+\raisebox{1em}{\hypertarget{id44}{}}
 
 {\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~370
 
-\hyperlink{id43}{
+\hyperlink{id45}{
 Unknown target name: "nonexistent".
 }}
 
 \DUadmonition[system-message]{
 \DUtitle[system-message]{system-message}
-\raisebox{1em}{\hypertarget{id44}{}}
+\raisebox{1em}{\hypertarget{id46}{}}
 
 {\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~397
 
-\hyperlink{id45}{
+\hyperlink{id47}{
 Unknown target name: "hyperlink reference without a target".
 }}
 
 \DUadmonition[system-message]{
 \DUtitle[system-message]{system-message}
-\raisebox{1em}{\hypertarget{id46}{}}
+\raisebox{1em}{\hypertarget{id48}{}}
 
 {\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~410
 
-\hyperlink{id47}{
+\hyperlink{id49}{
 Duplicate target name, cannot be used as a unique reference: "duplicate target names".
 }}
 
diff --git a/docutils/test/functional/input/data/custom_roles_latex.txt b/docutils/test/functional/input/data/custom_roles_latex.txt
index b1b69d25b..88c0a370c 100644
--- a/docutils/test/functional/input/data/custom_roles_latex.txt
+++ b/docutils/test/functional/input/data/custom_roles_latex.txt
@@ -1,9 +1,10 @@
 Custom Roles in LaTeX
 ---------------------
 
-* Role names and class arguments are converted to conform to the regular
-  expression ``[a-z][-a-z0-9]*`` (all non-conforming characters are replaced
-  by a hyphen, all letters are downcased).
+* Role names and class arguments are converted to conform to the
+  regular expression ``[a-z][-a-z0-9]*`` (letters are downcased,
+  accents and similar decoration is stripped, non-conforming
+  characters are replaced by a hyphen).
 
   Class arguments may contain numbers and hyphens, which need special
   treatment in LaTeX command names.
diff --git a/docutils/test/functional/input/standalone_rst_xetex.txt b/docutils/test/functional/input/standalone_rst_xetex.txt
index b566b793e..3ce341b3d 100644
--- a/docutils/test/functional/input/standalone_rst_xetex.txt
+++ b/docutils/test/functional/input/standalone_rst_xetex.txt
@@ -18,8 +18,22 @@ not need to be tested with other writers (e.g. the HTML writer).
 .. include:: data/latex_encoding.txt
 .. include:: data/hyperlinking.txt
 .. include:: data/urls.txt
-.. unusual combinations (from newlatex, for interactive testing)
-   .. include:: data/latex.txt
+
+Tests for the XeTeX writer
+==========================
+
+With XeTeX, you can typeset text in any language/script supported by
+Unicode and the selected font, e.g. Azərbaycanca, Bân-lâm-gú, Башҡорт
+Беларуская, Български, Català, Чӑвашла, Česky, Ελληνικά, Español,
+Français, Føroyskt, Хальмг, Íslenska, עברית , Қазақша, Kurdî,
+Latviešu, Lietuvių, Македонски, Монгол, Nāhuatl, Português, Română,
+Русский, Slovenščina, Српски, Türkçe, Українська, Tiếng Việt, Volapük,
+Võro, ייִדיש , Žemaitėška.
+Currently, there is extended support for 28 languages in the
+polyglossia_ package.
+
+.. _polyglossia:
+   http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia
 
 .. System Messages:
 .. include:: data/errors.txt