[RFC PATCH v2 0/7] docs: pdfdocs: Improve font choice in CJK translations

[RFC PATCH v2 0/7] docs: pdfdocs: Improve font choice in CJK translations

[Akira Yokosawa]

Hi all,

I'm calling this patch set "RFC PATCH v2", but the approach has changed
a lot since "RFC PATCH 0/3 docs: pdfdocs: Improve alignment of CJK
ascii-art" [1], hence the different title.

I added Hu Haowen, who is working on zh_TW translations, and Shinwoo Lee,
who has recently shown interest in enhancing ko_KR translations [2] but
has got no public response yet, in the CC list in the faint hope of their
interest in CJK typesetting by Sphinx + XeLaTeX.  If either (or both) of
you has no interest, please let me know.  I won't bother you in this area.

I thought it was impossible to switch CJK font choices in the middle
of a document, but it turns out it is actually possible.

Patch 1/7 is mostly the same as the original "RFC PATCH 1/3".

Patch 2/7 is the most important change in this patch set.
It introduces a pair of LaTeX macros for each CJK language:
    zh_CN:  \kerneldocBeginSC, \kerneldocEndSC
    ko_KR:  \kerneldocBeginKR, \kerneldocEndKR
    ja_JP:  \kerneldocBeginJP, \kerneldocEndJP

, which perform magical font settings for the languages.

Each pair of macros are added in translations' respective index.rst.

As for Hangul inter-phrase spaces, xeCJK provides a knob to preserve
them.  \kerneldocBeginKR has the knob enabled.

Also note that CJKmainfont is changed from "Noto Sans CJK" to "Noto
Serif CJK", as the latter looks more consistent with the roman (serif)
family of Latin text.

The font choice of latin monospace letters is overridden (for
ascii-art alignmet) only when the document is built by
"make SPHINXDIRS=translations pdfdocs".

As for the to-be-merged zh_TW translations, the same approach should
work by choosing "Noto xxxx CJK TC" fonts.

There remain a couple of glitches remaining as of Patch 2/7.
Following patches address them one by one.

Patch 3/7 increases line spacing of CJK contents.
In general, CJK characters in single spacing looks too busy.
One-half spacing generates a reasonable result (to my eyes).

Patch 4/7 is a workaround of "Noto CJK" fonts' lack of italic shapes.

Patch 5/7 fixes excessive kerning by xeCJK around quotation marks
in Korean and Japanese translations. Quotation marks in "Noto Serif
CJK KR" and "Not Serif CJK JP" fonts are half-width rather than
full-width in "Noto Serif CJK SC".

Patches 6/7 and 7/7 corresponds to 2/3 and 3/3 in the original RFC.
They attempt to align ascii-art figures found in the Korean translation
of memory-barriers.txt.

Now, candidates of *true* monospace font for Hangul are:

    D2Coding, Sarasa Mono K, and (ugly looking) Unifont.

I said earlier in response to Mauro's concerns with regard to
"Sarasa Mono" font and sphinx-pre-install [3]:

Akira>>> Existence of "Sarasa Mono SC" can be checked by the command:
     >>>
     >>>     fc-list | grep "Sarasa Mono SC," | grep "style=Regular" | wc -l
     >>>
     >>> If the result is *not* "0", you have the font somewhere in your
     >>> fontconfig path.
     >>>
     >>> I think this is portable across distros.
     >>> Wouldn't this suffice for sphinx-pre-install?
Mauro>> 
     >> No. The sphinx-pre-install tool generate a list of commands
     >> needed to install the pre-reqs on a given distro.
     >> ...
     >> The same command, when executed on a different distro will
     >> print a different set of packages and commands.
Akira>
     > I see...
     >
     > So let's forget Unifont and "Sarasa Mono" for the time being.
     >
     > By adding some custom configuration of fontconfig, "Noto Sans Mono
     > CJK SC" can be made an alias of "Sarasa Mono", "Unifont", or whatever
     > alternative font one wants to try.

This was my misunderstanding.  Yes, alias is possible by fontconfig,
but fontconfig's alias names are not recognized by fontspec/xeCJK + XeLaTeX.
So we need to embed the actual names of candidate fonts in the preamble.

Mauro, isn't the header comment in conf.py added in Patch 6/7 good enough?
I don't think those nice-to-have fonts are pre-reqs that should be
taken care of by the sphinx-pre-install script.

On the other hand, as having heard of nothing from SeongJae, who is
the maintainer of Korean memory-barrier.txt, there might be nobody
who cares the Korean chapter in translations.pdf.
Patches 6/7 and 7/7 need explicit Acks of someone who reads it, I guess.

This series is tested against Sphinx 2.4.4 and brand-new 4.1.1.

Again, any feedback is appreciated!

	Thanks, Akira

[1]: https://lore.kernel.org/lkml/386938dc-6290-239c-4b4f-c6153f3d98c5@gmail.com/
[2]: https://lore.kernel.org/linux-doc/CAJMZz3_M34cy4ZbKGLZniGeUPOoJ7DMXdDOQxy-T44_cQ1+Udw@mail.gmail.com/
[3]: https://lore.kernel.org/lkml/0cfd8dfb-b304-4073-973c-930a93d19a17@gmail.com/

--
Akira Yokosawa (7):
  docs: pdfdocs: Refactor config for CJK document
  docs: pdfdocs: Add CJK-language-specific font settings
  docs: pdfdocs: Use one-half spacing in CJK translations
  docs: pdfdocs: Permit AutoFakeSlant for CJK fonts
  docs: pdfdocs: Teach xeCJK the width of quotation marks
  docs: pdfdocs: Add optional choices for Korean monospace font
  docs/ko_KR: Use white spaces behind CJK characters in ascii-art

 Documentation/conf.py                         | 77 +++++++++++++++----
 Documentation/translations/conf.py            | 44 +++++++++++
 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 +
 .../translations/ko_KR/memory-barriers.txt    | 14 ++--
 Documentation/translations/zh_CN/index.rst    |  5 ++
 8 files changed, 140 insertions(+), 23 deletions(-)
 create mode 100644 Documentation/translations/conf.py

-- 
2.17.1

[RFC PATCH v2 1/7] 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.

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

[RFC PATCH v2 2/7] docs: pdfdocs: Add CJK-language-specific font settings

[Akira Yokosawa]

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
    \kerneldocBeginKR
    \kerneldocEndKR
    \kerneldocBeginJP
    \kerneldocEndJP

Note that CJKmainfont is changed to "Noto Serif CJK SC" as it suits well
with the roman font of Latin letters.

As for Korean translations, inter-phrase spaces in Hangul text can be
preserved by the \xeCJKsetup{CJKspace=true} option.

As for monospace font, employing "Noto Sans Mono CJK SC" globally
will result in sub-optimal look of literal blocks in Latin documents
due to its rather tight width.
So, localize the font choice by adding conf.py under
Documentation/translations/.
The additional 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 except for those in Korean
translations.

NOTE 1: Korean ascii-art figures' mis-alignment is due to the fact that
Hangul characters in "Noto Sans Mono CJK KR" are slightly narrower than
Hanja characters.

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_CN page to be properly typeset.

NOTE 3: Actual implementation of added macros has rooms to improve.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 Documentation/conf.py                      | 44 +++++++++++++++++++++-
 Documentation/translations/conf.py         | 12 ++++++
 Documentation/translations/ja_JP/index.rst |  5 +++
 Documentation/translations/ko_KR/index.rst |  2 +
 Documentation/translations/zh_CN/index.rst |  5 +++
 5 files changed, 66 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/translations/conf.py

diff --git a/Documentation/conf.py b/Documentation/conf.py
index b440cb606d22..a61628339d55 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -360,11 +360,45 @@ latex_elements['preamble']  += '''
     \\IfFontExistsTF{Noto Sans CJK SC}{
 	% This is needed for translations
 	\\usepackage{xeCJK}
-	\\setCJKmainfont{Noto Sans CJK SC}
+	\\setCJKmainfont{Noto Serif CJK SC}
+	\\setCJKsansfont{Noto Sans CJK SC}
+	\\setCJKmonofont{Noto Sans Mono CJK SC}
+	% CJK Language-specific font choices
+	\\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}
+	\\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}
+	\\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}
+	\\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}
+	\\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}
+	\\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}
+	\\newCJKfontfamily[JPserif]\\jpserif{Noto Serif 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%
+	    \\scserif%
+	    }
+	\\newcommand{\\kerneldocEndSC}{\\endgroup}
+	\\newcommand{\\kerneldocBeginKR}{%
+	    \\begingroup%
+	    \\krserif%
+	    \\renewcommand{\\CJKrmdefault}{KRserif}%
+	    \\renewcommand{\\CJKsfdefault}{KRsans}%
+	    \\renewcommand{\\CJKttdefault}{KRmono}%
+	    \\xeCJKsetup{CJKspace = true} % For inter-phrase space
+	    }
+	\\newcommand{\\kerneldocEndKR}{\\endgroup}
+	\\newcommand{\\kerneldocBeginJP}{%
+	    \\begingroup%
+	    \\jpserif%
+	    \\renewcommand{\\CJKrmdefault}{JPserif}%
+	    \\renewcommand{\\CJKsfdefault}{JPsans}%
+	    \\renewcommand{\\CJKttdefault}{JPmono}%
+	    }
+	\\newcommand{\\kerneldocEndJP}{\\endgroup}
+	% To customize \\sphinxtableofcontents
 	\\usepackage{etoolbox}
 	% Inactivate CJK after tableofcontents
 	\\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{}
@@ -372,6 +406,12 @@ latex_elements['preamble']  += '''
 	% Custom macros to on/off CJK (Dummy)
 	\\newcommand{\\kerneldocCJKon}{}
 	\\newcommand{\\kerneldocCJKoff}{}
+	\\newcommand{\\kerneldocBeginSC}{}
+	\\newcommand{\\kerneldocEndSC}{}
+	\\newcommand{\\kerneldocBeginKR}{}
+	\\newcommand{\\kerneldocEndKR}{}
+	\\newcommand{\\kerneldocBeginJP}{}
+	\\newcommand{\\kerneldocEndJP}{}
     }
 '''
 
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}
+    }{}
+'''
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 1f953d3439a5..23c1e595ed78 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:
 
@@ -184,3 +185,7 @@ TODOList:
 ----------
 
 * :ref:`genindex`
+
+.. raw:: latex
+
+	\kerneldocEndSC
-- 
2.17.1

[RFC PATCH v2 3/7] docs: pdfdocs: Use one-half spacing in CJK translations

[Akira Yokosawa]

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

The wider baseline is effective between \kerneldocCJKon and
\kerneldocCJKoff.

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

diff --git a/Documentation/conf.py b/Documentation/conf.py
index a61628339d55..23d647881f6e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -374,8 +374,9 @@ 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}
+	\\usepackage{setspace}
+	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing}
+	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive\\singlespacing}
 	\\newcommand{\\kerneldocBeginSC}{%
 	    \\begingroup%
 	    \\scserif%
@@ -398,6 +399,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

[RFC PATCH v2 4/7] 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              | 24 ++++++++++++------------
 Documentation/translations/conf.py |  2 +-
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 23d647881f6e..9a237471289b 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -360,19 +360,19 @@ latex_elements['preamble']  += '''
     \\IfFontExistsTF{Noto Sans CJK SC}{
 	% This is needed for translations
 	\\usepackage{xeCJK}
-	\\setCJKmainfont{Noto Serif CJK SC}
-	\\setCJKsansfont{Noto Sans CJK SC}
-	\\setCJKmonofont{Noto Sans Mono CJK SC}
+	\\setCJKmainfont{Noto Serif CJK SC}[AutoFakeSlant]
+	\\setCJKsansfont{Noto Sans CJK SC}[AutoFakeSlant]
+	\\setCJKmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]
 	% CJK Language-specific font choices
-	\\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}
-	\\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}
-	\\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}
-	\\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}
-	\\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}
-	\\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}
-	\\newCJKfontfamily[JPserif]\\jpserif{Noto Serif CJK JP}
-	\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}
-	\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}
+	\\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}[AutoFakeSlant]
+	\\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}[AutoFakeSlant]
+	\\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant]
+	\\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}[AutoFakeSlant]
+	\\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}[AutoFakeSlant]
+	\\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant]
+	\\newCJKfontfamily[JPserif]\\jpserif{Noto Serif CJK JP}[AutoFakeSlant]
+	\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}[AutoFakeSlant]
+	\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant]
 	% Define custom macros to on/off CJK
 	\\usepackage{setspace}
 	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing}
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

[RFC PATCH v2 5/7] docs: pdfdocs: Teach xeCJK the width of quotation marks

[Akira Yokosawa]

Quotation marks in "Noto Serif CJK KR" and "Not Serif CJK JP" fonts
are half width.
xeCJK assumes they are full width as in "Noto Serif CJK SC" and are
confused by the KR/JP variants.

Give xeCJK the character-class 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 9a237471289b..8a715765dada 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -384,6 +384,8 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocEndSC}{\\endgroup}
 	\\newcommand{\\kerneldocBeginKR}{%
 	    \\begingroup%
+	    \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}%
+	    \\xeCJKDeclareCharClass{HalfRight}{`”,`’}%
 	    \\krserif%
 	    \\renewcommand{\\CJKrmdefault}{KRserif}%
 	    \\renewcommand{\\CJKsfdefault}{KRsans}%
@@ -393,6 +395,8 @@ latex_elements['preamble']  += '''
 	\\newcommand{\\kerneldocEndKR}{\\endgroup}
 	\\newcommand{\\kerneldocBeginJP}{%
 	    \\begingroup%
+	    \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}%
+	    \\xeCJKDeclareCharClass{HalfRight}{`”,`’}%
 	    \\jpserif%
 	    \\renewcommand{\\CJKrmdefault}{JPserif}%
 	    \\renewcommand{\\CJKsfdefault}{JPsans}%
-- 
2.17.1

[RFC PATCH v2 6/7] docs: pdfdocs: Add optional choices for Korean monospace font

[Akira Yokosawa]

Candidates of alternative choices of a *true* monospace font would
be "D2Coding", "Sarasa Mono K", or "Unifont" font.

The alignment of Korean ascii-art figures matters when the optional
conf.py under Dodumentation/translations/ is effective.
So, add conditional settings in the local config so that when one of
the candidate fonts is found, it is used instead of "Noto Sans Mono
CJK KR".

As xeCJK does not provide a macro to redefine an existing CJK font
family, define a wrapper macro "\setKRmono" and use it in the
"\kerneldocBeginKR" macro.

Also mention the nice-to-have monospace Hangul fonts in the header
comment in conf.py.

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

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 8a715765dada..1368c64e3993 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -382,6 +382,8 @@ latex_elements['preamble']  += '''
 	    \\scserif%
 	    }
 	\\newcommand{\\kerneldocEndSC}{\\endgroup}
+	\\newcommand{\\setKRmono}{% For alternative Hangul monospace font
+	    \\renewcommand{\\CJKttdefault}{KRmono}}
 	\\newcommand{\\kerneldocBeginKR}{%
 	    \\begingroup%
 	    \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}%
@@ -389,7 +391,7 @@ latex_elements['preamble']  += '''
 	    \\krserif%
 	    \\renewcommand{\\CJKrmdefault}{KRserif}%
 	    \\renewcommand{\\CJKsfdefault}{KRsans}%
-	    \\renewcommand{\\CJKttdefault}{KRmono}%
+	    \\setKRmono%
 	    \\xeCJKsetup{CJKspace = true} % For inter-phrase space
 	    }
 	\\newcommand{\\kerneldocEndKR}{\\endgroup}
diff --git a/Documentation/translations/conf.py b/Documentation/translations/conf.py
index 92cdbba74229..0e171eed1862 100644
--- a/Documentation/translations/conf.py
+++ b/Documentation/translations/conf.py
@@ -3,10 +3,42 @@
 
 # -- Additinal options for LaTeX output ----------------------------------
 # font config for ascii-art alignment
-
+#
+# Note: Ascii-art figures involving Hangul characters need optional
+#       monospace font. (Hangul in "Noto Sans Mono CJK" is slightly narrow.)
+#       If you'd like to see properly aligned ascii-art figures in Korean
+#       translations, you need to install a *true* monospace Hangul font.
+#
+#       Candidates of such a monospace font which covers Hangul:
+#   1)  D2Coding: Availabe at
+#	    https://github.com/naver/d2codingfont/releases/latest
+#   2)  Sarasa Mono K: Available at
+#	    https://github.com/be5invis/Sarasa-Gothic/releases/latest
+#   3)  Unifont: (easy to install but poor quality)
+#	    Available as distro packages, e.g.:
+#		Ubuntu/Debian: ttf-unifont
+#		Fedora: unifont-fonts
+#
 latex_elements['preamble']  += '''
     \\IfFontExistsTF{Noto Sans CJK SC}{
 	% For CJK ascii-art alignment
 	\\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]
+	\\IfFontExistsTF{D2Coding}{
+	  \\newCJKfontfamily[KRtruemono]\\krtruemono{D2Coding}[AutoFakeSlant]
+	  \\renewcommand{\\setKRmono}{%
+	    \\renewcommand{\\CJKttdefault}{KRtruemono}}
+	}{
+	  \\IfFontExistsTF{Sarasa Mono K}{
+	    \\newCJKfontfamily[KRtruemono]\\krtruemono{Sarasa Mono K}
+	    \\renewcommand{\\setKRmono}{%
+	      \\renewcommand{\\CJKttdefault}{KRtruemono}}
+	  }{
+	    \\IfFontExistsTF{Unifont}{
+	      \\newCJKfontfamily[KRtruemono]\\krtruemono{Unifont}[AutoFakeSlant,AutoFakeBold]
+	      \\renewcommand{\\setKRmono}{%
+		\\renewcommand{\\CJKttdefault}{KRtruemono}}
+	    }{}
+	  }
+	}
     }{}
 '''
-- 
2.17.1

[RFC PATCH v2 7/7] docs/ko_KR: Use white spaces behind CJK characters in ascii-art

[Akira Yokosawa]

In literal ascii-art of Korean translation of memory-barriers.txt,
Sphinx is confused by tabs behind CJK chars and mis-caluculates number
of necessary white spaces in LaTeX code.

As a workaround, use white spaces in such cases.

"html" output is also slightly improved by this change, but still need
some proper font choice, which is out of the scope of this change.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 .../translations/ko_KR/memory-barriers.txt         | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt
index 64d932f5dc77..ff36b857ef72 100644
--- a/Documentation/translations/ko_KR/memory-barriers.txt
+++ b/Documentation/translations/ko_KR/memory-barriers.txt
@@ -1364,7 +1364,7 @@ Multicopy 원자성은 실제의 컴퓨터 시스템에서 항상 제공되지
 	=======================	=======================	=======================
 		{ X = 0, Y = 0 }
 	STORE X=1		r1=LOAD X (reads 1)	LOAD Y (reads 1)
-				<범용 배리어>		<읽기 배리어>
+				<범용 배리어>           <읽기 배리어>
 				STORE Y=r1		LOAD X
 
 CPU 2 의 Y 로의 스토어에 사용되는 X 로드의 결과가 1 이었고 CPU 3 의 Y 로드가
@@ -1394,7 +1394,7 @@ CPU 3 의 X 로드가 CPU 2 의 로드보다 뒤에 이루어졌으므로, CPU 3
 	=======================	=======================	=======================
 		{ X = 0, Y = 0 }
 	STORE X=1		r1=LOAD X (reads 1)	LOAD Y (reads 1)
-				<데이터 의존성>		<읽기 배리어>
+				<데이터 의존성>         <읽기 배리어>
 				STORE Y=r1		LOAD X (reads 0)
 
 이 변화는 non-multicopy 원자성이 만연하게 합니다: 이 예에서, CPU 2 의 X
@@ -1789,10 +1789,10 @@ CPU 메모리 배리어
 
 	TYPE		MANDATORY		SMP CONDITIONAL
 	===============	=======================	===========================
-	범용		mb()			smp_mb()
-	쓰기		wmb()			smp_wmb()
-	읽기		rmb()			smp_rmb()
-	데이터 의존성				READ_ONCE()
+	범용            mb()                    smp_mb()
+	쓰기            wmb()                   smp_wmb()
+	읽기            rmb()                   smp_rmb()
+	데이터 의존성                           READ_ONCE()
 
 
 데이터 의존성 배리어를 제외한 모든 메모리 배리어는 컴파일러 배리어를
@@ -2151,7 +2151,7 @@ wake_up() 이 무언가를 깨우게 되면, 이 함수는 범용 메모리 배
 	set_current_state();		STORE event_indicated
 	  smp_store_mb();		wake_up();
 	    STORE current->state	  ...
-	    <범용 배리어>		  <범용 배리어>
+	    <범용 배리어>                 <범용 배리어>
 	LOAD event_indicated		  if ((LOAD task->state) & TASK_NORMAL)
 					    STORE task->state
 
-- 
2.17.1

Re: [RFC PATCH v2 0/7] docs: pdfdocs: Improve font choice in CJK translations

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Hi all,
>
> I'm calling this patch set "RFC PATCH v2", but the approach has changed
> a lot since "RFC PATCH 0/3 docs: pdfdocs: Improve alignment of CJK
> ascii-art" [1], hence the different title.

Given the RFC nature, I'm assuming you're not ready to have these
applied yet.  Please do let me know when that changes...

Thanks,

jon

Re: [RFC PATCH v2 0/7] docs: pdfdocs: Improve font choice in CJK translations

[Akira Yokosawa]

On Sun, 25 Jul 2021 14:41:26 -0600, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> Hi all,
>>
>> I'm calling this patch set "RFC PATCH v2", but the approach has changed
>> a lot since "RFC PATCH 0/3 docs: pdfdocs: Improve alignment of CJK
>> ascii-art" [1], hence the different title.
> 
> Given the RFC nature, I'm assuming you're not ready to have these
> applied yet.  Please do let me know when that changes...

Will do.

As mentioned in the cover letter:

> As for the to-be-merged zh_TW translations, the same approach should
> work by choosing "Noto xxxx CJK TC" fonts.

, I'll wait until the zh_TW translations are merged (hopefully in v6)
and update this patch set so that it can cover all of zh_CN, zh_TW,
ko_KR, and ja_JP translations.

My expectation was to collect a few "Tested-by:" and "Reviewed-by"
tags, but failed so far.

Especially, I think 6/7 and 7/7 need explicit acks.
In the cover-letter, I said:

> Mauro, isn't the header comment in conf.py added in Patch 6/7 good enough?
> I don't think those nice-to-have fonts are pre-reqs that should be
> taken care of by the sphinx-pre-install script.
> 
> On the other hand, as having heard of nothing from SeongJae, who is
> the maintainer of Korean memory-barrier.txt, there might be nobody
> who cares the Korean chapter in translations.pdf.
> Patches 6/7 and 7/7 need explicit Acks of someone who reads it, I guess.

Also, I'm thinking of splitting 2/7 into smaller chunks.
It (1) introduces LaTeX macros for each CJK language, (2) changes CJKmainfont
to Serif, (3) adds translations specific conf.py to localize monospace
font choice for Latin letters, and (4) restores inter-phrase spaces in
Korean translations.

        Thanks, Akira

> 
> Thanks,
> 
> jon
>