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
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(-)
@@ -16,8 +16,6 @@ import sysimportosimportsphinx-fromsubprocessimportcheck_output-# Get Sphinx versionmajor,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')-ifcjk_cmd.find("Noto Sans CJK SC")>=0:-latex_elements['preamble']+='''+latex_elements['preamble']+='''+ \\IfFontExistsTF{NotoSansCJKSC}{%Thisisneededfortranslations- \\usepackage{xeCJK}- \\setCJKmainfont{NotoSansCJKSC}+ \\usepackage{xeCJK}+ \\setCJKmainfont{NotoSansCJKSC}%Definecustommacrostoon/offCJK \\newcommand{\\kerneldocCJKon}{\\makexeCJKactive} \\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive}
@@ -371,13 +368,12 @@ if cjk_cmd.find("Noto Sans CJK SC") >= 0: \\usepackage{etoolbox}%InactivateCJKaftertableofcontents \\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{}-'''-else:-latex_elements['preamble']+='''+}{%NoCJKfontfound%Custommacrostoon/offCJK(Dummy) \\newcommand{\\kerneldocCJKon}{} \\newcommand{\\kerneldocCJKoff}{}-'''+}+'''# Fix reference escape troubles with Sphinx 1.4.xifmajor==1:
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
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(-)
@@ -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 の和訳です。
@@ -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 의 한글 번역입니다.
"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(-)
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(+)
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(-)
@@ -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{NotoSansCJKSC}{%ForCJKascii-artalignment \\setmonofont{NotoSansMonoCJKSC}[AutoFakeSlant]+ \\IfFontExistsTF{D2Coding}{+ \\newCJKfontfamily[KRtruemono]\\krtruemono{D2Coding}[AutoFakeSlant]+ \\renewcommand{\\setKRmono}{%+ \\renewcommand{\\CJKttdefault}{KRtruemono}}+}{+ \\IfFontExistsTF{SarasaMonoK}{+ \\newCJKfontfamily[KRtruemono]\\krtruemono{SarasaMonoK}+ \\renewcommand{\\setKRmono}{%+ \\renewcommand{\\CJKttdefault}{KRtruemono}}+}{+ \\IfFontExistsTF{Unifont}{+ \\newCJKfontfamily[KRtruemono]\\krtruemono{Unifont}[AutoFakeSlant,AutoFakeBold]+ \\renewcommand{\\setKRmono}{%+ \\renewcommand{\\CJKttdefault}{KRtruemono}}+}{}+}+}}{}'''
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(-)
@@ -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
From: Jonathan Corbet <corbet@lwn.net> Date: 2021-07-25 20:41:29
Akira Yokosawa [off-list ref] 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
On Sun, 25 Jul 2021 14:41:26 -0600, Jonathan Corbet wrote:
Akira Yokosawa [off-list ref] writes:
quoted
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