linux-kernel - [PATCH] docs: sphinx-pre-install: Reword warning on installing cjk font

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <c5652bb4-0bb0-9efa-2b80-a79793a8efa8@gmail.com>
Date:   Fri, 21 May 2021 16:14:19 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Jonathan Corbet <corbet@....net>,
        Mauro Carvalho Chehab <mchehab@...nel.org>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        Akira Yokosawa <akiyks@...il.com>
Subject: [PATCH] docs: sphinx-pre-install: Reword warning on installing cjk
 font

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@...il.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