[PATCH v3 0/9] docs: pdfdocs: Improve font choice in CJK translations

[PATCH v3 0/9] docs: pdfdocs: Improve font choice in CJK translations

[Akira Yokosawa]

Hi all,

Now that the traditional Chinese translations by Hu Haowen has been
merged into docs-next, this v3 patch set covers them.

Changes since RFC v2 [1]:

    o Regression fixes:
      - CJK Serif font is chosen only when it is available (3/9).
        Now systems with only "Noto Sans CJK" fonts are good enough
        for building pdfdocs.
      - \usepackage{setspace} is moved before that of hyperref for
        compatibility (6/9).
    o Split RFC v2's 2/7 into 4 smaller chunks (2/9 -- 5/9).
    o Cover zh_TW translations (2/9, 9/9).
    o Use \scmain, \tcmain, \krmain, and \jpmain instead of
      \scserif, \tcserif, \krserif, and \jpserif in the definition
      of \kerneldocBegin(SC|TC|KR|JP) (2/9).
    o Having heard nothing from Mauro and SeongJae, dropped RFC v2's
      6/7 and 7/7.
      (I'll post them later as a separate RFC patch set.)
    o Wordsmith change logs.

[1]: https://lore.kernel.org/linux-doc/20ff8a65-6a5c-c062-fe1a-0f5c5ddc813c@gmail.com/#t

For those wondering how the difference of SC and TC font variants would
look, here are links to screenshots from the traditional Chinese chapter.

    "Noto Serif CJK SC": https://fars.ee/oOAS.png
    "Noto Serif CJK TC": https://fars.ee/11Li.png

The difference might be hard to spot for non-CJK readers. ;-)

        Thanks, Akira

--
Akira Yokosawa (9):
  docs: pdfdocs: Refactor config for CJK document
  docs: pdfdocs: Add CJK-language-specific font settings
  docs: pdfdocs: Choose Serif font as CJK mainfont if possible
  docs: pdfdocs: Preserve inter-phrase space in Korean translations
  docs: pdfdocs: Add conf.py local to translations for ascii-art
    alignment
  docs: pdfdocs: One-half spacing for CJK translations
  docs: pdfdocs: Permit AutoFakeSlant for CJK fonts
  docs: pdfdocs: Teach xeCJK about character classes of quotation marks
  docs: pdfdocs: Enable language-specific font choice of zh_TW
    translations

 Documentation/conf.py                      | 118 ++++++++++++++++++---
 Documentation/translations/conf.py         |  12 +++
 Documentation/translations/ja_JP/howto.rst |   8 ++
 Documentation/translations/ja_JP/index.rst |   5 +
 Documentation/translations/ko_KR/howto.rst |   8 ++
 Documentation/translations/ko_KR/index.rst |   2 +
 Documentation/translations/zh_CN/index.rst |   5 +
 Documentation/translations/zh_TW/index.rst |   4 +
 8 files changed, 146 insertions(+), 16 deletions(-)
 create mode 100644 Documentation/translations/conf.py

-- 
2.17.1

[PATCH v3 1/9] docs: pdfdocs: Refactor config for CJK document

[Akira Yokosawa]

To make generated LaTeX code portable across systems with different sets
of available fonts, convert font-availability check in python code to
LaTeX code by using a conditional command provided by the "fontspec"
package.

This will help those who run Sphinx on one machine/container and run
latexmk on other machines/containers.

Remove import of check_output as it is unused any more.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 Documentation/conf.py | 22 +++++++++-------------
 1 file changed, 9 insertions(+), 13 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 7d92ec3e5b6e..b440cb606d22 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -16,8 +16,6 @@ import sys
 import os
 import sphinx
 
-from subprocess import check_output
-
 # Get Sphinx version
 major, minor, patch = sphinx.version_info[:3]
 
@@ -355,15 +353,14 @@ latex_elements = {
      ''',
 }
 
-# At least one book (translations) may have Asian characters
-# with are only displayed if xeCJK is used
+# Translations have Asian (CJK) characters which are only displayed if
+# xeCJK is used
 
-cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
-if cjk_cmd.find("Noto Sans CJK SC") >= 0:
-    latex_elements['preamble']  += '''
+latex_elements['preamble']  += '''
+    \\IfFontExistsTF{Noto Sans CJK SC}{
 	% This is needed for translations
-        \\usepackage{xeCJK}
-        \\setCJKmainfont{Noto Sans CJK SC}
+	\\usepackage{xeCJK}
+	\\setCJKmainfont{Noto Sans CJK SC}
 	% Define custom macros to on/off CJK
 	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive}
 	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive}
@@ -371,13 +368,12 @@ if cjk_cmd.find("Noto Sans CJK SC") >= 0:
 	\\usepackage{etoolbox}
 	% Inactivate CJK after tableofcontents
 	\\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{}
-     '''
-else:
-    latex_elements['preamble']  += '''
+    }{ % No CJK font found
 	% Custom macros to on/off CJK (Dummy)
 	\\newcommand{\\kerneldocCJKon}{}
 	\\newcommand{\\kerneldocCJKoff}{}
-     '''
+    }
+'''
 
 # Fix reference escape troubles with Sphinx 1.4.x
 if major == 1:
-- 
2.17.1

[PATCH v3 2/9] docs: pdfdocs: Add CJK-language-specific font settings

[Akira Yokosawa]

zh_TW, ko_KR, and ja_JP translations have their preferred glyph sets
different from that of zh_CN.

To switch CJK font in the middle of the translations, introduce custom
LaTeX macros listed below:

    \kerneldocBeginSC
    \kerneldocEndSC
    \kerneldocBeginTC
    \kerneldocEndTC
    \kerneldocBeginKR
    \kerneldocEndKR
    \kerneldocBeginJP
    \kerneldocEndJP

, and embed a pair of macros in each language's index.rst.

NOTE 1: Update of zh_TW/index.rst is deferred to a follow-up change.

NOTE 2: Custom macros added here do not imply \kerneldocCJK(on|off).
This is intentional.  For example, \kerneldocCJKoff needs to be
at the top of Italian translations' index.rst for the footer of
final zh_TW page to be properly typeset.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 Documentation/conf.py                      | 51 +++++++++++++++++++++-
 Documentation/translations/ja_JP/index.rst |  5 +++
 Documentation/translations/ko_KR/index.rst |  2 +
 Documentation/translations/zh_CN/index.rst |  5 +++
 4 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index b440cb606d22..24e5427588e7 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -361,10 +361,51 @@ latex_elements['preamble']  += '''
 	% This is needed for translations
 	\\usepackage{xeCJK}
 	\\setCJKmainfont{Noto Sans CJK SC}
+	\\setCJKsansfont{Noto Sans CJK SC}
+	\\setCJKmonofont{Noto Sans Mono CJK SC}
+	% CJK Language-specific font choices
+	\\newCJKfontfamily[SCmain]\\scmain{Noto Sans CJK SC}
+	\\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}
+	\\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}
+	\\newCJKfontfamily[TCmain]\\tcmain{Noto Sans CJK TC}
+	\\newCJKfontfamily[TCsans]\\tcsans{Noto Sans CJK TC}
+	\\newCJKfontfamily[TCmono]\\tcmono{Noto Sans Mono CJK TC}
+	\\newCJKfontfamily[KRmain]\\krmain{Noto Sans CJK KR}
+	\\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}
+	\\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}
+	\\newCJKfontfamily[JPmain]\\jpmain{Noto Sans CJK JP}
+	\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}
+	\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}
 	% Define custom macros to on/off CJK
 	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive}
 	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive}
-	% To customize \sphinxtableofcontents
+	\\newcommand{\\kerneldocBeginSC}{%
+	    \\begingroup%
+	    \\scmain%
+	}
+	\\newcommand{\\kerneldocEndSC}{\\endgroup}
+	\\newcommand{\\kerneldocBeginTC}{%
+	    \\begingroup%
+	    \\tcmain%
+	    \\renewcommand{\\CJKsfdefault}{TCsans}%
+	    \\renewcommand{\\CJKttdefault}{TCmono}%
+	}
+	\\newcommand{\\kerneldocEndTC}{\\endgroup}
+	\\newcommand{\\kerneldocBeginKR}{%
+	    \\begingroup%
+	    \\krmain%
+	    \\renewcommand{\\CJKsfdefault}{KRsans}%
+	    \\renewcommand{\\CJKttdefault}{KRmono}%
+	}
+	\\newcommand{\\kerneldocEndKR}{\\endgroup}
+	\\newcommand{\\kerneldocBeginJP}{%
+	    \\begingroup%
+	    \\jpmain%
+	    \\renewcommand{\\CJKsfdefault}{JPsans}%
+	    \\renewcommand{\\CJKttdefault}{JPmono}%
+	}
+	\\newcommand{\\kerneldocEndJP}{\\endgroup}
+	% To customize \\sphinxtableofcontents
 	\\usepackage{etoolbox}
 	% Inactivate CJK after tableofcontents
 	\\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{}
@@ -372,6 +413,14 @@ latex_elements['preamble']  += '''
 	% Custom macros to on/off CJK (Dummy)
 	\\newcommand{\\kerneldocCJKon}{}
 	\\newcommand{\\kerneldocCJKoff}{}
+	\\newcommand{\\kerneldocBeginSC}{}
+	\\newcommand{\\kerneldocEndSC}{}
+	\\newcommand{\\kerneldocBeginTC}{}
+	\\newcommand{\\kerneldocEndTC}{}
+	\\newcommand{\\kerneldocBeginKR}{}
+	\\newcommand{\\kerneldocEndKR}{}
+	\\newcommand{\\kerneldocBeginSC}{}
+	\\newcommand{\\kerneldocEndKR}{}
     }
 '''
 
diff --git a/Documentation/translations/ja_JP/index.rst b/Documentation/translations/ja_JP/index.rst
index f94ba62d41c3..88d4d98eed15 100644
--- a/Documentation/translations/ja_JP/index.rst
+++ b/Documentation/translations/ja_JP/index.rst
@@ -3,6 +3,7 @@
 	\renewcommand\thesection*
 	\renewcommand\thesubsection*
 	\kerneldocCJKon
+	\kerneldocBeginJP
 
 Japanese translations
 =====================
@@ -11,3 +12,7 @@ Japanese translations
    :maxdepth: 1
 
    howto
+
+.. raw:: latex
+
+	\kerneldocEndJP
diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst
index 6ae258118bdf..f636b482fb4c 100644
--- a/Documentation/translations/ko_KR/index.rst
+++ b/Documentation/translations/ko_KR/index.rst
@@ -3,6 +3,7 @@
 	\renewcommand\thesection*
 	\renewcommand\thesubsection*
 	\kerneldocCJKon
+	\kerneldocBeginKR
 
 한국어 번역
 ===========
@@ -26,3 +27,4 @@
 .. raw:: latex
 
     \normalsize
+    \kerneldocEndKR
diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst
index e0d51a167032..510ec10959fa 100644
--- a/Documentation/translations/zh_CN/index.rst
+++ b/Documentation/translations/zh_CN/index.rst
@@ -5,6 +5,7 @@
 	\renewcommand\thesection*
 	\renewcommand\thesubsection*
 	\kerneldocCJKon
+	\kerneldocBeginSC
 
 .. _linux_doc_zh:
 
@@ -189,3 +190,7 @@ TODOList:
 ----------
 
 * :ref:`genindex`
+
+.. raw:: latex
+
+	\kerneldocEndSC
-- 
2.17.1

[PATCH v3 3/9] docs: pdfdocs: Choose Serif font as CJK mainfont if possible

[Akira Yokosawa]

"Noto Serif CJK SC" and its variants suit better with the roman font
of Latin letters.

On some distros such as Fedora, it is possible to partially install
"Noto Sans CJK" fonts.
So, if the Serif fonts are not found on the system, fall back to the
Sans fonts.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 Documentation/conf.py | 41 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 24e5427588e7..980be06df723 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -360,20 +360,48 @@ latex_elements['preamble']  += '''
     \\IfFontExistsTF{Noto Sans CJK SC}{
 	% This is needed for translations
 	\\usepackage{xeCJK}
-	\\setCJKmainfont{Noto Sans CJK SC}
+	\\IfFontExistsTF{Noto Serif CJK SC}{
+	    \\setCJKmainfont{Noto Serif CJK SC}
+	}{
+	    \\setCJKmainfont{Noto Sans CJK SC}
+	}
 	\\setCJKsansfont{Noto Sans CJK SC}
 	\\setCJKmonofont{Noto Sans Mono CJK SC}
 	% CJK Language-specific font choices
-	\\newCJKfontfamily[SCmain]\\scmain{Noto Sans CJK SC}
+	\\IfFontExistsTF{Noto Serif CJK SC}{
+	    \\newCJKfontfamily[SCmain]\\scmain{Noto Serif CJK SC}
+	    \\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}
+	}{
+	    \\newCJKfontfamily[SCmain]\\scmain{Noto Sans CJK SC}
+	    \\newCJKfontfamily[SCserif]\\scserif{Noto Sans CJK SC}
+	}
 	\\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}
 	\\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}
-	\\newCJKfontfamily[TCmain]\\tcmain{Noto Sans CJK TC}
+	\\IfFontExistsTF{Noto Serif CJK TC}{
+	    \\newCJKfontfamily[TCmain]\\tcmain{Noto Serif CJK TC}
+	    \\newCJKfontfamily[TCserif]\\tcserif{Noto Serif CJK TC}
+	}{
+	    \\newCJKfontfamily[TCmain]\\tcmain{Noto Sans CJK TC}
+	    \\newCJKfontfamily[TCserif]\\tcserif{Noto Sans CJK TC}
+	}
 	\\newCJKfontfamily[TCsans]\\tcsans{Noto Sans CJK TC}
 	\\newCJKfontfamily[TCmono]\\tcmono{Noto Sans Mono CJK TC}
-	\\newCJKfontfamily[KRmain]\\krmain{Noto Sans CJK KR}
+	\\IfFontExistsTF{Noto Serif CJK KR}{
+	    \\newCJKfontfamily[KRmain]\\krmain{Noto Serif CJK KR}
+	    \\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}
+	}{
+	    \\newCJKfontfamily[KRmain]\\krmain{Noto Sans CJK KR}
+	    \\newCJKfontfamily[KRserif]\\krserif{Noto Sans CJK KR}
+	}
 	\\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}
 	\\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}
-	\\newCJKfontfamily[JPmain]\\jpmain{Noto Sans CJK JP}
+	\\IfFontExistsTF{Noto Serif CJK JP}{
+	    \\newCJKfontfamily[JPmain]\\jpmain{Noto Serif CJK JP}
+	    \\newCJKfontfamily[JPserif]\\jpserif{Noto Serif CJK JP}
+	}{
+	    \\newCJKfontfamily[JPmain]\\jpmain{Noto Sans CJK JP}
+	    \\newCJKfontfamily[JPserif]\\jpserif{Noto Sans CJK JP}
+	}
 	\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}
 	\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}
 	% Define custom macros to on/off CJK
@@ -387,6 +415,7 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocBeginTC}{%
 	    \\begingroup%
 	    \\tcmain%
+	    \\renewcommand{\\CJKrmdefault}{TCserif}%
 	    \\renewcommand{\\CJKsfdefault}{TCsans}%
 	    \\renewcommand{\\CJKttdefault}{TCmono}%
 	}
@@ -394,6 +423,7 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocBeginKR}{%
 	    \\begingroup%
 	    \\krmain%
+	    \\renewcommand{\\CJKrmdefault}{KRserif}%
 	    \\renewcommand{\\CJKsfdefault}{KRsans}%
 	    \\renewcommand{\\CJKttdefault}{KRmono}%
 	}
@@ -401,6 +431,7 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocBeginJP}{%
 	    \\begingroup%
 	    \\jpmain%
+	    \\renewcommand{\\CJKrmdefault}{JPserif}%
 	    \\renewcommand{\\CJKsfdefault}{JPsans}%
 	    \\renewcommand{\\CJKttdefault}{JPmono}%
 	}
-- 
2.17.1

[PATCH v3 4/9] docs: pdfdocs: Preserve inter-phrase space in Korean translations

[Akira Yokosawa]

In Korean typesetting, inter-phrase spaces in Hangul text have
a similar role as the inter-word spaces in Latin text.
They can be preserved by the \xeCJKsetup{CJKspace=true} option.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 Documentation/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 980be06df723..2ccfe4442acc 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -426,6 +426,7 @@ latex_elements['preamble']  += '''
 	    \\renewcommand{\\CJKrmdefault}{KRserif}%
 	    \\renewcommand{\\CJKsfdefault}{KRsans}%
 	    \\renewcommand{\\CJKttdefault}{KRmono}%
+	    \\xeCJKsetup{CJKspace = true} % For inter-phrase space
 	}
 	\\newcommand{\\kerneldocEndKR}{\\endgroup}
 	\\newcommand{\\kerneldocBeginJP}{%
-- 
2.17.1

[PATCH v3 5/9] docs: pdfdocs: Add conf.py local to translations for ascii-art alignment

[Akira Yokosawa]

Globally choosing "Noto Sans Mono CJK SC" would result in sub-optimal look
of literal blocks in Latin documents.
Therefore, localize the font choice to translations by adding conf.py under
Documentation/translations/.

The local conf.py is enabled when the command:

    make SPHINXDIRS=translations pdfdocs

is used to build the PDF.
Resulting translations.pdf (under Documentation/output/translations/pdf)
will have properly aligned ascii-art figures.

NOTE: There remain mis-aligned ascii-art figures in Korean translations.
This is due to the font designer's decision to assign slightly narrower
widths (920) to Hangul characters in "Noto Sans Mono CJK KR" than those
of Hanja (Hanzi/Kanji) characters (1000) [1].

[1]: https://github.com/googlefonts/noto-cjk/issues/17

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 Documentation/translations/conf.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 Documentation/translations/conf.py

diff --git a/Documentation/translations/conf.py b/Documentation/translations/conf.py
new file mode 100644
index 000000000000..e859c2e19e8b
--- /dev/null
+++ b/Documentation/translations/conf.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+# SPDX-License-Identifier: GPL-2.0
+
+# -- Additinal options for LaTeX output ----------------------------------
+# font config for ascii-art alignment
+
+latex_elements['preamble']  += '''
+    \\IfFontExistsTF{Noto Sans CJK SC}{
+	% For CJK ascii-art alignment
+	\\setmonofont{Noto Sans Mono CJK SC}
+    }{}
+'''
-- 
2.17.1

[PATCH v3 6/9] docs: pdfdocs: One-half spacing for CJK translations

[Akira Yokosawa]

CJK documents are much easier to read with a wider baseline stretch.
Applying the onehalfspacing option of "setspace" package looks
reasonable.

Note: \usepackage{setspace} needs to be before that of hyperref in the
preamble.  The 'extrapackages' key (available since Sphinx 2.3) is for
this purpose.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 Documentation/conf.py                      | 9 +++++++--
 Documentation/translations/ja_JP/howto.rst | 8 ++++++++
 Documentation/translations/ko_KR/howto.rst | 8 ++++++++
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 2ccfe4442acc..2e54488e2480 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -341,6 +341,9 @@ latex_elements = {
         verbatimhintsturnover=false,
     ''',
 
+    # For CJK One-half spacing, need to be in front of hyperref
+    'extrapackages': r'\usepackage{setspace}',
+
     # Additional stuff for the LaTeX preamble.
     'preamble': '''
 	% Prevent column squeezing of tabulary.
@@ -405,8 +408,8 @@ latex_elements['preamble']  += '''
 	\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}
 	\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}
 	% Define custom macros to on/off CJK
-	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive}
-	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive}
+	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing}
+	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive\\singlespacing}
 	\\newcommand{\\kerneldocBeginSC}{%
 	    \\begingroup%
 	    \\scmain%
@@ -437,6 +440,8 @@ latex_elements['preamble']  += '''
 	    \\renewcommand{\\CJKttdefault}{JPmono}%
 	}
 	\\newcommand{\\kerneldocEndJP}{\\endgroup}
+	% Single spacing in literal blocks
+	\\fvset{baselinestretch=1}
 	% To customize \\sphinxtableofcontents
 	\\usepackage{etoolbox}
 	% Inactivate CJK after tableofcontents
diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst
index 73ebdab4ced7..d667f9d8a02a 100644
--- a/Documentation/translations/ja_JP/howto.rst
+++ b/Documentation/translations/ja_JP/howto.rst
@@ -1,3 +1,7 @@
+.. raw:: latex
+
+	\kerneldocCJKoff
+
 NOTE:
 This is a version of Documentation/process/howto.rst translated into Japanese.
 This document is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
@@ -11,6 +15,10 @@ try to update the original English file first.
 
 ----------------------------------
 
+.. raw:: latex
+
+	\kerneldocCJKon
+
 この文書は、
 Documentation/process/howto.rst
 の和訳です。
diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst
index a2bdd564c907..e3cdf0c84892 100644
--- a/Documentation/translations/ko_KR/howto.rst
+++ b/Documentation/translations/ko_KR/howto.rst
@@ -1,3 +1,7 @@
+.. raw:: latex
+
+	\kerneldocCJKoff
+
 NOTE:
 This is a version of Documentation/process/howto.rst translated into korean
 This document is maintained by Minchan Kim <minchan@kernel.org>
@@ -11,6 +15,10 @@ try to update the original English file first.
 
 ----------------------------------
 
+.. raw:: latex
+
+	\kerneldocCJKon
+
 이 문서는
 Documentation/process/howto.rst
 의 한글 번역입니다.
-- 
2.17.1

Re: [PATCH v3 6/9] docs: pdfdocs: One-half spacing for CJK translations

[Akira Yokosawa]

On Mon, 2 Aug 2021 18:56:16 +0900, Akira Yokosawa wrote:
> CJK documents are much easier to read with a wider baseline stretch.
> Applying the onehalfspacing option of "setspace" package looks
> reasonable.
> 
> Note: \usepackage{setspace} needs to be before that of hyperref in the
> preamble.  The 'extrapackages' key (available since Sphinx 2.3) is for
> this purpose.

Sphinx versions < 2.3 ignore 'extrapackages' and generate LaTeX
sources without setspace package.
Obviously, building such LaTeX sources will end up in the error of:

    ! Undefined control sequence.
    \kerneldocCJKoff ...exeCJKinactive \singlespacing

Current requirement to build pdfdocs is Sphinx 2.4.4, but LaTeX
sources generated by 1.7.9 can at least be built prior to this change.

Jon, Mauro, do you think this is a regression?

You can skip 6/9 if you'd like. 

I'll see what can be done for compatibility with Sphinx < 2.3.

        Thanks, Akira

> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> ---
>  Documentation/conf.py                      | 9 +++++++--
>  Documentation/translations/ja_JP/howto.rst | 8 ++++++++
>  Documentation/translations/ko_KR/howto.rst | 8 ++++++++
>  3 files changed, 23 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 2ccfe4442acc..2e54488e2480 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -341,6 +341,9 @@ latex_elements = {
>          verbatimhintsturnover=false,
>      ''',
>  
> +    # For CJK One-half spacing, need to be in front of hyperref
> +    'extrapackages': r'\usepackage{setspace}',
> +
>      # Additional stuff for the LaTeX preamble.
>      'preamble': '''
>  	% Prevent column squeezing of tabulary.
> @@ -405,8 +408,8 @@ latex_elements['preamble']  += '''
>  	\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}
>  	\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}
>  	% Define custom macros to on/off CJK
> -	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive}
> -	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive}
> +	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing}
> +	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive\\singlespacing}
>  	\\newcommand{\\kerneldocBeginSC}{%
>  	    \\begingroup%
>  	    \\scmain%
> @@ -437,6 +440,8 @@ latex_elements['preamble']  += '''
>  	    \\renewcommand{\\CJKttdefault}{JPmono}%
>  	}
>  	\\newcommand{\\kerneldocEndJP}{\\endgroup}
> +	% Single spacing in literal blocks
> +	\\fvset{baselinestretch=1}
>  	% To customize \\sphinxtableofcontents
>  	\\usepackage{etoolbox}
>  	% Inactivate CJK after tableofcontents
> diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst
> index 73ebdab4ced7..d667f9d8a02a 100644
> --- a/Documentation/translations/ja_JP/howto.rst
> +++ b/Documentation/translations/ja_JP/howto.rst
> @@ -1,3 +1,7 @@
> +.. raw:: latex
> +
> +	\kerneldocCJKoff
> +
>  NOTE:
>  This is a version of Documentation/process/howto.rst translated into Japanese.
>  This document is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
> @@ -11,6 +15,10 @@ try to update the original English file first.
>  
>  ----------------------------------
>  
> +.. raw:: latex
> +
> +	\kerneldocCJKon
> +
>  この文書は、
>  Documentation/process/howto.rst
>  の和訳です。
> diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst
> index a2bdd564c907..e3cdf0c84892 100644
> --- a/Documentation/translations/ko_KR/howto.rst
> +++ b/Documentation/translations/ko_KR/howto.rst
> @@ -1,3 +1,7 @@
> +.. raw:: latex
> +
> +	\kerneldocCJKoff
> +
>  NOTE:
>  This is a version of Documentation/process/howto.rst translated into korean
>  This document is maintained by Minchan Kim <minchan@kernel.org>
> @@ -11,6 +15,10 @@ try to update the original English file first.
>  
>  ----------------------------------
>  
> +.. raw:: latex
> +
> +	\kerneldocCJKon
> +
>  이 문서는
>  Documentation/process/howto.rst
>  의 한글 번역입니다.
> 

Re: [PATCH v3 6/9] docs: pdfdocs: One-half spacing for CJK translations

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> On Mon, 2 Aug 2021 18:56:16 +0900, Akira Yokosawa wrote:
>> CJK documents are much easier to read with a wider baseline stretch.
>> Applying the onehalfspacing option of "setspace" package looks
>> reasonable.
>> 
>> Note: \usepackage{setspace} needs to be before that of hyperref in the
>> preamble.  The 'extrapackages' key (available since Sphinx 2.3) is for
>> this purpose.
>
> Sphinx versions < 2.3 ignore 'extrapackages' and generate LaTeX
> sources without setspace package.
> Obviously, building such LaTeX sources will end up in the error of:
>
>     ! Undefined control sequence.
>     \kerneldocCJKoff ...exeCJKinactive \singlespacing
>
> Current requirement to build pdfdocs is Sphinx 2.4.4, but LaTeX
> sources generated by 1.7.9 can at least be built prior to this change.
>
> Jon, Mauro, do you think this is a regression?

Having the build just fail that way isn't really a good thing...it would
be far better to do the baseline tweaking only with versions of sphinx
that support it or, failing that, to at least refuse to build with a
suitably informative message.

Thanks,

jon

Re: [PATCH v3 6/9] docs: pdfdocs: One-half spacing for CJK translations

[Akira Yokosawa]

On Thu, 12 Aug 2021 08:42:48 -0600, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> On Mon, 2 Aug 2021 18:56:16 +0900, Akira Yokosawa wrote:
>>> CJK documents are much easier to read with a wider baseline stretch.
>>> Applying the onehalfspacing option of "setspace" package looks
>>> reasonable.
>>>
>>> Note: \usepackage{setspace} needs to be before that of hyperref in the
>>> preamble.  The 'extrapackages' key (available since Sphinx 2.3) is for
>>> this purpose.
>>
>> Sphinx versions < 2.3 ignore 'extrapackages' and generate LaTeX
>> sources without setspace package.
>> Obviously, building such LaTeX sources will end up in the error of:
>>
>>     ! Undefined control sequence.
>>     \kerneldocCJKoff ...exeCJKinactive \singlespacing
>>
>> Current requirement to build pdfdocs is Sphinx 2.4.4, but LaTeX
>> sources generated by 1.7.9 can at least be built prior to this change.
>>
>> Jon, Mauro, do you think this is a regression?
> 
> Having the build just fail that way isn't really a good thing...it would
> be far better to do the baseline tweaking only with versions of sphinx
> that support it or, failing that, to at least refuse to build with a
> suitably informative message.

Hi Jon,

This issue is fixed in v4 of the patch set.
Can you please consider pulling v4?

I have tested it against Sphinx versions 1.7.9, 2.4.4, and 4.1.2.

v4: https://lore.kernel.org/linux-doc/39d0fb0f-b248-bca4-2dac-df69e8d697b1@gmail.com/T/

        Thanks, Akira
 
> 
> Thanks,
> 
> jon
> 

Re: [PATCH v3 6/9] docs: pdfdocs: One-half spacing for CJK translations

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> On Thu, 12 Aug 2021 08:42:48 -0600, Jonathan Corbet wrote:
>> Akira Yokosawa <akiyks@gmail.com> writes:
>> 
>>> On Mon, 2 Aug 2021 18:56:16 +0900, Akira Yokosawa wrote:
>>>> CJK documents are much easier to read with a wider baseline stretch.
>>>> Applying the onehalfspacing option of "setspace" package looks
>>>> reasonable.
>>>>
>>>> Note: \usepackage{setspace} needs to be before that of hyperref in the
>>>> preamble.  The 'extrapackages' key (available since Sphinx 2.3) is for
>>>> this purpose.
>>>
>>> Sphinx versions < 2.3 ignore 'extrapackages' and generate LaTeX
>>> sources without setspace package.
>>> Obviously, building such LaTeX sources will end up in the error of:
>>>
>>>     ! Undefined control sequence.
>>>     \kerneldocCJKoff ...exeCJKinactive \singlespacing
>>>
>>> Current requirement to build pdfdocs is Sphinx 2.4.4, but LaTeX
>>> sources generated by 1.7.9 can at least be built prior to this change.
>>>
>>> Jon, Mauro, do you think this is a regression?
>> 
>> Having the build just fail that way isn't really a good thing...it would
>> be far better to do the baseline tweaking only with versions of sphinx
>> that support it or, failing that, to at least refuse to build with a
>> suitably informative message.
>
> Hi Jon,
>
> This issue is fixed in v4 of the patch set.
> Can you please consider pulling v4?
>
> I have tested it against Sphinx versions 1.7.9, 2.4.4, and 4.1.2.

Ouch, weird...I definitely got v4, but somehow it managed to evade my
docs folder.  Apologies for that; I've just applied that version.

Thanks,

jon

[PATCH v3 7/9] docs: pdfdocs: Permit AutoFakeSlant for CJK fonts

[Akira Yokosawa]

Noto CJK fonts don't provide italic shapes.
The AutoFakeSlant option of fontspec and xeCJK packages can be used as
a workaround.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 Documentation/conf.py              | 56 +++++++++++++++---------------
 Documentation/translations/conf.py |  2 +-
 2 files changed, 29 insertions(+), 29 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 2e54488e2480..c4813e51dbc9 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -364,49 +364,49 @@ latex_elements['preamble']  += '''
 	% This is needed for translations
 	\\usepackage{xeCJK}
 	\\IfFontExistsTF{Noto Serif CJK SC}{
-	    \\setCJKmainfont{Noto Serif CJK SC}
+	    \\setCJKmainfont{Noto Serif CJK SC}[AutoFakeSlant]
 	}{
-	    \\setCJKmainfont{Noto Sans CJK SC}
+	    \\setCJKmainfont{Noto Sans CJK SC}[AutoFakeSlant]
 	}
-	\\setCJKsansfont{Noto Sans CJK SC}
-	\\setCJKmonofont{Noto Sans Mono CJK SC}
+	\\setCJKsansfont{Noto Sans CJK SC}[AutoFakeSlant]
+	\\setCJKmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]
 	% CJK Language-specific font choices
 	\\IfFontExistsTF{Noto Serif CJK SC}{
-	    \\newCJKfontfamily[SCmain]\\scmain{Noto Serif CJK SC}
-	    \\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}
+	    \\newCJKfontfamily[SCmain]\\scmain{Noto Serif CJK SC}[AutoFakeSlant]
+	    \\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}[AutoFakeSlant]
 	}{
-	    \\newCJKfontfamily[SCmain]\\scmain{Noto Sans CJK SC}
-	    \\newCJKfontfamily[SCserif]\\scserif{Noto Sans CJK SC}
+	    \\newCJKfontfamily[SCmain]\\scmain{Noto Sans CJK SC}[AutoFakeSlant]
+	    \\newCJKfontfamily[SCserif]\\scserif{Noto Sans CJK SC}[AutoFakeSlant]
 	}
-	\\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}
-	\\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}
+	\\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}[AutoFakeSlant]
+	\\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant]
 	\\IfFontExistsTF{Noto Serif CJK TC}{
-	    \\newCJKfontfamily[TCmain]\\tcmain{Noto Serif CJK TC}
-	    \\newCJKfontfamily[TCserif]\\tcserif{Noto Serif CJK TC}
+	    \\newCJKfontfamily[TCmain]\\tcmain{Noto Serif CJK TC}[AutoFakeSlant]
+	    \\newCJKfontfamily[TCserif]\\tcserif{Noto Serif CJK TC}[AutoFakeSlant]
 	}{
-	    \\newCJKfontfamily[TCmain]\\tcmain{Noto Sans CJK TC}
-	    \\newCJKfontfamily[TCserif]\\tcserif{Noto Sans CJK TC}
+	    \\newCJKfontfamily[TCmain]\\tcmain{Noto Sans CJK TC}[AutoFakeSlant]
+	    \\newCJKfontfamily[TCserif]\\tcserif{Noto Sans CJK TC}[AutoFakeSlant]
 	}
-	\\newCJKfontfamily[TCsans]\\tcsans{Noto Sans CJK TC}
-	\\newCJKfontfamily[TCmono]\\tcmono{Noto Sans Mono CJK TC}
+	\\newCJKfontfamily[TCsans]\\tcsans{Noto Sans CJK TC}[AutoFakeSlant]
+	\\newCJKfontfamily[TCmono]\\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant]
 	\\IfFontExistsTF{Noto Serif CJK KR}{
-	    \\newCJKfontfamily[KRmain]\\krmain{Noto Serif CJK KR}
-	    \\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}
+	    \\newCJKfontfamily[KRmain]\\krmain{Noto Serif CJK KR}[AutoFakeSlant]
+	    \\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}[AutoFakeSlant]
 	}{
-	    \\newCJKfontfamily[KRmain]\\krmain{Noto Sans CJK KR}
-	    \\newCJKfontfamily[KRserif]\\krserif{Noto Sans CJK KR}
+	    \\newCJKfontfamily[KRmain]\\krmain{Noto Sans CJK KR}[AutoFakeSlant]
+	    \\newCJKfontfamily[KRserif]\\krserif{Noto Sans CJK KR}[AutoFakeSlant]
 	}
-	\\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}
-	\\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}
+	\\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}[AutoFakeSlant]
+	\\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant]
 	\\IfFontExistsTF{Noto Serif CJK JP}{
-	    \\newCJKfontfamily[JPmain]\\jpmain{Noto Serif CJK JP}
-	    \\newCJKfontfamily[JPserif]\\jpserif{Noto Serif CJK JP}
+	    \\newCJKfontfamily[JPmain]\\jpmain{Noto Serif CJK JP}[AutoFakeSlant]
+	    \\newCJKfontfamily[JPserif]\\jpserif{Noto Serif CJK JP}[AutoFakeSlant]
 	}{
-	    \\newCJKfontfamily[JPmain]\\jpmain{Noto Sans CJK JP}
-	    \\newCJKfontfamily[JPserif]\\jpserif{Noto Sans CJK JP}
+	    \\newCJKfontfamily[JPmain]\\jpmain{Noto Sans CJK JP}[AutoFakeSlant]
+	    \\newCJKfontfamily[JPserif]\\jpserif{Noto Sans CJK JP}[AutoFakeSlant]
 	}
-	\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}
-	\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}
+	\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}[AutoFakeSlant]
+	\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant]
 	% Define custom macros to on/off CJK
 	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing}
 	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive\\singlespacing}
diff --git a/Documentation/translations/conf.py b/Documentation/translations/conf.py
index e859c2e19e8b..92cdbba74229 100644
--- a/Documentation/translations/conf.py
+++ b/Documentation/translations/conf.py
@@ -7,6 +7,6 @@
 latex_elements['preamble']  += '''
     \\IfFontExistsTF{Noto Sans CJK SC}{
 	% For CJK ascii-art alignment
-	\\setmonofont{Noto Sans Mono CJK SC}
+	\\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]
     }{}
 '''
-- 
2.17.1

[PATCH v3 8/9] docs: pdfdocs: Teach xeCJK about character classes of quotation marks

[Akira Yokosawa]

Quotation marks in "KR" and "JP" variants of Noto CJK fonts are half
width.
xeCJK assumes they are full width by default and does excessive kerning
around them in Korean and Japanese translations.

Give xeCJK proper hints by the \xeCJKDeclareCharClass command.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 Documentation/conf.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index c4813e51dbc9..846d57eba57c 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -425,6 +425,8 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocEndTC}{\\endgroup}
 	\\newcommand{\\kerneldocBeginKR}{%
 	    \\begingroup%
+	    \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}%
+	    \\xeCJKDeclareCharClass{HalfRight}{`”,`’}%
 	    \\krmain%
 	    \\renewcommand{\\CJKrmdefault}{KRserif}%
 	    \\renewcommand{\\CJKsfdefault}{KRsans}%
@@ -434,6 +436,8 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocEndKR}{\\endgroup}
 	\\newcommand{\\kerneldocBeginJP}{%
 	    \\begingroup%
+	    \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}%
+	    \\xeCJKDeclareCharClass{HalfRight}{`”,`’}%
 	    \\jpmain%
 	    \\renewcommand{\\CJKrmdefault}{JPserif}%
 	    \\renewcommand{\\CJKsfdefault}{JPsans}%
-- 
2.17.1

[PATCH v3 9/9] docs: pdfdocs: Enable language-specific font choice of zh_TW translations

[Akira Yokosawa]

The "TC" variant is supposed to be the choice for traditional
Chinese documents.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Hu Haowen <src.res@email.cn>
---
 Documentation/translations/zh_TW/index.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst
index 76981b2111f6..c02c4b5281e6 100644
--- a/Documentation/translations/zh_TW/index.rst
+++ b/Documentation/translations/zh_TW/index.rst
@@ -5,6 +5,7 @@
 	\renewcommand\thesection*
 	\renewcommand\thesubsection*
 	\kerneldocCJKon
+	\kerneldocBeginTC
 
 .. _linux_doc_zh_tw:
 
@@ -162,3 +163,6 @@ TODOList:
 
 * :ref:`genindex`
 
+.. raw:: latex
+
+	\kerneldocEndTC
-- 
2.17.1

Re: [PATCH v3 9/9] docs: pdfdocs: Enable language-specific font choice of zh_TW translations

[Hu Haowen]

在 2021/8/2 下午6:00, Akira Yokosawa 写道:
> The "TC" variant is supposed to be the choice for traditional
> Chinese documents.
>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: Hu Haowen <src.res@email.cn>


Well done!

Reviewed-by: Hu Haowen <src.res@email.cn>
Tested-by: Hu Haowen <src.res@email.cn>

Cheers,
Hu Haowen


> ---
>  Documentation/translations/zh_TW/index.rst | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst
> index 76981b2111f6..c02c4b5281e6 100644
> --- a/Documentation/translations/zh_TW/index.rst
> +++ b/Documentation/translations/zh_TW/index.rst
> @@ -5,6 +5,7 @@
>  	\renewcommand\thesection*
>  	\renewcommand\thesubsection*
>  	\kerneldocCJKon
> +	\kerneldocBeginTC
>  
>  .. _linux_doc_zh_tw:
>  
> @@ -162,3 +163,6 @@ TODOList:
>  
>  * :ref:`genindex`
>  
> +.. raw:: latex
> +
> +	\kerneldocEndTC