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

From: Mauro Carvalho Chehab
Date: Fri May 21 2021 - 03:54:48 EST


HI Akira,

Em Fri, 21 May 2021 16:14:19 +0900
Akira Yokosawa <akiyks@xxxxxxxxx> escreveu:

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

Yes. The same LaTeX configuration is applied to all documents.

While the standard Sphinx logic allows just one conf.py, there's
a logic on Linux that allows a per-directory configuration.
Perhaps it would be possible to set the font just for translations.

Yet, this can't be easily done per-translation - Italian
translation for instance doesn't need CJK fonts.

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

Hmm... could you give an example where it looks ugly?

At least on the documents I use to check the PDF output, I was unable
to see any big issue.

Regards,
Mauro

>
> 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@xxxxxxxxx>
> ---
> 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";
> }



Thanks,
Mauro