docs: Activate exCJK only in CJK chapters

Activating xeCJK in English and Italian-translation documents
results in sub-optimal typesetting with wide-looking apostrophes
and quotation marks.

The xeCJK package provides macros for enabling and disabling its
effect in the middle of a document, namely \makexeCJKactive and
\makexeCJKinactive.

So the goal of this change is to activate xeCJK in the relevant
chapters in translations.

To do this:

    o Define custom macros in the preamble depending on the
      availability of the "Noto Sans CJK" font so that those
      macros can be used regardless of the use of xeCJK package.

    o Patch \sphinxtableofcontents so that xeCJK is inactivated
      after table of contents.

    o Embed those custom macros in each language's index.rst file
      as a ".. raw:: latex" construct.

Note: A CJK chapter needs \kerneldocCJKon in front of its chapter
heading, while a non-CJK chapter should have \kerneldocCJKoff
below its chapter heading.

This is to make sure the CJK font is available to CJK chapter's
heading and ending page's footer.

Tested against Sphinx versions 2.4.4 and 4.0.2.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Tested-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/lkml/2061da0a-6ab1-35f3-99c1-dbc415444f37@gmail.com
Link: https://lore.kernel.org/r/83208ddc-5de9-b283-3fd6-92c635348ca0@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 879e86dbea6679498cf738f28fd0b4f474b18a1e..25aa00c707b0277a8745c0e6259d08d8639a89de 100644 (file)
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -371,6 +371,19 @@ if cjk_cmd.find("Noto Sans CJK SC") >= 0:
        % This is needed for translations
         \\usepackage{xeCJK}
         \\setCJKmainfont{Noto Sans CJK SC}
+       % Define custom macros to on/off CJK
+       \\newcommand{\\kerneldocCJKon}{\\makexeCJKactive}
+       \\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive}
+       % To customize \sphinxtableofcontents
+       \\usepackage{etoolbox}
+       % Inactivate CJK after tableofcontents
+       \\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{}
+     '''
+else:
+    latex_elements['preamble']  += '''
+       % Custom macros to on/off CJK (Dummy)
+       \\newcommand{\\kerneldocCJKon}{}
+       \\newcommand{\\kerneldocCJKoff}{}
      '''
 
 # Fix reference escape troubles with Sphinx 1.4.x

diff --git a/Documentation/translations/index.rst b/Documentation/translations/index.rst
index e446e5ed00a6af8e2a2c82f3217c8c06b888a78a..556b050884fce94a23f9b91986e8564502b16bbb 100644 (file)
--- a/Documentation/translations/index.rst
+++ b/Documentation/translations/index.rst
@@ -18,6 +18,10 @@ Translations
 Disclaimer
 ----------
 
+.. raw:: latex
+
+       \kerneldocCJKoff
+
 Translation's purpose is to ease reading and understanding in languages other
 than English. Its aim is to help people who do not understand English or have
 doubts about its interpretation. Additionally, some people prefer to read

diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst
index bb8fa7346939bff973f8b7a22d1bb932e19bceb9..e80a3097aa578938cb011ab18cccc36fcc439bc7 100644 (file)
--- a/Documentation/translations/it_IT/index.rst
+++ b/Documentation/translations/it_IT/index.rst
@@ -4,6 +4,10 @@
 Traduzione italiana
 ===================
 
+.. raw:: latex
+
+       \kerneldocCJKoff
+
 :manutentore: Federico Vaga <federico.vaga@vaga.pv.it>
 
 .. _it_disclaimer:

diff --git a/Documentation/translations/ja_JP/index.rst b/Documentation/translations/ja_JP/index.rst
index 2f91b895e3c276aa773d259ba908c1fc79a18a45..f94ba62d41c36eb50239f9c2dedb029085debc15 100644 (file)
--- a/Documentation/translations/ja_JP/index.rst
+++ b/Documentation/translations/ja_JP/index.rst
@@ -1,7 +1,8 @@
 .. raw:: latex
 
-        \renewcommand\thesection*
-        \renewcommand\thesubsection*
+       \renewcommand\thesection*
+       \renewcommand\thesubsection*
+       \kerneldocCJKon
 
 Japanese translations
 =====================

diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst
index b9e27d20b039b523cf093ab2a1e03ee2497439d0..6ae258118bdf2dcfff990bd377d24f066f0d27e2 100644 (file)
--- a/Documentation/translations/ko_KR/index.rst
+++ b/Documentation/translations/ko_KR/index.rst
@@ -1,7 +1,8 @@
 .. raw:: latex
 
-        \renewcommand\thesection*
-        \renewcommand\thesubsection*
+       \renewcommand\thesection*
+       \renewcommand\thesubsection*
+       \kerneldocCJKon
 
 한국어 번역
 ===========

diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
index a736057da41f37945db095833c31ddbfa23dc4ab..1f953d3439a524004d572ce95bf25a37628c7e7e 100644 (file)
--- a/Documentation/translations/zh_CN/index.rst
+++ b/Documentation/translations/zh_CN/index.rst
@@ -4,6 +4,7 @@
 
        \renewcommand\thesection*
        \renewcommand\thesubsection*
+       \kerneldocCJKon
 
 .. _linux_doc_zh: