Hi,
6/9 in v3 was not compatible with Sphinx < 2.3.
It is now fixed in v4.
Change in v3 [1] -> v4:
o Provide dummy commands for Sphinx < 2.3 to keep compatible
with Sphinx < 2.3 (6/9).
o Add Reviewed-by and Tested-by tags from Hu Haowen (9/9).
Changes in RFC v2 [2] -> v3:
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] v3: https://lore.kernel.org/linux-doc/eb8184ab-cfab-680b-f180-1157a7f709b3@gmail.com/#t
[2] RFC v2: 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
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 | 121 ++++++++++++++++++---
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, 149 insertions(+), 16 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.
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(-)
@@ -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:
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(-)
"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(-)
In Korean typesetting, inter-phrase spaces in Hangul text have
a similar role as the 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(+)
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
CJK documents are much easier to read with a wider baseline stretch.
Applying 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.
For systems with Sphinx < 2.3, dummy commands of \onehalfspacing and
\singlespacing are provided instead.
One-half spacing is not effective in LaTeX sources generated by such
revisions of Sphinx.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
Documentation/conf.py | 12 ++++++++++--
Documentation/translations/ja_JP/howto.rst | 8 ++++++++
Documentation/translations/ko_KR/howto.rst | 8 ++++++++
3 files changed, 26 insertions(+), 2 deletions(-)
@@ -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':'''%Preventcolumnsqueezingoftabulary.
@@ -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 | 56 +++++++++++++++---------------
Documentation/translations/conf.py | 2 +-
2 files changed, 29 insertions(+), 29 deletions(-)
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(+)
The "TC" variants are supposed to be the choice for traditional
Chinese documents.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Reviewed-by: Hu Haowen <redacted>
Tested-by: Hu Haowen <redacted>
---
Documentation/translations/zh_TW/index.rst | 4 ++++
1 file changed, 4 insertions(+)