[PATCH] docs: Activate xeCJK only in CJK chapters

[Akira Yokosawa <akiyks@gmail.com>]

Activating xeCJK in English or 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 embedded in translations.tex after the fact.
      By default, xeCJK is inactive.

    o Add a script retouch-translations.sh to embed the on/off
      macros in translations.tex where necessary.
      The patterns in the script are ad-hoc by nature, and will
      need updates when the chapter organization changes.

    o Invoke the script at the final step of target "latexdocs".


Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
Hi Mauro,

Good news.
xeCJK can be activated/deactivated inside a document.
Which means we can activate xeCJK only in the CJK chapters
of the translations document.

This patch is an attempt to do so.

I think there still is ad-hoc aspect in this approach, but it
also fixed the build error of s390.pdf I encountered yesterday
(with the CJK font installed).

"make pdfdocs" now completes successfully both with and without
the CJK font installed.

Can you try this?
Any feedback is welcome!

        Thanks, Akira
--
 Documentation/Makefile                       |  2 ++
 Documentation/conf.py                        | 11 ++++++++
 Documentation/sphinx/retouch-translations.sh | 29 ++++++++++++++++++++
 3 files changed, 42 insertions(+)
 create mode 100755 Documentation/sphinx/retouch-translations.sh

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9c42dde97671..31ca4d268fa0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -96,6 +96,8 @@ linkcheckdocs:
 latexdocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
+	@find $(BUILDDIR) -name translations.tex -exec \
+	sh $(srctree)/Documentation/sphinx/retouch-translations.sh \{\} \;
 
 ifeq ($(HAVE_PDFLATEX),0)
 
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 879e86dbea66..b3ab8b6017af 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -371,6 +371,17 @@ if cjk_cmd.find("Noto Sans CJK SC") >= 0:
 	% This is needed for translations
         \\usepackage{xeCJK}
         \\setCJKmainfont{Noto Sans CJK SC}
+	% Define custom macro to on/off CJK
+	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive}
+	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive}
+	% CJK off by default
+	\\kerneldocCJKoff
+     '''
+else:
+    latex_elements['preamble']  += '''
+	% Dummy custom macro to on/off CJK
+	\\newcommand{\\kerneldocCJKon}{}
+	\\newcommand{\\kerneldocCJKoff}{}
      '''
 
 # Fix reference escape troubles with Sphinx 1.4.x
diff --git a/Documentation/sphinx/retouch-translations.sh b/Documentation/sphinx/retouch-translations.sh
new file mode 100755
index 000000000000..edbfde42b1a5
--- /dev/null
+++ b/Documentation/sphinx/retouch-translations.sh
@@ -0,0 +1,29 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-2.0
+# Copyright 2021 Akira Yokosawa <akiyks@gmail.com>
+#
+# Retouch translations.tex to add CJK on/off macros.
+# The substitution rules need updates when there is some change in
+# the ordering of chapters.
+#
+# Path of the file to be retouched is passed in command argument $1
+# from docs Makefile.
+# If there is no need of retouch, do nothing.
+
+retouch=$1
+
+if [ -e $retouch ]; then
+	if grep -q 'kerneldocCJKon\\chapter' $retouch ; then
+		exit 0
+	fi
+	sed -i -e 's/\(\\sphinxtableofcontents\)/\\kerneldocCJKon\1/' \
+	    -e 's/\(\\chapter{中文\)/\\kerneldocCJKon\1/' \
+	    -e 's/\(\\chapter{Traduzione[^}]*}\)/\1\\kerneldocCJKoff/' \
+	    -e 's/\(\\chapter{한국어\)/\\kerneldocCJKon\1/' \
+	    -e 's/\(\\chapter{Disclaimer[^}]*}\)/\1\\kerneldocCJKoff/' \
+	    $retouch
+	echo "$retouch retouched."
+	exit 0
+else
+	exit 0
+fi
-- 
2.17.1