Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
To:     Jonathan Corbet <corbet@lwn.net>,
        Mauro Carvalho Chehab <mchehab@kernel.org>
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Akira Yokosawa <akiyks@gmail.com>
From:   Akira Yokosawa <akiyks@gmail.com>
Subject: [PATCH] docs: sphinx-pre-install: Reword warning on installing cjk
 font
Message-ID: <c5652bb4-0bb0-9efa-2b80-a79793a8efa8@gmail.com>
Date:   Fri, 21 May 2021 16:14:19 +0900
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.10.0
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

Installing a ckj font as recommended by the warning message causes
generated latex code to have:

	% This is needed for translations
	\usepackage{xeCJK}
	\setCJKmainfont{Noto Sans CJK SC}

in its preamble even for an English document.

The package "xeCJK" changes wide characters' appearance including
apostrophe (single quote) and double quotes, and it changes line-break
behavior with regard to the boundary of narrow and wide characters.

This greatly degrades readability of English PDFs typeset by xelatex.

As a band-aid help, reword the message and let the user at least be
aware of the degradation.

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

I'm a newcomer to kernel-doc who started trying sphinx this week.
I have both sphinx 2.4.4 and 1.7.9 installed.
For pdfdocs, I use 2.4.4.

"make htmldocs" was fairly easy, but I struggled a while to get
PDFs as I expected.

The culprit turned out to be the "xeCJK" package mentioned above
in the change log.  It appears in all the generated latex files
due to the "Noto Sans CJK" font I have installed seeing the warning
message from sphinx-pre-install.

By uninstalling the font, I can now build the PDF as I expect.

The reworded message is just a band-aid help.

In the long term, I see that rst2pdf tool is your hope to avoid
LaTeX altogether.  But it would be nice if you can enable xeCJK only
for the translations document.  Can sphinx permit such language
choice per subdirectory (or hopefully per .rst file)?

        Thanks, Akira
--
 scripts/sphinx-pre-install | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index fe92020d67e3..b3c7da2b8ad2 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -101,7 +101,12 @@ sub check_missing(%)
 		}
 
 		if ($is_optional) {
-			print "Warning: better to also install \"$prog\".\n";
+			if ($prog =~ /cjk/ ) {
+				print "Warning: For translations PDF, better to install \"$prog\".\n";
+				print "However, doing so will *degrade* English PDF typesetting.\n";
+			} else {
+				print "Warning: better to also install \"$prog\".\n";
+			}
 		} else {
 			print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
 		}
-- 
2.17.1