From 2825e338c250ba8e089b53e8d0c1a644aae8a29f Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 15 Nov 2018 18:04:11 +0100 Subject: [PATCH 1/5] LaTeX: support for Greek and Cyrillic 0. do not escape Unicode Greek letters via LaTeX math mark-up: pass them through un-modified to LaTeX document, 1. if "fontenc" receives extra option LGR, then pdflatex will support Unicode Greek letters (not in math), and with extra option T2A it will support (most) Unicode Cyrillic letters. 2. for pdflatex with LGR, this will use "textalpha" LaTeX package and "substitutefont" package to set up some automatic font substitution to work around the unavailability of Greek with "times" package (which is default font package chosen by Sphinx for pdflatex), same with T2A and "substitutefont" for Cyrillic. 3. for xelatex/lualatex, set up Computer Modern Unicode as default font, as it supports Cyrillic and Greek scripts, 4. for platex, don't do anything special as the engine already has its default font supporting Cyrillic and Greek (even in math mode!) Closes: #5251 Fixes: #5248 Fixes: #5247 --- CHANGES | 49 +++++++++++++- doc/conf.py | 7 ++ doc/usage/builders/index.rst | 2 + doc/usage/configuration.rst | 103 ++++++++++++++++++++++++++--- sphinx/templates/latex/latex.tex_t | 2 + sphinx/texinputs/sphinx.sty | 24 +++++++ sphinx/texinputs/sphinx.xdy | 89 +++++++++++++++---------- sphinx/util/texescape.py | 52 +-------------- sphinx/writers/latex.py | 68 ++++++++++++++----- tests/test_markup.py | 4 +- 10 files changed, 287 insertions(+), 113 deletions(-) diff --git a/CHANGES b/CHANGES index 45c176ac145..7ff4978efc9 100644 --- a/CHANGES +++ b/CHANGES @@ -4,7 +4,41 @@ Release 2.0.0 (in development) Dependencies ------------ -* LaTeX builder now depends on TeX Live 2015 or above +* LaTeX builder now depends on TeX Live 2015 or above. +* LaTeX builder may need these additional LaTeX packages for PDF builds + (with ``'pdflatex'`` :confval:`latex_engine`): + + .. list-table:: Requirements + :header-rows: 1 + + * - LaTeX package (CTAN) + - Ubuntu xenial + - needed for + * - substitutefont + - texlive-latex-extra + - Greek or Cyrillic letters (in non-Cyrillic documents) + * - textalpha + - texlive-lang-greek + - Greek letters (in text, not math) + * - gfsartemisia + - fonts-gfs-artemisia (texlive-fonts-extra) + - Greek letters (in text, not math) + * - gfsneohellenic + - fonts-gfs-neohellenic (texlive-fonts-extra) + - Greek letters (in text, not math) + * - cbfonts + - texlive-lang-greek + - Greek letters (in text, not math) + * - cm-lgc + - texlive-fonts-extra + - Cyrillic letters (in non-Cyrillic documents) + + These extra package are not required by default. The first two are needed if + the :confval:`latex_elements`.\ ``'fontenc'`` key has been modify to declare + the use of the ``LGR`` (Greek) and/or ``T2A`` (Cyrillic) font encoding. Even + then, the last four are font packages arising in the default value for + :confval:`latex_elements`.\ ``'fontpkg'``, and may be replaced by other font + packages providing ``LGR`` and/or ``T2A`` support. Incompatible changes -------------------- @@ -15,6 +49,11 @@ Incompatible changes has been longly used as default of sphinx-quickstart. * LaTeX: Move message resources to ``sphinxmessage.sty`` * LaTeX: Stop using ``\captions`` macro for some labels +* LaTeX: Greek letters in text are not escaped to math mode mark-up, and they + will use the text font not the math font. If (and only if) the document + contains such Greek Unicode letters *and* the :confval:`latex_engine` is + ``'pdflatex'`` then the :confval:`latex_elements`.\ ``'fontenc'`` key + **must** be used to declare usage of the ``LGR`` font encoding. Deprecated ---------- @@ -58,10 +97,18 @@ __ https://github.com/sphinx-contrib/sphinx-pretty-searchresults * #4018: htmlhelp: Add :confval:`htmlhelp_file_suffix` and :confval:`htmlhelp_link_suffix` * #5559: text: Support complex tables (colspan and rowspan) +* LaTeX: support rendering (not in math, yet) of Greek and Cyrillic Unicode + letters in non-Cyrillic document even with ``'pdflatex'`` as + :confval:`latex_engine` Bugs fixed ---------- +* #5247: LaTeX: PDF does not build with default font config for Russian + language and ``'xelatex'`` or ``'lualatex'`` as :confval:`latex_engine` + (refs: #5251) +* #5248: LaTeX: Greek letters in section titles disappear from PDF bookmarks + Testing -------- diff --git a/doc/conf.py b/doc/conf.py index e06d7015025..661efb4348d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -56,10 +56,17 @@ 'Georg Brandl', 'manual', 1)] latex_logo = '_static/sphinx.png' latex_elements = { + 'fontenc': r'\usepackage[LGR,T2A,T1]{fontenc}', 'fontpkg': r''' \usepackage[sc]{mathpazo} \usepackage[scaled]{helvet} \usepackage{courier} +\substitutefont{LGR}{\rmdefault}{udidot} +\substitutefont{LGR}{\sfdefault}{neohellenic} +\substitutefont{LGR}{\ttdefault}{cmtt} +\substitutefont{T2A}{\rmdefault}{fcm} +\substitutefont{T2A}{\sfdefault}{fcs} +\substitutefont{T2A}{\ttdefault}{fct} ''', 'passoptionstopackages': '\\PassOptionsToPackage{svgnames}{xcolor}', 'preamble': '\\DeclareUnicodeCharacter{229E}{\\ensuremath{\\boxplus}}', diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index e7ad13bd163..3f16c84e507 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -164,6 +164,8 @@ The builder's "name" must be given to the **-b** command-line option of * ``texlive-latex-recommended`` * ``texlive-fonts-recommended`` * ``texlive-latex-extra`` + * ``texlive-fonts-extra``, ``texlive-lang-greek`` (if needed to + support Greek or Cyrillic letters in non-cyrillic document) * ``latexmk`` (for ``make latexpdf`` on GNU/Linux and MacOS X) * ``texlive-luatex``, ``texlive-xetex`` (see :confval:`latex_engine`) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index f64ec73bcf1..765431fe28d 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2043,17 +2043,48 @@ information. ``babel``, not ``polyglossia``. ``'fontpkg'`` - Font package inclusion, default ``'\\usepackage{times}'`` (which uses - Times for text, Helvetica for sans serif and Courier for code-blocks). + Font package inclusion, the default is ``'\\usepackage{times}'`` which + uses Times for text, Helvetica for sans serif and Courier for monospace. .. versionchanged:: 1.2 Defaults to ``''`` when the :confval:`language` uses the Cyrillic script. - .. versionchanged:: 1.5 - Defaults to ``''`` when :confval:`latex_engine` is ``'xelatex'``. - .. versionchanged:: 1.6 - Defaults to ``''`` also with ``'lualatex'``. - + .. versionchanged:: 2.0 + Support for individual Greek and Cyrillic letters: + + - In order to support occasional Cyrillic (физика частиц) + or Greek letters (Σωματιδιακή φυσική) in + a document whose language is English or a Latin European + one, the default set-up is enhanced (only for ``'pdflatex'`` + engine) to do: + + .. code-block:: latex + + \substitutefont{LGR}{\rmdefault}{artemisia} + \substitutefont{LGR}{\sfdefault}{neohellenic} + \substitutefont{LGR}{\ttdefault}{cmtt} + \substitutefont{T2A}{\rmdefault}{fcm} + \substitutefont{T2A}{\sfdefault}{fcs} + \substitutefont{T2A}{\ttdefault}{fct} + + For this however, the ``'fontenc'`` key must be used to tell + LaTeX to load the ``LGR`` (Greek) or ``T2A`` (partial Cyrillic) + font encoding. If ``'fontenc'`` is not modified the above lines + are not executed. + + In a custom ``'fontpkg'`` setting, do not use ``\substitutefont`` + with a font encoding not also declared via ``'fontenc'``. + + - For ``'xelatex'`` and ``'lualatex'``, the default is + ``'\\setmainfont{CMU Serif}'`` (and similar for sans + serif and monospace) . This OpenType font family supports + both Cyrillic and Greek scripts (contrarily to the + default font configured by LaTeX for ``xelatex/lualatex`` + if ``'fontpkg'`` is left to empty string, as was the case + prior to 2.0). + + - ``'platex'`` (Japanese documents) engine supports individual + Cyrillic and Greek letters with no need of extra user set-up. ``'fncychap'`` Inclusion of the "fncychap" package (which makes fancy chapter titles), default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation @@ -2130,13 +2161,69 @@ information. .. versionadded:: 1.2 ``'fontenc'`` - "fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``. + "fontenc" package inclusion, defaults to + ``'\\usepackage[T1]{fontenc}'``. .. versionchanged:: 1.5 Defaults to ``'\\usepackage{fontspec}'`` when :confval:`latex_engine` is ``'xelatex'``. .. versionchanged:: 1.6 ``'lualatex'`` also uses ``fontspec`` per default. + .. versionchanged:: 2.0 + With ``'pdflatex'`` you can add ``LGR`` and/or ``T2A`` + (before ``T1`` which should remain the last) to trigger + automatic support of occasional Greek and Cyrillic letters + in text. + + .. attention:: + + Prior to 2.0, Unicode Greek letters were escaped to use LaTeX + math mark-up. This is not the case anymore so it may be needed + to modify this key into ``'\\usepackage[LGR,T1]{fontenc}'`` and + also to make sure to have the suitable Greek font packages + as listed in :doc:`../changes` (or replacements). + + ``'textgreek'`` + The default (``'pdflatex'`` only) is + ``'\\usepackage{textalpha}'``, but only if ``'fontenc'`` was + modified by user to include ``LGR`` option. If not, the key + value will be forced to be empty string. + + This is needed for ``pdfLaTeX`` to support Unicode input of Greek + letters such as φύσις. Expert users may want to load the ``textalpha`` + package with its option ``normalize-symbols``. + + .. note:: + + - Unicode Greek letters in text were, prior to release 2.0, escaped + to LaTeX math markup in the produced LaTeX file, hence their + rendering in PDF used the math font. They are now copied over + unmodified to the LaTeX file and rendered in PDF by the text + font. But the ``LGR`` font encoding must be loaded. + + - Unicode Greek letters are not accepted in :rst:dir:`math` + contents. LaTeX math mark-up ``\alpha`` etc..., must be used + there. + + - With ``'xelatex'`` or ``'lualatex'``, this is ignored as the + support for Unicode Greek letters comes from using an OpenType + font which supports the Greek script. This is the case (since + 2.0) with the default fonts used by Sphinx for these engines. + + Besides, Unicode input in math (not only Greek symbols) can be + obtained by adding ``\usepackage{unicode-math}`` to the LaTeX + preamble (and perhaps use ``\setmathfont`` to switch to some + other OpenMath font than the XeLaTeX default). Then one can use + ``:math:`α=\alpha``` input. But take note that + ``\usepackage[math-style=literal]{unicode-math}`` is needed to + obtain in PDF similar output as in HTML+MathJaX, i.e. the ``α`` + remains upright, and the ``\alpha`` gives an italic letter. + + - With ``platex`` (Japanese), this key setting is ignored: + Greek (and Cyrillic) letters are handled natively by the engine + own default fonts. + + .. versionadded:: 2.0 ``'geometry'`` "geometry" package inclusion, the default definition is: diff --git a/sphinx/templates/latex/latex.tex_t b/sphinx/templates/latex/latex.tex_t index e75a9e8ce18..06b94b0f2bd 100644 --- a/sphinx/templates/latex/latex.tex_t +++ b/sphinx/templates/latex/latex.tex_t @@ -26,7 +26,9 @@ <%= fontenc %> <%= amsmath %> <%= multilingual %> +<%= substitutefont %> <%= fontpkg %> +<%= textgreek %> <%= fncychap %> \usepackage<%= sphinxpkgoptions %>{sphinx} <%= sphinxsetup %> diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 249f2ece070..5aa1d586ae8 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -247,6 +247,8 @@ \DeclareStringOption[\inv@mag in]{vmargin} \DeclareStringOption[.5\dimexpr\inv@mag in\relax]{marginpar} \fi +% Allow Cyrillic letters in non-Cyrillic document (needed for pdflatex only) +\DeclareBoolOption[false]{cyrnocyr} \DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0} \DeclareStringOption[-1]{numfigreset} @@ -361,6 +363,28 @@ \newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}} +%% CYRILLIC IN NON-CYRILLIC DOCUMENTS (pdflatex only) +% +% refs: https://tex.stackexchange.com/q/460271/4686 +% +\ifspx@opt@cyrnocyr + \@tfor\@tempa:=% + {ae}{a}{b}{chrdsc}{chvcrs}{ch}{c}{dje}{dze}{dzhe}{d}{erev}{ery}{e}% + {f}{ghcrs}{gup}{g}{hdsc}{hrdsn}{h}{ie}{ii}{ishrt}{i}{je}% + {kbeak}{kdsc}{kvcrs}{k}{lje}{l}{m}{ndsc}{ng}{nje}{n}{otld}{o}{p}{r}% + {schwa}{sdsc}{sftsn}{shch}{shha}{sh}{s}{tshe}{t}{ushrt}{u}{v}% + {ya}{yhcrs}{yi}{yo}{yu}{y}{zdsc}{zhdsc}{zh}{z}\do + {% + \expandafter\DeclareTextSymbolDefault\expandafter + {\csname cyr\@tempa\endcsname}{T2A}% + \expandafter\uppercase\expandafter{\expandafter + \def\expandafter\@tempa\expandafter{\@tempa}}% + \expandafter\DeclareTextSymbolDefault\expandafter + {\csname CYR\@tempa\endcsname}{T2A}% + }% + \DeclareTextSymbolDefault{\CYRpalochka}{T2A}% +\fi + %% MAXLISTDEPTH % % remove LaTeX's cap on nesting depth if 'maxlistdepth' key used. diff --git a/sphinx/texinputs/sphinx.xdy b/sphinx/texinputs/sphinx.xdy index 0d02ef3372a..1c0794cd91d 100644 --- a/sphinx/texinputs/sphinx.xdy +++ b/sphinx/texinputs/sphinx.xdy @@ -147,40 +147,61 @@ (merge-rule "\(\sb{\text{7}}\)" "₇" :string) (merge-rule "\(\sb{\text{8}}\)" "₈" :string) (merge-rule "\(\sb{\text{9}}\)" "₉" :string) -(merge-rule "\(\alpha\)" "α" :string) -(merge-rule "\(\beta\)" "β" :string) -(merge-rule "\(\gamma\)" "γ" :string) -(merge-rule "\(\delta\)" "δ" :string) -(merge-rule "\(\epsilon\)" "ε" :string) -(merge-rule "\(\zeta\)" "ζ" :string) -(merge-rule "\(\eta\)" "η" :string) -(merge-rule "\(\theta\)" "θ" :string) -(merge-rule "\(\iota\)" "ι" :string) -(merge-rule "\(\kappa\)" "κ" :string) -(merge-rule "\(\lambda\)" "λ" :string) -(merge-rule "\(\mu\)" "μ" :string) -(merge-rule "\(\nu\)" "ν" :string) -(merge-rule "\(\xi\)" "ξ" :string) -(merge-rule "\(\pi\)" "π" :string) -(merge-rule "\(\rho\)" "ρ" :string) -(merge-rule "\(\sigma\)" "σ" :string) -(merge-rule "\(\tau\)" "τ" :string) -(merge-rule "\(\upsilon\)" "υ" :string) -(merge-rule "\(\phi\)" "φ" :string) -(merge-rule "\(\chi\)" "χ" :string) -(merge-rule "\(\psi\)" "ψ" :string) -(merge-rule "\(\omega\)" "ω" :string) -(merge-rule "\(\Gamma\)" "Γ" :string) -(merge-rule "\(\Delta\)" "Δ" :string) -(merge-rule "\(\Theta\)" "Θ" :string) -(merge-rule "\(\Lambda\)" "Λ" :string) -(merge-rule "\(\Xi\)" "Ξ" :string) -(merge-rule "\(\Pi\)" "Π" :string) -(merge-rule "\(\Sigma\)" "Σ" :string) -(merge-rule "\(\Upsilon\)" "Υ" :string) -(merge-rule "\(\Phi\)" "Φ" :string) -(merge-rule "\(\Psi\)" "Ψ" :string) -(merge-rule "\(\Omega\)" "Ω" :string) +(merge-rule "\IeC {\textalpha }" "α" :string) +(merge-rule "\IeC {\textbeta }" "β" :string) +(merge-rule "\IeC {\textgamma }" "γ" :string) +(merge-rule "\IeC {\textdelta }" "δ" :string) +(merge-rule "\IeC {\textepsilon }" "ε" :string) +(merge-rule "\IeC {\textzeta }" "ζ" :string) +(merge-rule "\IeC {\texteta }" "η" :string) +(merge-rule "\IeC {\texttheta }" "θ" :string) +(merge-rule "\IeC {\textiota }" "ι" :string) +(merge-rule "\IeC {\textkappa }" "κ" :string) +(merge-rule "\IeC {\textlambda }" "λ" :string) +(merge-rule "\IeC {\textmu }" "μ" :string) +(merge-rule "\IeC {\textnu }" "ν" :string) +(merge-rule "\IeC {\textxi }" "ξ" :string) +(merge-rule "\IeC {\textomicron }" "ο" :string) +(merge-rule "\IeC {\textpi }" "π" :string) +(merge-rule "\IeC {\textrho }" "ρ" :string) +(merge-rule "\IeC {\textsigma }" "σ" :string) +(merge-rule "\IeC {\texttau }" "τ" :string) +(merge-rule "\IeC {\textupsilon }" "υ" :string) +(merge-rule "\IeC {\textphi }" "φ" :string) +(merge-rule "\IeC {\textchi }" "χ" :string) +(merge-rule "\IeC {\textpsi }" "ψ" :string) +(merge-rule "\IeC {\textomega }" "ω" :string) +(merge-rule "\IeC {\textAlpha }" "Α" :string) +(merge-rule "\IeC {\textBeta }" "Β" :string) +(merge-rule "\IeC {\textGamma }" "Γ" :string) +(merge-rule "\IeC {\textDelta }" "Δ" :string) +(merge-rule "\IeC {\textEpsilon }" "Ε" :string) +(merge-rule "\IeC {\textZeta }" "Ζ" :string) +(merge-rule "\IeC {\textEta }" "Η" :string) +(merge-rule "\IeC {\textTheta }" "Θ" :string) +(merge-rule "\IeC {\textIota }" "Ι" :string) +(merge-rule "\IeC {\textKappa }" "Κ" :string) +(merge-rule "\IeC {\textLambda }" "Λ" :string) +(merge-rule "\IeC {\textMu }" "Μ" :string) +(merge-rule "\IeC {\textNu }" "Ν" :string) +(merge-rule "\IeC {\textTheta }" "Θ" :string) +(merge-rule "\IeC {\textIota }" "Ι" :string) +(merge-rule "\IeC {\textKappa }" "Κ" :string) +(merge-rule "\IeC {\textLambda }" "Λ" :string) +(merge-rule "\IeC {\textMu }" "Μ" :string) +(merge-rule "\IeC {\textNu }" "Ν" :string) +(merge-rule "\IeC {\textXi }" "Ξ" :string) +(merge-rule "\IeC {\textOmicron }" "Ο" :string) +(merge-rule "\IeC {\textPi }" "Π" :string) +(merge-rule "\IeC {\textRho }" "Ρ" :string) +(merge-rule "\IeC {\textSigma }" "Σ" :string) +(merge-rule "\IeC {\textTau }" "Τ" :string) +(merge-rule "\IeC {\textUpsilon }" "Υ" :string) +(merge-rule "\IeC {\textPhi }" "Φ" :string) +(merge-rule "\IeC {\textChi }" "Χ" :string) +(merge-rule "\IeC {\textPsi }" "Ψ" :string) +(merge-rule "\IeC {\textOmega }" "Ω" :string) +(merge-rule "\IeC {\textohm }" "Ω" :string) ;; This xindy module provides some basic support for "see" (require "makeindex.xdy") diff --git a/sphinx/util/texescape.py b/sphinx/util/texescape.py index 0f1783defc5..4ce2cfff8d1 100644 --- a/sphinx/util/texescape.py +++ b/sphinx/util/texescape.py @@ -69,56 +69,8 @@ ('₇', r'\(\sb{\text{7}}\)'), ('₈', r'\(\sb{\text{8}}\)'), ('₉', r'\(\sb{\text{9}}\)'), - # map Greek alphabet - ('α', r'\(\alpha\)'), - ('β', r'\(\beta\)'), - ('γ', r'\(\gamma\)'), - ('δ', r'\(\delta\)'), - ('ε', r'\(\epsilon\)'), - ('ζ', r'\(\zeta\)'), - ('η', r'\(\eta\)'), - ('θ', r'\(\theta\)'), - ('ι', r'\(\iota\)'), - ('κ', r'\(\kappa\)'), - ('λ', r'\(\lambda\)'), - ('μ', r'\(\mu\)'), - ('ν', r'\(\nu\)'), - ('ξ', r'\(\xi\)'), - ('ο', r'o'), - ('π', r'\(\pi\)'), - ('ρ', r'\(\rho\)'), - ('σ', r'\(\sigma\)'), - ('τ', r'\(\tau\)'), - ('υ', '\\(\\upsilon\\)'), - ('φ', r'\(\phi\)'), - ('χ', r'\(\chi\)'), - ('ψ', r'\(\psi\)'), - ('ω', r'\(\omega\)'), - ('Α', r'A'), - ('Β', r'B'), - ('Γ', r'\(\Gamma\)'), - ('Δ', r'\(\Delta\)'), - ('Ε', r'E'), - ('Ζ', r'Z'), - ('Η', r'H'), - ('Θ', r'\(\Theta\)'), - ('Ι', r'I'), - ('Κ', r'K'), - ('Λ', r'\(\Lambda\)'), - ('Μ', r'M'), - ('Ν', r'N'), - ('Ξ', r'\(\Xi\)'), - ('Ο', r'O'), - ('Π', r'\(\Pi\)'), - ('Ρ', r'P'), - ('Σ', r'\(\Sigma\)'), - ('Τ', r'T'), - ('Υ', '\\(\\Upsilon\\)'), - ('Φ', r'\(\Phi\)'), - ('Χ', r'X'), - ('Ψ', r'\(\Psi\)'), - ('Ω', r'\(\Omega\)'), - ('Ω', r'\(\Omega\)'), + # Greek alphabet not escaped: pdflatex handles it via textalpha and inputenc + # OHM SIGN U+2126 is handled by LaTeX textcomp package ] tex_escape_map = {} # type: Dict[int, unicode] diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 207f7513a29..f1e3b7e988e 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -64,6 +64,23 @@ 'lowerroman': r'\roman', 'upperroman': r'\Roman', }) # type: Dict[unicode, unicode] +PDFLATEX_DEFAULT_FONT_PKG = r''' +\usepackage{times} +\expandafter\ifx\csname T@LGR\endcsname\relax +\else +% LGR was declared as font encoding + \substitutefont{LGR}{\rmdefault}{artemisia} % gfsartemisia + \substitutefont{LGR}{\sfdefault}{neohellenic} % gfsneohellenic + \substitutefont{LGR}{\ttdefault}{cmtt} % cbfonts +\fi +\expandafter\ifx\csname T@T2A\endcsname\relax +\else +% T2A was declared as font encoding + \substitutefont{T2A}{\rmdefault}{fcm} + \substitutefont{T2A}{\sfdefault}{fcs} + \substitutefont{T2A}{\ttdefault}{fct} +\fi +''' DEFAULT_SETTINGS = { 'latex_engine': 'pdflatex', @@ -86,7 +103,9 @@ 'multilingual': '', 'babel': '\\usepackage{babel}', 'polyglossia': '', - 'fontpkg': '\\usepackage{times}', + 'fontpkg': PDFLATEX_DEFAULT_FONT_PKG, + 'substitutefont': '', + 'textgreek': '\\usepackage{textalpha}', 'fncychap': '\\usepackage[Bjarne]{fncychap}', 'hyperref': ('% Include hyperref last.\n' '\\usepackage{hyperref}\n' @@ -121,21 +140,17 @@ 'inputenc': '\\usepackage[utf8]{inputenc}', 'utf8extra': ('\\ifdefined\\DeclareUnicodeCharacter\n' '% support both utf8 and utf8x syntaxes\n' - '\\edef\\sphinxdqmaybe{' - '\\ifdefined\\DeclareUnicodeCharacterAsOptional' - '\\string"\\fi}\n' - ' \\DeclareUnicodeCharacter{\\sphinxdqmaybe00A0}' - '{\\nobreakspace}\n' - ' \\DeclareUnicodeCharacter{\\sphinxdqmaybe2500}' - '{\\sphinxunichar{2500}}\n' - ' \\DeclareUnicodeCharacter{\\sphinxdqmaybe2502}' - '{\\sphinxunichar{2502}}\n' - ' \\DeclareUnicodeCharacter{\\sphinxdqmaybe2514}' - '{\\sphinxunichar{2514}}\n' - ' \\DeclareUnicodeCharacter{\\sphinxdqmaybe251C}' - '{\\sphinxunichar{251C}}\n' - ' \\DeclareUnicodeCharacter{\\sphinxdqmaybe2572}' - '{\\textbackslash}\n' + ' \\ifdefined\\DeclareUnicodeCharacterAsOptional\n' + ' \\def\\sphinxDUC#1{\\DeclareUnicodeCharacter{"#1}}\n' + ' \\else\n' + ' \\let\\sphinxDUC\\DeclareUnicodeCharacter\n' + ' \\fi\n' + ' \\sphinxDUC{00A0}{\\nobreakspace}\n' + ' \\sphinxDUC{2500}{\\sphinxunichar{2500}}\n' + ' \\sphinxDUC{2502}{\\sphinxunichar{2502}}\n' + ' \\sphinxDUC{2514}{\\sphinxunichar{2514}}\n' + ' \\sphinxDUC{251C}{\\sphinxunichar{251C}}\n' + ' \\sphinxDUC{2572}{\\textbackslash}\n' '\\fi'), }, 'xelatex': { @@ -143,7 +158,10 @@ 'polyglossia': '\\usepackage{polyglossia}', 'babel': '', 'fontenc': '\\usepackage{fontspec}', - 'fontpkg': '', + 'fontpkg': ('\\setmainfont{CMU Serif}\n' + '\\setsansfont{CMU Sans Serif}\n' + '\\setmonofont{CMU Typewriter Text}'), + 'textgreek': '', 'utf8extra': ('\\catcode`^^^^00a0\\active\\protected\\def^^^^00a0' '{\\leavevmode\\nobreak\\ }'), 'fvset': '\\fvset{fontsize=auto}', @@ -153,7 +171,10 @@ 'polyglossia': '\\usepackage{polyglossia}', 'babel': '', 'fontenc': '\\usepackage{fontspec}', - 'fontpkg': '', + 'fontpkg': ('\\setmainfont{CMU Serif}\n' + '\\setsansfont{CMU Sans Serif}\n' + '\\setmonofont{CMU Typewriter Text}'), + 'textgreek': '', 'utf8extra': ('\\catcode`^^^^00a0\\active\\protected\\def^^^^00a0' '{\\leavevmode\\nobreak\\ }'), 'fvset': '\\fvset{fontsize=auto}', @@ -162,6 +183,8 @@ 'latex_engine': 'platex', 'babel': '', 'classoptions': ',dvipdfmx', + 'fontpkg': '\\usepackage{times}', + 'textgreek': '', 'fncychap': '', 'geometry': '\\usepackage[dvipdfm]{geometry}', }, @@ -552,6 +575,15 @@ def __init__(self, document, builder): builder.config.language) # set up multilingual module... + if self.elements['latex_engine'] == 'pdflatex': + if ('T2A' in self.elements['fontenc'] and + not self.babel.uses_cyrillic()): + self.elements['substitutefont'] = '\\usepackage{substitutefont}' + self.elements['sphinxpkgoptions'] += ',cyrnocyr' + if 'LGR' in self.elements['fontenc']: + self.elements['substitutefont'] = '\\usepackage{substitutefont}' + else: + self.elements['textgreek'] = '' # 'babel' key is public and user setting must be obeyed if self.elements['babel']: self.elements['classoptions'] += ',' + self.babel.get_language() diff --git a/tests/test_markup.py b/tests/test_markup.py index 0f401306b51..0c376d041d5 100644 --- a/tests/test_markup.py +++ b/tests/test_markup.py @@ -216,7 +216,7 @@ def get(name): 'verify', u'Γ\\\\∞$', None, - r'\(\Gamma\)\textbackslash{}\(\infty\)\$', + u'Γ\\textbackslash{}\\(\\infty\\)\\$', ), ( # in verbatim code fragments @@ -225,7 +225,7 @@ def get(name): None, (u'\\fvset{hllines={, ,}}%\n' u'\\begin{sphinxVerbatim}[commandchars=\\\\\\{\\}]\n' - u'@\\(\\Gamma\\)\\PYGZbs{}\\(\\infty\\)\\PYGZdl{}\\PYGZob{}\\PYGZcb{}\n' + u'@Γ\\PYGZbs{}\\(\\infty\\)\\PYGZdl{}\\PYGZob{}\\PYGZcb{}\n' u'\\end{sphinxVerbatim}'), ), ( From f56431b6874dde42903ead498d7d719aac4b2d0e Mon Sep 17 00:00:00 2001 From: jfbu Date: Sat, 17 Nov 2018 00:41:53 +0100 Subject: [PATCH 2/5] Fix flake8 --- sphinx/writers/latex.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index f1e3b7e988e..b77f6234a67 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -576,8 +576,7 @@ def __init__(self, document, builder): # set up multilingual module... if self.elements['latex_engine'] == 'pdflatex': - if ('T2A' in self.elements['fontenc'] and - not self.babel.uses_cyrillic()): + if 'T2A' in self.elements['fontenc'] and not self.babel.uses_cyrillic(): self.elements['substitutefont'] = '\\usepackage{substitutefont}' self.elements['sphinxpkgoptions'] += ',cyrnocyr' if 'LGR' in self.elements['fontenc']: From 6283324b1a6edd3ff46b7b775ba06842478f90c2 Mon Sep 17 00:00:00 2001 From: jfbu Date: Sat, 17 Nov 2018 01:38:01 +0100 Subject: [PATCH 3/5] Load CMU by filename, not font name, for XeLaTeX --- CHANGES | 7 +++++-- doc/usage/builders/index.rst | 3 ++- sphinx/writers/latex.py | 15 ++++++++++++--- 3 files changed, 19 insertions(+), 6 deletions(-) diff --git a/CHANGES b/CHANGES index 7ff4978efc9..70a81d93f4e 100644 --- a/CHANGES +++ b/CHANGES @@ -33,12 +33,15 @@ Dependencies - texlive-fonts-extra - Cyrillic letters (in non-Cyrillic documents) - These extra package are not required by default. The first two are needed if + These extra package are not required by default. The first two are needed if the :confval:`latex_elements`.\ ``'fontenc'`` key has been modify to declare - the use of the ``LGR`` (Greek) and/or ``T2A`` (Cyrillic) font encoding. Even + the use of the ``LGR`` (Greek) and/or ``T2A`` (Cyrillic) font encoding. Even then, the last four are font packages arising in the default value for :confval:`latex_elements`.\ ``'fontpkg'``, and may be replaced by other font packages providing ``LGR`` and/or ``T2A`` support. +* LaTeX builder with :confval:`latex_engine` set to ``'xelatex'`` or to + ``'lualatex'`` requires (by default) the ``Computer Modern Unicode`` fonts, + which in Ubuntu xenial are in ``texlive-fonts-extra``. Incompatible changes -------------------- diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index 3f16c84e507..aa4aba76af7 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -167,7 +167,8 @@ The builder's "name" must be given to the **-b** command-line option of * ``texlive-fonts-extra``, ``texlive-lang-greek`` (if needed to support Greek or Cyrillic letters in non-cyrillic document) * ``latexmk`` (for ``make latexpdf`` on GNU/Linux and MacOS X) - * ``texlive-luatex``, ``texlive-xetex`` (see :confval:`latex_engine`) + * ``texlive-luatex``, ``texlive-xetex``, ``texlive-fonts-extra`` + (if :confval:`latex_engine` is set to ``'xelatex'`` or ``'lualatex'``) The testing of Sphinx LaTeX is done on Ubuntu xenial with the above mentioned packages, which are from a TeXLive 2015 snapshot dated March 2016. diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index b77f6234a67..aa80d0776f0 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -158,9 +158,18 @@ 'polyglossia': '\\usepackage{polyglossia}', 'babel': '', 'fontenc': '\\usepackage{fontspec}', - 'fontpkg': ('\\setmainfont{CMU Serif}\n' - '\\setsansfont{CMU Sans Serif}\n' - '\\setmonofont{CMU Typewriter Text}'), + 'fontpkg': ('\\setmainfont{cmunrm.otf}[\n' + ' BoldFont = cmunbx.otf,\n' + ' ItalicFont = cmunti.otf,\n' + ' BoldItalicFont = cmunbi.otf]\n' + '\\setsansfont{cmunss.otf}[\n' + ' BoldFont = cmunsx.otf,\n' + ' ItalicFont = cmunsi.otf,\n' + ' BoldItalicFont = cmunso.otf]\n' + '\\setmonofont{cmuntt.otf}[\n' + ' BoldFont = cmuntb.otf,\n' + ' ItalicFont = cmunit.otf,\n' + ' BoldItalicFont = cmuntx.otf]'), 'textgreek': '', 'utf8extra': ('\\catcode`^^^^00a0\\active\\protected\\def^^^^00a0' '{\\leavevmode\\nobreak\\ }'), From 1edf2a45b9873ce3a137c72667078989f0aaa6b3 Mon Sep 17 00:00:00 2001 From: jfbu Date: Wed, 21 Nov 2018 18:58:58 +0100 Subject: [PATCH 4/5] LaTeX: font choices for Greek and Cyrillic support, and (Xe|Lua)LaTeX --- CHANGES | 52 ++------ doc/conf.py | 12 +- doc/usage/builders/index.rst | 48 ++++--- doc/usage/configuration.rst | 193 ++++++++++++++--------------- sphinx/templates/latex/latex.tex_t | 1 + sphinx/texinputs/sphinx.sty | 24 ---- sphinx/writers/latex.py | 81 +++++++----- 7 files changed, 194 insertions(+), 217 deletions(-) diff --git a/CHANGES b/CHANGES index 70a81d93f4e..cd330a70b4c 100644 --- a/CHANGES +++ b/CHANGES @@ -5,43 +5,16 @@ Dependencies ------------ * LaTeX builder now depends on TeX Live 2015 or above. -* LaTeX builder may need these additional LaTeX packages for PDF builds - (with ``'pdflatex'`` :confval:`latex_engine`): - - .. list-table:: Requirements - :header-rows: 1 - - * - LaTeX package (CTAN) - - Ubuntu xenial - - needed for - * - substitutefont - - texlive-latex-extra - - Greek or Cyrillic letters (in non-Cyrillic documents) - * - textalpha - - texlive-lang-greek - - Greek letters (in text, not math) - * - gfsartemisia - - fonts-gfs-artemisia (texlive-fonts-extra) - - Greek letters (in text, not math) - * - gfsneohellenic - - fonts-gfs-neohellenic (texlive-fonts-extra) - - Greek letters (in text, not math) - * - cbfonts - - texlive-lang-greek - - Greek letters (in text, not math) - * - cm-lgc - - texlive-fonts-extra - - Cyrillic letters (in non-Cyrillic documents) - - These extra package are not required by default. The first two are needed if - the :confval:`latex_elements`.\ ``'fontenc'`` key has been modify to declare - the use of the ``LGR`` (Greek) and/or ``T2A`` (Cyrillic) font encoding. Even - then, the last four are font packages arising in the default value for - :confval:`latex_elements`.\ ``'fontpkg'``, and may be replaced by other font - packages providing ``LGR`` and/or ``T2A`` support. +* LaTeX builder (with ``'pdflatex'`` :confval:`latex_engine`) will process + Unicode Greek letters in text (not in math mark-up) via the text font and + will not escape them to math mark-up. See the discussion of the + ``'fontenc'`` key of :confval:`latex_elements`; such (optional) support for + Greek adds, for example on Ubuntu xenial, the ``texlive-lang-greek`` and (if + default font set-up is not modified) ``cm-super(-minimal)`` as additional + Sphinx LaTeX requirements. * LaTeX builder with :confval:`latex_engine` set to ``'xelatex'`` or to - ``'lualatex'`` requires (by default) the ``Computer Modern Unicode`` fonts, - which in Ubuntu xenial are in ``texlive-fonts-extra``. + ``'lualatex'`` requires (by default) the ``FreeFont`` fonts, + which in Ubuntu xenial are provided by package ``fonts-freefont-otf``. Incompatible changes -------------------- @@ -53,10 +26,9 @@ Incompatible changes * LaTeX: Move message resources to ``sphinxmessage.sty`` * LaTeX: Stop using ``\captions`` macro for some labels * LaTeX: Greek letters in text are not escaped to math mode mark-up, and they - will use the text font not the math font. If (and only if) the document - contains such Greek Unicode letters *and* the :confval:`latex_engine` is - ``'pdflatex'`` then the :confval:`latex_elements`.\ ``'fontenc'`` key - **must** be used to declare usage of the ``LGR`` font encoding. + will use the text font not the math font. The ``LGR`` font encoding must be + added to the ``'fontenc'`` key of :confval:`latex_elements` for this to work + (only if it is needed by the document, of course). Deprecated ---------- diff --git a/doc/conf.py b/doc/conf.py index 661efb4348d..8d0762b4514 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -56,17 +56,17 @@ 'Georg Brandl', 'manual', 1)] latex_logo = '_static/sphinx.png' latex_elements = { - 'fontenc': r'\usepackage[LGR,T2A,T1]{fontenc}', + 'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}', 'fontpkg': r''' \usepackage[sc]{mathpazo} \usepackage[scaled]{helvet} \usepackage{courier} -\substitutefont{LGR}{\rmdefault}{udidot} -\substitutefont{LGR}{\sfdefault}{neohellenic} +\substitutefont{LGR}{\rmdefault}{cmr} +\substitutefont{LGR}{\sfdefault}{cmss} \substitutefont{LGR}{\ttdefault}{cmtt} -\substitutefont{T2A}{\rmdefault}{fcm} -\substitutefont{T2A}{\sfdefault}{fcs} -\substitutefont{T2A}{\ttdefault}{fct} +\substitutefont{X2}{\rmdefault}{cmr} +\substitutefont{X2}{\sfdefault}{cmss} +\substitutefont{X2}{\ttdefault}{cmtt} ''', 'passoptionstopackages': '\\PassOptionsToPackage{svgnames}{xcolor}', 'preamble': '\\DeclareUnicodeCharacter{229E}{\\ensuremath{\\boxplus}}', diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index aa4aba76af7..b9e107699e8 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -158,20 +158,34 @@ The builder's "name" must be given to the **-b** command-line option of chapter :ref:`latex-options` for details. The produced LaTeX file uses several LaTeX packages that may not be present - in a "minimal" TeX distribution installation. For example, on Ubuntu, the - following packages need to be installed for successful PDF builds: + in a "minimal" TeX distribution installation. + + On Ubuntu xenial, the following packages need to be installed for + successful PDF builds: * ``texlive-latex-recommended`` * ``texlive-fonts-recommended`` * ``texlive-latex-extra`` - * ``texlive-fonts-extra``, ``texlive-lang-greek`` (if needed to - support Greek or Cyrillic letters in non-cyrillic document) - * ``latexmk`` (for ``make latexpdf`` on GNU/Linux and MacOS X) - * ``texlive-luatex``, ``texlive-xetex``, ``texlive-fonts-extra`` - (if :confval:`latex_engine` is set to ``'xelatex'`` or ``'lualatex'``) - - The testing of Sphinx LaTeX is done on Ubuntu xenial with the above mentioned - packages, which are from a TeXLive 2015 snapshot dated March 2016. + * ``latexmk`` (this is a Sphinx requirement on GNU/Linux and MacOS X + for functioning of ``make latexpdf``) + + Additional packages are needed in some circumstances (see the discussion of + the ``'fontpkg'`` key of :confval:`latex_elements` for more information): + + * to support occasional Cyrillic letters or words, and a fortiori if + :confval:`language` is set to a Cyrillic language, the package + ``texlive-lang-cyrillic`` is required, and, with unmodified ``'fontpkg'``, + also ``cm-super`` or ``cm-super-minimal``, + * to support occasional Greek letters or words (in text, not in + :rst:dir:`math` directive contents), ``texlive-lang-greek`` is required, + and, with unmodified ``'fontpkg'``, also ``cm-super`` or + ``cm-super-minimal``, + * for ``'xelatex'`` or ``'lualatex'`` (see :confval:`latex_engine`), + ``texlive-xetex`` resp. ``texlive-luatex``, and, if leaving unchanged + ``'fontpkg'``, ``fonts-freefont-otf``. + + The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution + is based on a TeXLive 2015 snapshot dated March 2016. .. versionchanged:: 1.6 Formerly, testing had been done on Ubuntu precise (TeXLive 2009). @@ -194,20 +208,16 @@ The builder's "name" must be given to the **-b** command-line option of reduces console output to a minimum. - Also, if ``latexmk`` version is 4.52b or higher (Jan 17) - ``LATEXMKOPTS="-xelatex"`` will speed up PDF builds via XeLateX in case + Also, if ``latexmk`` is at version 4.52b or higher (January 2017) + ``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case of numerous graphics inclusions. - .. code-block:: console - - make latexpdf LATEXMKOPTS="-xelatex" - - To pass options directly to the ``(pdf|xe|lua)latex`` executable, use - variable ``LATEXOPTS``. + To pass options directly to the ``(pdf|xe|lua)latex`` binary, use + variable ``LATEXOPTS``, for example: .. code-block:: console - make latexpdf LATEXOPTS="--interaction=nonstopmode" + make latexpdf LATEXOPTS="--halt-on-error" .. autoattribute:: name diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 765431fe28d..d133bbfe177 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1796,42 +1796,18 @@ information. * ``'lualatex'`` -- LuaLaTeX * ``'platex'`` -- pLaTeX (default if :confval:`language` is ``'ja'``) - PDFLaTeX's support for Unicode characters covers those from the document - language (the LaTeX ``babel`` and ``inputenc`` packages map them to glyph - slots in the document font, at various encodings allowing each only 256 - characters; Sphinx uses by default (except for Cyrillic languages) the - ``times`` package), but stray characters from other scripts or special - symbols may require adding extra LaTeX packages or macros to the LaTeX - preamble. - - If your project uses such extra Unicode characters, switching the engine to - XeLaTeX or LuaLaTeX and setting up the document to use an OpenType font - with wide-enough glyph coverage is often easier than sticking with PDFLaTeX - and trying to get it to work with the Unicode characters. - - The :confval:`latex_elements` ``'fontpkg'`` key allows to set up the - document fonts, see :ref:`this example `. Currently, for - XeLaTeX and LuaLaTeX, Sphinx leaves this key empty and LaTeX then defaults - to the `Latin Modern`_ font family (from the TeX distribution fonts). This - font family provides good coverage of Latin scripts (European languages, - Vietnamese) but Cyrillic requires some other OpenType font; for example - Computer Modern Unicode (see `babel-russian`_ documentation on how to load - it in the LaTeX document). In future, it is planned Sphinx will provide - another default choice of OpenType font than `Latin Modern`_, perhaps - `Libertinus`_, which is included in recent TeX distributions and supports - Latin and Cyrillic and also has an accompanying math font. - - With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use - `polyglossia`_. For some languages the `babel`_ support appears - preferable; Sphinx uses currently `babel`_ for French and perhaps will also - for some more languages in future. One can use the - :confval:`latex_elements` ``'babel'`` key to override Sphinx's default. - - .. _`Latin Modern`: http://www.gust.org.pl/projects/e-foundry/latin-modern - .. _`polyglossia`: https://ctan.org/pkg/polyglossia - .. _`babel`: https://ctan.org/pkg/babel - .. _`babel-russian`: https://ctan.org/pkg/babel-russian - .. _`Libertinus`: https://ctan.org/pkg/libertinus + ``'pdflatex'``\ 's support for Unicode characters is limited. + + If your project uses Unicode characters, setting the engine to + ``'xelatex'`` or ``'lualatex'`` and making sure to use an OpenType font + with wide-enough glyph coverage (since Sphinx 2.0, the default font is the + FreeFont family) is often easier than trying to make + ``'pdflatex'`` work with the extra Unicode characters. + + .. note:: + + 2.0 adds to ``'pdflatex'`` automatic support in Latin language document + of occasional Cyrillic or Greek letters or words. .. confval:: latex_documents @@ -2033,6 +2009,20 @@ information. ``english`` is used if no language.) For Japanese documents, the default is the empty string. + With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use + `polyglossia`_, but one should be aware that current `babel`_ has + improved its support for Unicode engines in recent years and for some + languages it may make sense to prefer ``babel`` over ``polyglossia``. + + .. hint:: + + After modifiying a core LaTeX key like this one, clean up the LaTeX + build repertory before next PDF build, else left-over auxiliary + files are likely to break the build. + + .. _`polyglossia`: https://ctan.org/pkg/polyglossia + .. _`babel`: https://ctan.org/pkg/babel + .. versionchanged:: 1.5 For :confval:`latex_engine` set to ``'xelatex'``, the default is ``'\\usepackage{polyglossia}\n\\setmainlanguage{}'``. @@ -2060,28 +2050,38 @@ information. .. code-block:: latex - \substitutefont{LGR}{\rmdefault}{artemisia} - \substitutefont{LGR}{\sfdefault}{neohellenic} + \substitutefont{LGR}{\rmdefault}{cmr} + \substitutefont{LGR}{\sfdefault}{cmss} \substitutefont{LGR}{\ttdefault}{cmtt} - \substitutefont{T2A}{\rmdefault}{fcm} - \substitutefont{T2A}{\sfdefault}{fcs} - \substitutefont{T2A}{\ttdefault}{fct} - - For this however, the ``'fontenc'`` key must be used to tell - LaTeX to load the ``LGR`` (Greek) or ``T2A`` (partial Cyrillic) - font encoding. If ``'fontenc'`` is not modified the above lines - are not executed. - - In a custom ``'fontpkg'`` setting, do not use ``\substitutefont`` - with a font encoding not also declared via ``'fontenc'``. - - - For ``'xelatex'`` and ``'lualatex'``, the default is - ``'\\setmainfont{CMU Serif}'`` (and similar for sans - serif and monospace) . This OpenType font family supports - both Cyrillic and Greek scripts (contrarily to the - default font configured by LaTeX for ``xelatex/lualatex`` - if ``'fontpkg'`` is left to empty string, as was the case - prior to 2.0). + \substitutefont{X2}{\rmdefault}{cmr} + \substitutefont{X2}{\sfdefault}{cmss} + \substitutefont{X2}{\ttdefault}{cmtt} + + but this is activated only under the condition that the + ``'fontenc'`` key is configured to load the ``LGR`` (Greek) + and/or ``X2`` (Cyrillic) pdflatex-font encodings (if the + :confval:`language` is set to a Cyrillic language, this + ``'fontpkg'`` key must be used as "times" package has no direct + support for it; then keep only ``LGR`` lines from the above, + if support is needed for Greek in the text). + + The ``\substitutefont`` command is from the eponymous LaTeX + package, which is loaded by Sphinx if needed (on Ubuntu xenial it + is part of ``texlive-latex-extra`` which is a Sphinx + requirement). + + Only if the document actually does contain Unicode Greek letters + (in text) or Cyrillic letters, will the above default set-up + cause additional requirements for the PDF build. On Ubuntu + xenial, ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and + (with the above choice of fonts) the ``cm-super`` (or + ``cm-super-minimal``) package. + + - For ``'xelatex'`` and ``'lualatex'``, the default is to + use the FreeFont family: this OpenType font family + supports both Cyrillic and Greek scripts and is available as + separate Ubuntu xenial package ``fonts-freefont-otf``, it is not + needed to install the big package ``texlive-fonts-extra``. - ``'platex'`` (Japanese documents) engine supports individual Cyrillic and Greek letters with no need of extra user set-up. @@ -2164,24 +2164,45 @@ information. "fontenc" package inclusion, defaults to ``'\\usepackage[T1]{fontenc}'``. + One can (``'pdflatex'`` only) add ``LGR`` for support of Greek letters + or words in the document, and ``X2`` (or ``T2A``) for Cyrillic ones: + + .. code-block:: latex + + r'\usepackage[LGR,X2,T1]{fontenc}' + + (A Cyrillic document will naturally use ``T2A`` or ``X2`` in last + position, as it has then to be the main encoding for the document + fonts). + + .. attention:: + + Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math + mark-up. This is not the case anymore, thus if such Greek letters + are used in the text (we are not discussing here Greek letters + using the math font, from math markup ``\alpha`` etc...) it is then + mandatory to declare the ``LGR`` font encoding, i.e. + ``r'\usepackage[LGR,T1]{fontenc}'`` if no support for Cyrillic is + needed. On Ubuntu xenial, package ``texlive-lang-greek`` is then + required (and also ``cm-super`` if the ``'fontpkg'`` setting is not + modified). + + .. hint:: + + Ubuntu package ``cm-super-minimal`` requires that the LaTeX + document executes ``\usepackage[10pt]{type1ec}`` before loading + ``fontenc``. Thus, use this key with this extra at its start. + .. versionchanged:: 1.5 Defaults to ``'\\usepackage{fontspec}'`` when :confval:`latex_engine` is ``'xelatex'``. .. versionchanged:: 1.6 ``'lualatex'`` also uses ``fontspec`` per default. .. versionchanged:: 2.0 - With ``'pdflatex'`` you can add ``LGR`` and/or ``T2A`` - (before ``T1`` which should remain the last) to trigger - automatic support of occasional Greek and Cyrillic letters - in text. - - .. attention:: - - Prior to 2.0, Unicode Greek letters were escaped to use LaTeX - math mark-up. This is not the case anymore so it may be needed - to modify this key into ``'\\usepackage[LGR,T1]{fontenc}'`` and - also to make sure to have the suitable Greek font packages - as listed in :doc:`../changes` (or replacements). + Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of + occasional Greek or Cyrillic (``'pdflatex'`` only, as this support + is provided natively by ``'platex'`` and only requires suitable + font with ``'xelatex'/'lualatex'``). ``'textgreek'`` The default (``'pdflatex'`` only) is @@ -2190,41 +2211,13 @@ information. value will be forced to be empty string. This is needed for ``pdfLaTeX`` to support Unicode input of Greek - letters such as φύσις. Expert users may want to load the ``textalpha`` + letters such as φύσις. Expert users may want to load the ``textalpha`` package with its option ``normalize-symbols``. - .. note:: - - - Unicode Greek letters in text were, prior to release 2.0, escaped - to LaTeX math markup in the produced LaTeX file, hence their - rendering in PDF used the math font. They are now copied over - unmodified to the LaTeX file and rendered in PDF by the text - font. But the ``LGR`` font encoding must be loaded. - - - Unicode Greek letters are not accepted in :rst:dir:`math` - contents. LaTeX math mark-up ``\alpha`` etc..., must be used - there. - - - With ``'xelatex'`` or ``'lualatex'``, this is ignored as the - support for Unicode Greek letters comes from using an OpenType - font which supports the Greek script. This is the case (since - 2.0) with the default fonts used by Sphinx for these engines. - - Besides, Unicode input in math (not only Greek symbols) can be - obtained by adding ``\usepackage{unicode-math}`` to the LaTeX - preamble (and perhaps use ``\setmathfont`` to switch to some - other OpenMath font than the XeLaTeX default). Then one can use - ``:math:`α=\alpha``` input. But take note that - ``\usepackage[math-style=literal]{unicode-math}`` is needed to - obtain in PDF similar output as in HTML+MathJaX, i.e. the ``α`` - remains upright, and the ``\alpha`` gives an italic letter. - - - With ``platex`` (Japanese), this key setting is ignored: - Greek (and Cyrillic) letters are handled natively by the engine - own default fonts. + With ``'platex'`` (Japanese), ``'xelatex'`` or ``'lualatex'``, this + key is ignored. .. versionadded:: 2.0 - ``'geometry'`` "geometry" package inclusion, the default definition is: diff --git a/sphinx/templates/latex/latex.tex_t b/sphinx/templates/latex/latex.tex_t index 06b94b0f2bd..c6586d6b794 100644 --- a/sphinx/templates/latex/latex.tex_t +++ b/sphinx/templates/latex/latex.tex_t @@ -27,6 +27,7 @@ <%= amsmath %> <%= multilingual %> <%= substitutefont %> +<%= textcyrillic %> <%= fontpkg %> <%= textgreek %> <%= fncychap %> diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 5aa1d586ae8..249f2ece070 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -247,8 +247,6 @@ \DeclareStringOption[\inv@mag in]{vmargin} \DeclareStringOption[.5\dimexpr\inv@mag in\relax]{marginpar} \fi -% Allow Cyrillic letters in non-Cyrillic document (needed for pdflatex only) -\DeclareBoolOption[false]{cyrnocyr} \DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0} \DeclareStringOption[-1]{numfigreset} @@ -363,28 +361,6 @@ \newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}} -%% CYRILLIC IN NON-CYRILLIC DOCUMENTS (pdflatex only) -% -% refs: https://tex.stackexchange.com/q/460271/4686 -% -\ifspx@opt@cyrnocyr - \@tfor\@tempa:=% - {ae}{a}{b}{chrdsc}{chvcrs}{ch}{c}{dje}{dze}{dzhe}{d}{erev}{ery}{e}% - {f}{ghcrs}{gup}{g}{hdsc}{hrdsn}{h}{ie}{ii}{ishrt}{i}{je}% - {kbeak}{kdsc}{kvcrs}{k}{lje}{l}{m}{ndsc}{ng}{nje}{n}{otld}{o}{p}{r}% - {schwa}{sdsc}{sftsn}{shch}{shha}{sh}{s}{tshe}{t}{ushrt}{u}{v}% - {ya}{yhcrs}{yi}{yo}{yu}{y}{zdsc}{zhdsc}{zh}{z}\do - {% - \expandafter\DeclareTextSymbolDefault\expandafter - {\csname cyr\@tempa\endcsname}{T2A}% - \expandafter\uppercase\expandafter{\expandafter - \def\expandafter\@tempa\expandafter{\@tempa}}% - \expandafter\DeclareTextSymbolDefault\expandafter - {\csname CYR\@tempa\endcsname}{T2A}% - }% - \DeclareTextSymbolDefault{\CYRpalochka}{T2A}% -\fi - %% MAXLISTDEPTH % % remove LaTeX's cap on nesting depth if 'maxlistdepth' key used. diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index aa80d0776f0..e494c7e4feb 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -64,23 +64,54 @@ 'lowerroman': r'\roman', 'upperroman': r'\Roman', }) # type: Dict[unicode, unicode] -PDFLATEX_DEFAULT_FONT_PKG = r''' +PDFLATEX_DEFAULT_FONTPKG = r''' \usepackage{times} \expandafter\ifx\csname T@LGR\endcsname\relax \else % LGR was declared as font encoding - \substitutefont{LGR}{\rmdefault}{artemisia} % gfsartemisia - \substitutefont{LGR}{\sfdefault}{neohellenic} % gfsneohellenic - \substitutefont{LGR}{\ttdefault}{cmtt} % cbfonts + \substitutefont{LGR}{\rmdefault}{cmr} + \substitutefont{LGR}{\sfdefault}{cmss} + \substitutefont{LGR}{\ttdefault}{cmtt} \fi -\expandafter\ifx\csname T@T2A\endcsname\relax +\expandafter\ifx\csname T@X2\endcsname\relax + \expandafter\ifx\csname T@T2A\endcsname\relax + \else + % T2A was declared as font encoding + \substitutefont{T2A}{\rmdefault}{cmr} + \substitutefont{T2A}{\sfdefault}{cmss} + \substitutefont{T2A}{\ttdefault}{cmtt} + \fi \else -% T2A was declared as font encoding - \substitutefont{T2A}{\rmdefault}{fcm} - \substitutefont{T2A}{\sfdefault}{fcs} - \substitutefont{T2A}{\ttdefault}{fct} +% X2 was declared as font encoding + \substitutefont{X2}{\rmdefault}{cmr} + \substitutefont{X2}{\sfdefault}{cmss} + \substitutefont{X2}{\ttdefault}{cmtt} \fi ''' +XELATEX_DEFAULT_FONTPKG = r''' +\setmainfont{FreeSerif}[ + Extension = .otf, + UprightFont = *, + ItalicFont = *Italic, + BoldFont = *Bold, + BoldItalicFont = *BoldItalic +] +\setsansfont{FreeSans}[ + Extension = .otf, + UprightFont = *, + ItalicFont = *Oblique, + BoldFont = *Bold, + BoldItalicFont = *BoldOblique, +] +\setmonofont{FreeMono}[ + Extension = .otf, + UprightFont = *, + ItalicFont = *Oblique, + BoldFont = *Bold, + BoldItalicFont = *BoldOblique, +] +''' +LUALATEX_DEFAULT_FONTPKG = XELATEX_DEFAULT_FONTPKG DEFAULT_SETTINGS = { 'latex_engine': 'pdflatex', @@ -103,8 +134,9 @@ 'multilingual': '', 'babel': '\\usepackage{babel}', 'polyglossia': '', - 'fontpkg': PDFLATEX_DEFAULT_FONT_PKG, + 'fontpkg': PDFLATEX_DEFAULT_FONTPKG, 'substitutefont': '', + 'textcyrillic': '', 'textgreek': '\\usepackage{textalpha}', 'fncychap': '\\usepackage[Bjarne]{fncychap}', 'hyperref': ('% Include hyperref last.\n' @@ -158,18 +190,7 @@ 'polyglossia': '\\usepackage{polyglossia}', 'babel': '', 'fontenc': '\\usepackage{fontspec}', - 'fontpkg': ('\\setmainfont{cmunrm.otf}[\n' - ' BoldFont = cmunbx.otf,\n' - ' ItalicFont = cmunti.otf,\n' - ' BoldItalicFont = cmunbi.otf]\n' - '\\setsansfont{cmunss.otf}[\n' - ' BoldFont = cmunsx.otf,\n' - ' ItalicFont = cmunsi.otf,\n' - ' BoldItalicFont = cmunso.otf]\n' - '\\setmonofont{cmuntt.otf}[\n' - ' BoldFont = cmuntb.otf,\n' - ' ItalicFont = cmunit.otf,\n' - ' BoldItalicFont = cmuntx.otf]'), + 'fontpkg': XELATEX_DEFAULT_FONTPKG, 'textgreek': '', 'utf8extra': ('\\catcode`^^^^00a0\\active\\protected\\def^^^^00a0' '{\\leavevmode\\nobreak\\ }'), @@ -180,9 +201,7 @@ 'polyglossia': '\\usepackage{polyglossia}', 'babel': '', 'fontenc': '\\usepackage{fontspec}', - 'fontpkg': ('\\setmainfont{CMU Serif}\n' - '\\setsansfont{CMU Sans Serif}\n' - '\\setmonofont{CMU Typewriter Text}'), + 'fontpkg': LUALATEX_DEFAULT_FONTPKG, 'textgreek': '', 'utf8extra': ('\\catcode`^^^^00a0\\active\\protected\\def^^^^00a0' '{\\leavevmode\\nobreak\\ }'), @@ -585,9 +604,15 @@ def __init__(self, document, builder): # set up multilingual module... if self.elements['latex_engine'] == 'pdflatex': - if 'T2A' in self.elements['fontenc'] and not self.babel.uses_cyrillic(): - self.elements['substitutefont'] = '\\usepackage{substitutefont}' - self.elements['sphinxpkgoptions'] += ',cyrnocyr' + if not self.babel.uses_cyrillic(): + if 'X2' in self.elements['fontenc']: + self.elements['substitutefont'] = '\\usepackage{substitutefont}' + self.elements['textcyrillic'] = ('\\usepackage[Xtwo]' + '{sphinxcyrillic}') + elif 'T2A' in self.elements['fontenc']: + self.elements['substitutefont'] = '\\usepackage{substitutefont}' + self.elements['textcyrillic'] = ('\\usepackage[TtwoA]' + '{sphinxcyrillic}') if 'LGR' in self.elements['fontenc']: self.elements['substitutefont'] = '\\usepackage{substitutefont}' else: From 5974c4010bdc457bedc9c9ea724e438062e7ed4e Mon Sep 17 00:00:00 2001 From: jfbu Date: Wed, 21 Nov 2018 22:48:51 +0100 Subject: [PATCH 5/5] new file: sphinx/texinputs/sphinxcyrillic.sty Forgot to add it to previous commit :( --- sphinx/texinputs/sphinxcyrillic.sty | 51 +++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 sphinx/texinputs/sphinxcyrillic.sty diff --git a/sphinx/texinputs/sphinxcyrillic.sty b/sphinx/texinputs/sphinxcyrillic.sty new file mode 100644 index 00000000000..a4714d3ee22 --- /dev/null +++ b/sphinx/texinputs/sphinxcyrillic.sty @@ -0,0 +1,51 @@ +%% CYRILLIC IN NON-CYRILLIC DOCUMENTS (pdflatex only) +% +% refs: https://tex.stackexchange.com/q/460271/ +% https://tex.stackexchange.com/a/460325/ thanks to user egreg +% https://tex.stackexchange.com/a/460305/ thanks to user jfbu +\ProvidesPackage{sphinxcyrillic}% + [2018/11/21 v2.0 support for Cyrillic in non-Cyrillic documents] +\RequirePackage{kvoptions} +\SetupKeyvalOptions{prefix=spx@cyropt@} % use \spx@cyropt@ prefix +\DeclareBoolOption[false]{Xtwo} +\DeclareBoolOption[false]{TtwoA} +\DeclareDefaultOption{\@unknownoptionerror} +\ProcessKeyvalOptions* + +\ifspx@cyropt@Xtwo +% 159 Cyrillic glyphs as available in X2 TeX 8bit font encoding +% This assumes inputenc loaded with utf8 option, or LaTeX release +% as recent as 2018/04/01 which does it automatically. + \@tfor\next:=% + {ө}{Ө}{ӡ}{Ӡ}{ә}{Ә}{ӕ}{Ӕ}{ӎ}{Ӎ}{ӌ}{Ӌ}{ӈ}{Ӈ}{ӆ}{Ӆ}{ӄ}{Ӄ}{Ӏ}% + {ҿ}{Ҿ}{ҽ}{Ҽ}{һ}{Һ}{ҹ}{Ҹ}{ҷ}{Ҷ}{ҵ}{Ҵ}{ҳ}{Ҳ}{ұ}{Ұ}{ү}{Ү}% + {ҭ}{Ҭ}{ҫ}{Ҫ}{ҩ}{Ҩ}{ҧ}{Ҧ}{ҥ}{Ҥ}{ң}{Ң}{ҡ}{Ҡ}{ҟ}{Ҟ}{ҝ}{Ҝ}{қ}{Қ}% + {ҙ}{Ҙ}{җ}{Җ}{ҕ}{Ҕ}{ғ}{Ғ}{ґ}{Ґ}{ѵ}{Ѵ}{ѫ}{Ѫ}{ѣ}{Ѣ}{џ}{ў}{ћ}{њ}{љ}% + {ј}{і}{ѕ}{є}{ђ}{ё}{я}{ю}{э}{ь}{ы}{ъ}{щ}{ш}{ч}{ц}{х}{ф}{у}{т}{с}% + {р}{п}{о}{н}{м}{л}{к}{й}{и}{з}{ж}{е}{д}{г}{в}{б}{а}{Я}{Ю}{Э}% + {Ь}{Ы}{Ъ}{Щ}{Ш}{Ч}{Ц}{Х}{Ф}{У}{Т}{С}{Р}{П}{О}{Н}{М}{Л}{К}{Й}{И}% + {З}{Ж}{Е}{Д}{Г}{В}{Б}{А}{Џ}{Ў}{Ћ}{Њ}{Љ}{Ј}{І}{Ѕ}{Є}{Ђ}{Ё}\do{% + \begingroup\def\IeC{\protect\DeclareTextSymbolDefault}% + \protected@edef\@temp{\endgroup\next{X2}}\@temp + }% +\else +\ifspx@cyropt@TtwoA +% 63*2+1=127 Cyrillic glyphs as found in T2A 8bit TeX font-encoding + \@tfor\@tempa:=% + {ae}{a}{b}{chrdsc}{chvcrs}{ch}{c}{dje}{dze}{dzhe}{d}{erev}{ery}{e}% + {f}{ghcrs}{gup}{g}{hdsc}{hrdsn}{h}{ie}{ii}{ishrt}{i}{je}% + {kbeak}{kdsc}{kvcrs}{k}{lje}{l}{m}{ndsc}{ng}{nje}{n}{otld}{o}{p}{r}% + {schwa}{sdsc}{sftsn}{shch}{shha}{sh}{s}{tshe}{t}{ushrt}{u}{v}% + {ya}{yhcrs}{yi}{yo}{yu}{y}{zdsc}{zhdsc}{zh}{z}\do + {% + \expandafter\DeclareTextSymbolDefault\expandafter + {\csname cyr\@tempa\endcsname}{T2A}% + \expandafter\uppercase\expandafter{\expandafter + \def\expandafter\@tempa\expandafter{\@tempa}}% + \expandafter\DeclareTextSymbolDefault\expandafter + {\csname CYR\@tempa\endcsname}{T2A}% + }% + \DeclareTextSymbolDefault{\CYRpalochka}{T2A}% +\fi\fi +\endinput +